Gerado do código a cada release · também em /llms-full.txt (Markdown puro para a sua IA) e OpenAPI

API do GereNota

Gerado do código pela suíte (scripts/gera_doc_api.py); versão 0.1.0 · API v1 em https://api.gerenota.com.br · site https://gerenota.com.br. Este arquivo é o llms-full.txt do GereNota: cole-o inteiro no seu assistente ou aponte-o para ele.

Comece aqui: uma nota em cinco chamadas

Tudo fica sob https://api.gerenota.com.br/api/v1 e leva o cabeçalho Authorization: Bearer gnk_live_… (a chave é criada em Painel → Integrações). Guarde a chave numa variável de ambiente; os exemplos usam $GERENOTA_KEY.

1. Quem sou eu. GET /me devolve a conta, o papel efetivo da chave, o plano e o uso das cotas. Se vier 401, a chave está errada ou revogada; se vier 402 RECURSO_FORA_DO_PLANO, o plano da conta não inclui a API — ela entra a partir do Plano Individual, que o dono da conta assina na página Cobrança do painel.
2. Escolha a empresa. A GereNota atende empresas do Simples Nacional e MEI (o cadastro de não optante volta 422 EMPRESA_FORA_DO_SIMPLES). GET /companies lista as empresas emissoras da conta; use o id de uma com status: "ativa" e certificado válido (GET /companies/{id}/status diz se pode emitir). Uma empresa pode ser cadastrada pela API (POST /companies), mas o certificado A1 e a validação são feitos pelo dono no painel: até lá ela não emite.
3. Emita em teste. POST /companies/{id}/nfse com "ambiente": "teste" valida a nota inteira no Sistema Nacional sem efeito fiscal. É o jeito de conferir código de serviço, valores e tomador antes de valer.
4. Emita valendo. A mesma chamada sem ambiente (ou com "producao"), com o cabeçalho Idempotency-Key. A resposta traz numero (o número oficial), chave_acesso e id.
5. Pegue o documento. GET /nfse/{id}/pdf é o DANFSE; GET /nfse/{id}/xml é o XML autorizado; POST /nfse/{id}/enviar-email manda ao cliente.

curl -X POST "https://api.gerenota.com.br/api/v1/companies/$EMPRESA/nfse" \
  -H "Authorization: Bearer $GERENOTA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "dCompet": "2026-09-16",
    "servico": { "cTribNac": "010501", "descricao": "Licença de uso de software — setembro/2026" },
    "valores": { "vServ": "350.00" },
    "tomador": { "tipo": "CNPJ", "documento": "11222333000181", "nome": "Cliente Exemplo Ltda", "email": "financeiro@cliente.com.br" }
  }'

Série, regime tributário e a alíquota do Simples do mês saem do cadastro da empresa; você não os informa na chamada. Empresa do Simples (ME/EPP) ainda sem alíquota nenhuma — nem calculada pelo PGDAS-D, nem confirmada no painel — recebe 422 ALIQUOTA_NAO_CONFIRMADA: o dono autoriza a consulta ao PGDAS-D, ou alguém com acesso fiscal à empresa (dono, operador ou contabilidade) confirma a alíquota no painel — ou você manda valores.pTotTribSN (veja Regras de emissão). O tomador é opcional: sem ele a nota sai sem identificação do cliente, quando a legislação permite.

Autenticação e escopos

• Chave de API (gnk_live_…): criada pelo dono da conta em Painel → Integrações, mostrada uma única vez; só o hash fica guardado. Mande em toda chamada: Authorization: Bearer gnk_live_….
• Escopo por chave: emissao lê e escreve (emitir, cancelar, cadastrar); leitura só lê. Escrever com chave de leitura dá 403.
• Papel efetivo: é sempre o menor entre o escopo da chave e o papel de quem a criou, e uma chave nunca tem o papel de dono. Por isso ações de dono (enviar o certificado A1, validar a empresa, gerir acessos e cobrança) não existem nesta API: são feitas no painel. Pelo mesmo motivo, os erros de limite nunca trazem upgrade para uma chave: o plano que resolve vem só no hint (veja Erros).
• Plano: a API e o conector MCP entram a partir do Plano Individual. A chave de uma conta cujo plano deixou de incluir a API recebe 402 RECURSO_FORA_DO_PLANO em qualquer chamada, com o Plano Individual no hint. No conector MCP, a conexão de uma conta sem o plano para numa página que diz o plano que resolve; se o plano muda com o conector já ligado, cada chamada — menos as de cobrança e a do link do painel, que seguem abertas para a assinatura — responde 403 RECURSO_FORA_DO_PLANO, com o upgrade (o Plano Individual, o preço e o link para assinar) quando quem conectou é o dono da conta; a conexão cai na renovação seguinte, em até 1 hora.
• Revogação: revogar a chave no painel vale na hora; a chamada seguinte recebe 401.
• Não use a chave em código-fonte, em URL nem em log. Uma chave por sistema integrado facilita revogar sem derrubar os outros.
• Assistentes conversacionais (Claude e compatíveis) não usam chave: conectam pelo MCP com login por código no e-mail (veja a última seção).
• Antes da primeira escrita: GET /me devolve escopo (emissao ou leitura) e role; uma chave de leitura recebe 403 em emissão, cancelamento e substituição.

Teste × valendo

• "ambiente": "teste" em POST /companies/{id}/nfse valida a nota inteira no Sistema Nacional (ambiente de produção restrita do gov.br) e devolve a mesma estrutura de resposta, sem efeito fiscal: não conta na cota, não aparece em GET /nfse nem nos totais, e o PDF sai com marca de rascunho. Notas de teste são apagadas em 24 horas.
• Sem ambiente (ou "producao"), a nota é emitida de verdade: numerada, assinada com o certificado da empresa e transmitida ao gov.br.
• Prévia sem transmitir: POST /companies/{id}/nfse/rascunho-pdf recebe o mesmo corpo da emissão e devolve um PDF de rascunho gerado localmente, sem tocar o Sistema Nacional. Use para mostrar ao usuário antes de emitir.
• O que o Sistema Nacional rejeita em teste rejeitaria valendo: um 422 com o código do gov.br (por exemplo E0312, município não aderente para o serviço) na mensagem é o mesmo nos dois ambientes.

Idempotência: nunca emita duas vezes

• Mande o cabeçalho Idempotency-Key com um valor único por intenção de emissão (um UUID serve) em POST /companies/{id}/nfse e em POST /nfse/{id}/substituir.
• No cancelamento (POST /nfse/{id}/cancelar) a chave vale o mesmo: repetir com ela devolve o mesmo cancelamento (200, X-Idempotent-Replay: true) em vez do 409 NFSE_NAO_ATIVA da nota já cancelada, e a chamada simultânea recebe 409 CANCELAMENTO_EM_ANDAMENTO. Ali a chave é da nota: a mesma chave usada numa emissão não se confunde com ela.
• Repetir a chamada com a mesma chave devolve a mesma nota (resposta idêntica, cabeçalho X-Idempotent-Replay: true) por 24 horas. É seguro repetir depois de timeout, queda de rede ou 5xx.
• Uma chamada simultânea com a mesma chave, enquanto a primeira ainda não terminou, recebe 409 EMISSAO_EM_ANDAMENTO. Espere a primeira responder e repita, se precisar.
• Se a emissão falhou (por exemplo, 422 de validação), a chave é liberada: a próxima chamada com ela tenta de novo.
• Se o Sistema Nacional não responder a tempo, a emissão confere a nota pelo número da DPS antes de responder: se ela saiu, a resposta é a nota. Sem como confirmar, vem 503 EMISSAO_INCERTA e a chave não é liberada: repita com a mesma chave em alguns minutos — a repetição confere primeiro se a nota saiu e, se não saiu, emite com o mesmo número. Uma chave nova poderia emitir uma segunda nota.
• A chave é por conta: duas contas podem usar o mesmo valor sem se cruzar. Quem tem acesso a só algumas empresas (o membro com recorte, ou quem opera uma empresa compartilhada por outra conta) tem as chaves dele: elas nunca se cruzam com as do dono da conta nem com as de outra pessoa.
• Sem o cabeçalho, cada chamada emite uma nota nova. Em integrações automáticas isso é um erro caro: use sempre.

Erros

Todo erro volta com este envelope, em qualquer status 4xx ou 5xx:

{ "code": "EMPRESA_NAO_ENCONTRADA", "message": "Empresa não encontrada", "hint": "…", "field": "…", "erros": [ … ], "volta_em": "…", "upgrade": { … } }

• code é estável: programe por ele. message é para mostrar a uma pessoa. hint diz como resolver quando há o que fazer. field aponta o campo do corpo, quando houver. erros (só no 422) detalha cada campo: loc, type, msg. volta_em e upgrade só aparecem nos erros de limite (veja o fim desta seção).
• Status: 401 chave ausente, inválida ou revogada · 402 plano sem o recurso, teto do plano atingido (empresas, automações, acessos), cota do mês esgotada ou conta com a renovação vencida (CONTA_BLOQUEADA, a de quem é dono da empresa compartilhada inclusive) · 403 escopo de leitura tentando escrever, papel insuficiente, empresa fora do acesso da chave ou, no conector MCP, plano sem o conector · 404 não existe nesta conta · 409 conflito com o estado atual (nota já cancelada, empresa inativa, emissão em andamento, arquivo indisponível, links abertos no teto) · 413 arquivo acima de 8 MB · 422 dados inválidos ou rejeição do Sistema Nacional · 429 muitas chamadas, ou o teto do dia acabou · 502 o Sistema Nacional ou a Receita respondeu com erro · 503 serviço externo indisponível.
• Rejeição do gov.br: vem como 422 com o código oficial (E0312, E0625, …) no code e a explicação na message. Corrija o corpo e repita; a Idempotency-Key é liberada em falha. A partir de 1º/11/2026, a recusa de uma ME ou EPP de cidade sem adesão por uma das regras do convênio do município (E0016, E0037, E0038 ou E0039) não se corrige no corpo: a message explica, e repetir a mesma nota não muda o resultado.
• Códigos que valem conhecer: EMPRESA_NAO_ENCONTRADA, EMPRESA_NAO_ATIVA, EMPRESA_FORA_DO_RECORTE, EMISSAO_EM_ANDAMENTO, EMISSAO_INCERTA (503: repita com a mesma Idempotency-Key), NFSE_NAO_ENCONTRADA, ARQUIVO_INDISPONIVEL, RECURSO_FORA_DO_PLANO, LIMITE_DO_PLANO, COTA_ESGOTADA, COTA_CONSULTAS_ESGOTADA, DOCUMENTO_INVALIDO, RATE_LIMIT, DADOS_INVALIDOS.
• Dos tetos de uso (a proteção das consultas e dos envios pagos): LIMITE_CONSULTAS_DIA (429: as consultas de CNPJ/CPF do dia da conta acabaram), CONSULTAS_PAUSADAS (503: as consultas da plataforma pararam até a virada do dia; siga com o cadastro manual), LIMITE_EMAILS_DO_DIA (429: 100 notas por e-mail por dia) e LIMITE_RODAR_AGORA (429: o “rodar agora” de uma automação de relatório, 3 vezes por dia). Os 429 do dia renovam à 0h de Brasília, o instante que vem em volta_em.
• Do cliente pelo CNPJ (o cadastro e a emissão só com o CNPJ, que buscam na Receita): CNPJ_NAO_ENCONTRADO_NA_RECEITA (422: a Receita não conhece o número — confira os dígitos com o cliente; a resposta da Receita é cobrada) e TOMADOR_SEM_NOME (422: a prévia em PDF, a substituição e as automações continuam exigindo o tomador.nome). Quando a busca não sai — COTA_CONSULTAS_ESGOTADA, LIMITE_CONSULTAS_DIA, RATE_LIMIT, CONSULTAS_PAUSADAS, Receita fora —, o erro aponta o field do nome (nome no cadastro, tomador.nome na emissão), com o volta_em e o upgrade do limite quando há: mande o nome e o pedido segue sem a Receita, sem custo. NOME_OBRIGATORIO (422): CPF sem nome.
• Só Simples Nacional e MEI: EMPRESA_FORA_DO_SIMPLES (422) no cadastro de não optante (o regime 1, ou o CNPJ que a consulta à Receita da conta mostrou como não optante) e na emissão da empresa que saiu do Simples — o hint diz o caminho: quando ela voltar, o “Conferir na Receita” (painel, Empresas → Editar tributação) libera na hora.
• Do Simples e dos pacotes: ALIQUOTA_NAO_CONFIRMADA (422: empresa ME/EPP sem alíquota nenhuma — o hint diz os três caminhos), TETO_DIARIO_PGDAS (429: 3 consultas pagas do PGDAS-D por empresa e dia pela API — volta à 0h de Brasília, em volta_em), PGDAS_PAUSADO (503: as consultas pagas da plataforma pararam até a virada do dia), ACEITE_SO_DO_DONO (403: só o dono assina o termo de consulta), EXPORT_NAO_CONCLUIDO (409: o pacote ainda não está pronto — ou terminou em erro, e aí é preciso pedir de novo) e VOLUME_NAO_ENCONTRADO (404: volume fora da lista do pacote).

Erros de limite: quando volta e o plano que resolve

Os erros de limite — LIMITE_DO_PLANO (402: empresas, automações ou acessos no teto do plano), COTA_ESGOTADA (402: a cota de notas do mês), RECURSO_FORA_DO_PLANO (402: relatórios automáticos ou API fora do plano; 403 no conector MCP da conta cujo plano não o inclui), COTA_CONSULTAS_ESGOTADA (402), LIMITE_CONSULTAS_DIA (429), LIMITE_DE_LINKS_DO_DIA (429) e LINKS_ABERTOS_NO_TETO (409) — podem trazer, além da dica, dois campos:

• volta_em: quando o limite volta sozinho, em ISO 8601 e UTC — "2026-11-01T03:00:00Z" é a 0h de Brasília do dia 1º de novembro. Vem nas cotas do mês (COTA_ESGOTADA e COTA_CONSULTAS_ESGOTADA: a 0h de Brasília do dia 1º) e em todo teto do dia (LIMITE_CONSULTAS_DIA e LIMITE_DE_LINKS_DO_DIA, e também LIMITE_EMAILS_DO_DIA, LIMITE_RODAR_AGORA e TETO_DIARIO_PGDAS, que não têm plano que resolva: a 0h de Brasília do dia seguinte), para qualquer credencial: é o instante para agendar a nova tentativa. O limite que só libera com uma ação — remover uma empresa, excluir uma automação, usar ou cancelar um link, assinar outro plano — vem sem ele.
• upgrade: o plano que resolve o limite batido (a regra de cada limite está em Limites, cotas e custos). plano traz id, nome, rotulo (o nome pronto para um texto: “Plano Multi”), preco_base (o preço do mês em reais, como texto: "79.90") e preco_anual (o do ciclo anual, ou null); limite_no_plano é o teto daquele recurso no plano que resolve (null = sem limite, como as notas dos planos pagos, ou recurso incluído, como a API); link abre a página Cobrança do painel com o plano que resolve já marcado e o motivo do limite — os dois vão na URL (https://app.gerenota.com.br/billing?plano=plan_multi&motivo=empresas). O motivo é um de: empresas, automacoes, acessos, notas, consultas, consultas_dia, links, relatorios, api.
• Só o dono da conta recebe o upgrade — no login do dono, pelo painel ou pelo conector MCP. A chave de API nunca é do dono (veja Autenticação): com ela o upgrade não vem, e o hint já nomeia o plano que resolve, sem preço, e diz quem assina (“quem assina é o dono da conta, na página Cobrança”) — é o texto para mostrar a quem usa o seu sistema. Numa empresa compartilhada vale o papel de quem a acessa: quem opera a empresa de outra conta também não recebe.
• Sem plano que resolva, sem upgrade, nem para o dono: o Plano Escritório no teto, os planos fora da vitrine (como o Plano Cortesia) e os tetos que são só de segurança — as consultas à Receita e os links de cadastro dos planos pagos. O hint dá o caminho sem plano e, onde cabe, o contato: “Para mais, fale com a gente: faleaqui@gerenota.com.br”.

A segunda empresa no Plano Individual (que inclui 1; o Plano Multi, 5), como o dono recebe — 402 LIMITE_DO_PLANO com o upgrade:

{
  "code": "LIMITE_DO_PLANO",
  "message": "O Plano Individual inclui 1 empresa — e a conta já usa 1",
  "hint": "No Plano Multi cabem até 5 empresas; quem assina é o dono da conta, na página Cobrança — ou libere uma vaga removendo uma empresa que não usa (inclusive na lista de espera)",
  "upgrade": {
    "plano": { "id": "plan_multi", "nome": "Multi", "rotulo": "Plano Multi", "preco_base": "79.90", "preco_anual": "799.00" },
    "limite_no_plano": 5,
    "link": "https://app.gerenota.com.br/billing?plano=plan_multi&motivo=empresas"
  }
}

O mesmo pedido pela chave de API, ou por quem não é dono: a mesma mensagem e a mesma dica, sem o upgrade.

{
  "code": "LIMITE_DO_PLANO",
  "message": "O Plano Individual inclui 1 empresa — e a conta já usa 1",
  "hint": "No Plano Multi cabem até 5 empresas; quem assina é o dono da conta, na página Cobrança — ou libere uma vaga removendo uma empresa que não usa (inclusive na lista de espera)"
}

E um limite que volta sozinho, sem plano que resolva — as consultas do mês do Plano Individual, um teto de segurança:

{
  "code": "COTA_CONSULTAS_ESGOTADA",
  "message": "As 20 consultas de CNPJ/CPF do mês do Plano Individual acabaram",
  "hint": "O CNPJ consultado nos últimos 7 dias e o CPF nas últimas 24 h saem do cache sem gastar; o limite renova no dia 1º. Para mais, fale com a gente: faleaqui@gerenota.com.br",
  "volta_em": "2026-11-01T03:00:00Z"
}

Regras de emissão que você precisa saber

• dCompet: a data da competência do serviço, AAAA-MM-DD. Define o mês em que a nota conta.
• servico.cTribNac: o código de tributação nacional do serviço, 6 dígitos sem pontos (ex.: 010501 = licenciamento de software). Ele decide alíquota, retenções e se o município do serviço precisa ser informado. servico.descricao é o texto que vai na nota.
• Não sabe o código? POST /servicos/sugerir com a descrição livre do serviço devolve os candidatos do catálogo nacional com o código e a semelhança; GET /servicos/codigo/{codigo} confere um código que veio de fora e diz se o ISS é devido no local da prestação. Confirme o candidato antes de emitir: o código decide a tributação.
• Valores como texto decimal com ponto e duas casas: "350.00". valores.vServ é o valor do serviço; descontos incondicionais e condicionais são opcionais.
• Vários itens: servico.itens (descrição, quantidade, valor unitário) soma o total e escreve o detalhamento nas informações complementares; nesse caso não mande vServ.
• Tributação: tributacao.tribISSQN (1 = operação tributável) e tributacao.tpRetISSQN (1 = ISS não retido, 2 = retido pelo tomador, 3 = pelo intermediário). Quando há retenção numa ME/EPP do Simples, omita pAliq: a plataforma preenche com o ISS efetivo do mês da prestação — o da competência (dCompet), pela regra da retenção (LC 123, art. 21, § 4º, I). A nota do mês da alíquota em vigor (mes.mes, normalmente o corrente) leva o de mes.p_aliq_iss; a de outro mês, o ISS daquele mês: o do historico de GET /companies/{id}/aliquotas ou, na empresa em modo automático (tributacao_modo auto), o da conta pelas declarações PGDAS-D arquivadas — a mesma do dia 1º, com o anexo e o impedimento daquele período; o mês calculado entra no historico quando uma nota retida sai com esse número. Fora disso (modo manual sem aquele mês confirmado — inclusive o corrente, antes da confirmação —, ou quando a conta pelas declarações não fecha para o período) a plataforma não tem o ISS daquele mês e não usa o de outro: 422 ALIQUOTA_ISS_DO_MES_AUSENTE — mande a pAliq daquele mês (o contador tem). A mesma resposta vem quando o mês da nota não tem o ISS confirmado. Com o ISS fora do DAS — a declaração mostra o impedimento pelo sublimite, ou o cadastro tem reg_ap_trib_sn 2 ou 3 —, a nota vai sem pAliq e o município aplica a dele. Fora do Simples, informe pAliq (a alíquota do município). Sem retenção, não mande pAliq (422 ALIQUOTA_SEM_RETENCAO). O percentual total de tributos do Simples (pTotTribSN) sai da alíquota do mês em uso da empresa; só mande para sobrepor.
• Alíquota do Simples (ME/EPP): a da nota é a do mês, pela regra da retenção (Resolução CGSN 140/2018, art. 27): a faixa vem da receita bruta dos 12 meses que a lei manda contar (os que antecedem o mês anterior ao da nota — também de 2027 em diante, quando passa a valer a tabela da Resolução CGSN 190/2026; da declaração de janeiro de 2027 em diante, a declaração de um mês só confere aquele mesmo mês, já fechado, sem mudar a alíquota em vigor), lida das declarações PGDAS-D da empresa. Ela é fixada no dia 1º, e a do mês seguinte é calculada no dia 21, quando a declaração do mês anterior já foi transmitida. Só muda no meio do mês em três casos, com aviso ao dono e a quem cuida da empresa por outra conta (operador e contabilidade) — o da correção pela declaração sempre; os outros dois, salvo se “Alíquota do mês e conferências” estiver desligado nas Notificações de quem recebe: quando ela era estimada (faltava uma declaração) e a declaração chega; quando a do mês ainda não tinha saído (as notas usavam a do mês anterior) e a declaração chega; ou quando a conta por uma declaração dá outra alíquota — aí muda na hora, e o aviso traz as notas com retenção afetadas. GET /companies/{id}/aliquotas mostra a alíquota em vigor com a conta, a próxima e a última conferência. No regime de caixa, cada declaração traz os dois números do mês — rpa_competencia (o faturado, que forma a RBT12 e a alíquota) e rpa_caixa (o recebido, base do DAS) — em GET /companies/{id}/pgdas/declaracoes e nas declaracoes do dossiê; a conferência da receita compara as notas com o faturado e traz o recebido ao lado (conferencia.receita.rpa_caixa). Se o seu sistema manda pTotTribSN ou pAliq diferente da calculada — nem a do mês da prestação, nem a em uso (mais de 0,01 ponto) —, a nota sai como veio e o dono recebe um aviso por mês. Empresa ME/EPP sem alíquota nenhuma (nem pelo PGDAS-D, nem confirmada) recebe 422 ALIQUOTA_NAO_CONFIRMADA; com a alíquota de um mês anterior ainda gravada (a do mês não saiu), a nota sai com ela no total (pTotTribSN) — a retida sem pAliq, não: o ISS de outro mês não vai à nota (veja a Tributação, acima). O MEI não tem alíquota efetiva: a nota dele sai sem pTotTribSN (vai indTotTrib 0 — o Sistema Nacional recusa o percentual para o MEI, E0710) e sem ISS retido (E0583); mandar um ou outro volta 422 MEI_NAO_INFORMA_PTOTTRIBSN ou MEI_NAO_TEM_RETENCAO.
• Tomador: opcional. tipo CNPJ, CPF, NIF (estrangeiro com identificação) ou naoNIF; documento sem pontuação (o CPF com 11 números; o CNPJ com 14 caracteres, que podem ter letras nas 12 primeiras posições); endereço obrigatório para alguns serviços (a validação em teste avisa). Tomadores salvos em POST /tomadores podem ser reaproveitados, e GET /tomadores/{documento}/sugestao devolve o que a última nota daquele cliente usou.
• Local da prestação: para os serviços em que o ISS é devido onde o serviço acontece (construção, eventos, limpeza etc.), mande servico.cMunPrestacao com o código IBGE do município; GET /consultas/municipio?q=&uf= acha o código pelo nome e GET /municipios/{cmun} diz se o município já aderiu ao Sistema Nacional.
• Quem preenche o resto: série, regime tributário, a alíquota do Simples do mês e a inscrição municipal vêm do cadastro da empresa; o número da nota é dado pelo gov.br e volta em numero.

Documentos e entregas

• DANFSE: GET /nfse/{id}/pdf (binário application/pdf). Nota de teste sai marcada como rascunho; nota cancelada sai com a marca de cancelamento.
• XML: GET /nfse/{id}/xml é o XML da NFS-e autorizado pelo gov.br.
• E-mail ao cliente: POST /nfse/{id}/enviar-email manda o PDF e o XML; sem para, vai para o e-mail do tomador cadastrado. O envio fica registrado na trilha da nota.
• WhatsApp é canal do próprio GereNota: os avisos chegam lá a quem os recebe — o dono da conta, as pessoas escolhidas no bloco Avisos de cada automação e, numa empresa compartilhada, quem tem acesso a ela pelo papel —, cada um com as Notificações da própria conta; não há envio por API para números arbitrários.
• Lote para o contador: POST /exports gera um ZIP por período. É assíncrono: a resposta 202 traz o id, a montagem entra numa fila justa entre as contas, e você consulta GET /exports/{id} até status: "concluido". O download (GET /exports/{id}/download) responde 302 para um link temporário do arquivo: siga o redirecionamento (curl -L -o pacote.zip) e, para baixar de novo, chame a rota de novo. A faixa é a mesma da listagem: periodo_por (competencia, emissao ou evento) com de/ate. Dentro: relatorio.html (o relatório do período para ler e imprimir — cabeçalho com a empresa, totais, fechamento por competência e uma linha por nota, cada uma com link para os arquivos do próprio pacote; a soma é só das ativas), relatorio.csv, as notas ATIVAS na raiz de xml/ e pdf/, canceladas e substituídas em xml/canceladas/ e xml/substituidas/, e eventos/ com o XML de cada cancelamento ou substituição — quem importa xml/ sem recursão recebe só o que vale. Os arquivos levam a data de emissão (Brasília) no nome, e o relatorio.csv é do contador, pronto para o Excel em português: cabeçalhos em português, códigos por extenso (situação, tributação e retenção do ISS, tributos aproximados), o ISS retido em reais (o valor apurado na nota, que é o que se soma na planilha), competência dd/mm/aaaa e as outras datas dd/mm/aaaa hh:mm em Brasília, vírgula decimal, texto sem quebras de linha, a nota que substituiu pelo número, e chave, CPF/CNPJ e código do serviço como texto por fórmula (="…", para o Excel não perder dígitos) — para máquina, use o JSON (nomes técnicos, UTC, ponto decimal). GET /reports/nfse devolve o relatório do período na hora; com formato=csv, o CSV vem completo, em streaming (o limite vale só para a lista do JSON).
• Pacote grande nunca é cortado: acima de 2.000 notas (1.000 quando os PDFs vão junto) o pacote sai em volumes — um por mês, no eixo do recorte (competência, emissão ou evento), e um mês grande em partes, na ordem de numeração. O primeiro item é o resumo: relatorio.html do período inteiro, com a tabela dos volumes e a regra da divisão numa frase, e o relatorio.csv completo; cada volume traz a sua listagem.html, listagem.csv, xml/, pdf/ e eventos/. Baixe com download?volume=resumo, 1, 2, … Quem pediu recebe o e-mail com o relatório anexo e os arquivos por links que valem 30 dias, na própria conta (numa empresa compartilhada, a pessoa com acesso; por chave de API, quem criou a chave), se o aviso “Exportação pronta” estiver ligado nas Notificações dela — e, se a exportação falhar, o aviso de que falhou. Para saber antes o que vai sair, GET /nfse/agregado com o mesmo recorte traz exportacao: notas por volume, quantos arquivos, a estimativa em segundos e a contagem mês a mês.
• O que mudou desde a última sincronização: GET /nfse/eventos?desde=<maior cursor da página anterior> lista os cancelamentos e substituições da conta, uma linha por mudança, com a situação atual da nota e se o XML do evento está disponível. O cursor é o campo cursor (quando o evento entrou na plataforma), NÃO a hora oficial dh: o cancelamento feito pela prefeitura chega na importação do dia seguinte com data anterior, e quem paginasse pela hora oficial nunca o receberia. Com desde, a lista vem na ordem de entrada; sem ele, na ordem cronológica oficial. Não precisa guardar cópia das situações para descobrir o que foi cancelado depois de enviado ao contador. Vale qualquer via: o que foi feito aqui, no portal do gov.br ou pela prefeitura (cancelamento deferido por análise fiscal e cancelamento por ofício). Cada evento traz descricao com o nome oficial e muda_situacao; todos=true inclui os que só registram histórico, como a rejeição do tomador e o bloqueio por ofício. A pasta eventos/ do ZIP continua só com a prova das mudanças de situação.
• Situação com data e prova (16/set): a nota diz quando saiu de ativa — cancelada_em e substituida_em, na hora oficial do evento (o dhEvento do gov.br) — e substituida_por aponta a nota que entrou no lugar, também nas importadas. GET /nfse/{id}/eventos/{evento_id}/xml baixa o XML do evento. Importante: o XML da nota continua sendo o autorizado, idêntico depois do cancelamento; um sistema contábil que só recebe a nota a importa como válida — mande o evento junto. Para achar o que mudou num período use periodo_por=evento (status=cancelada&periodo_por=evento&de=2026-08&ate=2026-08 = cancelado em agosto), com ordem=evento_desc para o mais recente primeiro; cada nota fora de ativa traz evento_situacao (qual evento a tirou de ativa) e, na substituída, substituida_por_numero. As bordas de de/ate valem no horário de Brasília. GET /nfse/agregado traz por_status; o faturamento válido do período é por_status.ativa.

Automações

• Uma automação emite sozinha, no dia programado, uma nota com empresa, tomador, serviço e valor fixos (ou com valor variável, que pede confirmação ao dono antes de sair). É o caminho para mensalidades e contratos.
• POST /automations/recorrente cria uma: tomador (documento), dia do mês (1 a 28), valor (ou sem valor, para confirmar a cada rodada) e, se quiser, o código de serviço e a descrição; sem eles, usa o que a última nota daquele cliente usou — numa conta com mais de uma empresa, mande o company_id (na query) para a nota-base ser a daquela empresa. GET /automations lista as da conta; PATCH /automations/{id} edita e pausa ("ativo": false) ou reativa; DELETE exclui (o histórico de execuções vai junto; as notas já emitidas ficam); POST /automations/{id}/run roda agora, fora da agenda, e emite de verdade; GET /automations/{id}/runs traz o histórico com o desfecho de cada rodada e um motivo legível quando falhou.
• O relatório mensal por e-mail é a outra automação. Agenda-se no painel (Automações → Enviar um relatório por e-mail) ou pelo conector MCP (nfse_relatorio_agendado); as rotas que o painel usa — POST /report-definitions guarda o recorte (periodo = mes_fechado ou mes_atual, periodo_por = competencia, emissao ou evento, status, company_id, destinos e incluir_zip) e POST /automations agenda o dia — ainda não entram na referência abaixo. No dia, às 08:00 (Brasília), o pacote entra na fila e o e-mail sai quando ele fica pronto: o relatório em HTML (para ler) e em CSV (para o Excel) anexos, com o nome do arquivo trazendo a empresa e o mês; com incluir_zip, vai o mesmo pacote da exportação, com os XMLs por situação e a prova de cada cancelamento — anexo até 8 MB, por link de 30 dias acima disso. Um mês grande não é cortado: sai em partes, na ordem de numeração, e o resumo explica a divisão. O e-mail vai para os destinos da definição sempre: é a entrega, não um aviso — nem os avisos da automação nem a preferência “Relatório mensal” da conta o calam (a preferência governa só o cartão do WhatsApp; a falha do relatório é aviso do tipo “Falha de automação”). Em runs, a execução nasce em_fila e, na entrega, vira o que o provedor de e-mail aceitou: relatorio_enviado (todos os destinos), relatorio_parcial (parte deles — erro_msg diz quem ficou sem) ou relatorio_nao_entregue (nenhum: conta como falha e tenta de novo em 1 hora, inclusive no mesmo dia); a mesma definição não gera dois relatórios automáticos no mesmo dia (repetida), e POST /automations/{id}/run repete de propósito. periodo_por: "evento" manda o que foi CANCELADO ou SUBSTITUÍDO no mês — o recorte que o contador usa para refazer o fechamento. Notas de teste nunca entram.
• Automações pausadas continuam contando no limite do plano; para liberar vaga, exclua.
• Os avisos de cada rodada (emitida, falhou, precisa de valor) chegam por e-mail e WhatsApp a quem o bloco Avisos da automação escolheu — quem criou, as pessoas da conta e, numa empresa compartilhada, o operador que a acessa por outra conta; a integração acompanha por runs.
• Numa empresa do Simples (ME/EPP) ainda sem alíquota nenhuma, a rodada de emissão sai pulada, com erro_codigo ALIQUOTA_NAO_CONFIRMADA: tenta de novo no dia seguinte, avisa o dono e não conta como falha nem pausa a automação.

Emitir em lote

• Um lote é uma planilha (ou as linhas em JSON) que vira notas propostas, uma por linha. Nada é emitido até a confirmação: a plataforma propõe, e quem emite confere e confirma. A empresa vai no caminho (/companies/{company_id}/lotes), e a empresa compartilhada com você funciona igual.
• POST /companies/{company_id}/lotes recebe a planilha (multipart/form-data, campo file: XLSX ou CSV, até 8 MB). A leitura é em segundo plano: em alguns segundos o lote passa de lendo a em_revisao. O modelo do GereNota (baixe no painel, em Emitir nota → Em lote) é lido sempre na hora; a planilha de um formato que a plataforma ainda não conhece passa por aprendendo, e a conferência da leitura (“Entendi assim”) é feita no painel. Sem arquivo, POST /companies/{company_id}/lotes/linhas recebe até 200 linhas com os mesmos campos da planilha (documento e valor obrigatórios; nome obrigatório no CPF; data, descricao, codigo_servico, email, endereco e cep opcionais).
• GET /companies/{company_id}/lotes/{lote_id}/itens traz as linhas: a nota proposta, a situação (proposto = pronta) e o que falta em pendencias. Ficam de fora por padrão a linha repetida no arquivo (repetida) e a que já tem nota do mesmo cliente, valor e mês (ja_tem_nota, contando: três sessões iguais no mês com uma nota emitida marcam só uma linha). O e-mail da linha vai na nota e é para onde ela é enviada; sem ele, vale o do cadastro do cliente. O código do serviço vem da planilha ou das notas anteriores do cliente; sem nenhum dos dois, a linha precisa de dados.
• POST /companies/{company_id}/lotes/{lote_id}/confirmar põe as linhas prontas na fila, com a data da nota fixada na confirmação (a data de cada linha, por padrão). A fila emite uma nota por vez pelo Sistema Nacional e manda o PDF e o XML ao e-mail do cliente; GET /companies/{company_id}/lotes/{lote_id} é o andamento (emitindo → concluido). A linha recusada traz o motivo em recusa; a resposta que não veio do Sistema Nacional é conferida com o mesmo número da DPS, e a nota nunca sai em dobro. O cliente novo entra no cadastro da conta na confirmação.
• Confirmam o dono, o operador e a contabilidade com “Pode emitir notas”; a contabilidade sem a opção monta o lote e o envia para quem pode emitir, pelo painel. O plano Free confirma dentro da cota do mês (402 COTA_DO_LOTE com erros[0].restam).
• POST /companies/{company_id}/lotes/{lote_id}/cancelar descarta o lote antes da confirmação e, depois dela, tira da fila só o que ainda não saiu: as notas emitidas continuam valendo e se cancelam uma a uma.
• O arquivo fica guardado até o lote terminar, por no máximo 7 dias; depois, ficam as notas e a ligação de cada uma com a linha (lote em GET /nfse/{nfse_id}, e origem=lote em GET /nfse).

Limites, cotas e custos

• Por minuto: buscas de CNPJ/CPF, 10 por minuto por conta, venham de onde vierem; o envio da nota por e-mail (POST /nfse/{id}/enviar-email), 10 por minuto por conta; demais rotas sem teto fixo, mas uso abusivo recebe 429 RATE_LIMIT. Repita depois de alguns segundos.
• Por dia (o dia de Brasília, que renova à 0h — o instante que vem em volta_em): consultas em tempo real à Receita — Plano Free 3, Plano Individual, Plano Multi e Plano Cortesia 10, Plano Escritório 30 por conta (429 LIMITE_CONSULTAS_DIA); o teto técnico de 300 buscas de CNPJ por conta, igual em todos os planos, contra uso automatizado — conta toda busca, do cache ou não, inclusive a do CNPJ que não existe; os links de cadastro ficam fora (429 LIMITE_CONSULTAS_DIA, sem upgrade); o envio da nota por e-mail, 100 por conta (429 LIMITE_EMAILS_DO_DIA).
• Por mês (plano): consultas em tempo real à Receita — o CPF e o CNPJ que ainda não está no cadastro mensal: Plano Free 5, Plano Individual 20, Plano Multi e Plano Cortesia 60, Plano Escritório 200 —, somando todas as portas da conta: esta API, o painel, os links de cadastro e o WhatsApp; notas — Plano Free 5, planos pagos sem teto; empresas, automações e acessos conforme o plano. O mês é o de Brasília: a contagem recomeça à 0h do dia 1º no horário de Brasília (a nota das 22h do último dia ainda conta no mês dela), e a cota esgotada — 402 COTA_ESGOTADA nas notas, 402 COTA_CONSULTAS_ESGOTADA nas consultas — traz esse instante em volta_em. GET /me mostra uso e teto de cada um (e, ao dono da conta, o upgrade do limite já no teto); estourar dá 402 com o code e a saída no hint.
• Links de cadastro — a página em que um terceiro manda os dados: o link de empresa (o cadastro completo da empresa emissora, que consulta a Receita) e o de cliente (o tomador); o link só do certificado fica fora destes tetos. São criados no painel, no conector MCP (nfse_link_empresa, nfse_link_tomador) e no WhatsApp. Por dia, os dois tipos somados: Plano Free 3, planos pagos 10 (429 LIMITE_DE_LINKS_DO_DIA, com volta_em). Abertos ao mesmo tempo: os de cliente, Plano Free 3 e planos pagos 10; os de empresa, Plano Free 1 e planos pagos até 5, nunca mais que as vagas de empresa livres no plano (409 LINKS_ABERTOS_NO_TETO, sem volta_em: a vaga volta quando um link é usado, cancelado ou vence).
• O plano que resolve: quando um plano maior resolve o limite batido, o hint o nomeia, sem preço, e o dono da conta recebe também o upgrade, com o preço e o link para assinar (veja Erros). É o plano mais barato, acima do atual, em que cabem o uso de hoje e o que o pedido traria (num convite para várias empresas, todos os acessos dele) e em que a conta inteira cabe — as empresas, as automações e os acessos que ela já tem —, para a assinatura não ser recusada:
  • empresas, automações e acessos (LIMITE_DO_PLANO): pelo teto — as empresas do Plano Free e do Plano Individual (1 em cada) resolvem no Plano Multi;
  • notas (COTA_ESGOTADA, a cota do Plano Free): o Plano Individual, sem teto de notas;
  • relatórios automáticos e API/MCP (RECURSO_FORA_DO_PLANO): o Plano Individual, o primeiro que os inclui;
  • consultas à Receita, do mês e do dia, e links de cadastro: só no Plano Free — o Plano Individual, ou o Plano Multi no link de empresa, que acompanha as vagas de empresa; nos planos pagos esses tetos são de segurança, sem plano que resolva;
  • o Plano Escritório no teto e os planos fora da vitrine (como o Plano Cortesia): nenhum — o hint dá o caminho sem plano e o contato, faleaqui@gerenota.com.br.
• O que custa dinheiro ao GereNota (e por isso tem cota): a consulta em tempo real à Receita — o CPF e o CNPJ que ainda não está no cadastro mensal (os Dados Abertos do CNPJ, que a Receita publica uma vez por mês) —, pela rota de consulta e também quando POST /tomadores ou a emissão recebem o cliente só com o CNPJ (com o nome no corpo, nada é consultado). A busca de CNPJ pelo cadastro mensal não custa e não tem cota (a resposta traz fonte: "gerecnpj" e o mes_referencia); só o teto técnico do dia vale para ela. O mesmo CNPJ no mesmo mês do cadastro, ou consultado em tempo real nos últimos 7 dias, sai do cache sem gastar (a resposta traz de_cache: true); o CPF, só com a mesma data de nascimento e pela mesma conta, nas últimas 24 horas. Quando as consultas em tempo real da plataforma param até a virada do dia, a resposta é 503 CONSULTAS_PAUSADAS — siga com o cadastro manual.
• Declarações PGDAS-D: cada consulta ao Integra Contador custa R$ 0,24 ao GereNota e não entra na cota do plano. A plataforma busca sozinha, em segundo plano, o que falta: as 13 declarações da autorização chegam em poucos minutos, e depois entra uma por mês. Pela API, POST /companies/{id}/pgdas/sync com pa e forcar=true consulta um período específico, com teto de 3 consultas pagas por empresa e dia (429 TETO_DIARIO_PGDAS, com volta_em); sem forcar, o que já está no histórico volta sem custo. Quando as consultas pagas da plataforma param até a virada do dia, a resposta é 503 PGDAS_PAUSADO — a alíquota do mês não muda.
• Exportações: sem teto de notas. Acima de 2.000 notas (1.000 com os PDFs) o pacote sai em volumes; os links do e-mail valem 30 dias.
• Tamanho: upload do certificado A1 até 8 MB (um A1 tem poucos KB); corpo de requisição até 8 MB.
• Paginação: listagens aceitam skip e limit (padrão 50, máximo informado em cada rota) e devolvem o total do filtro quando aplicável.

Versão e changelog

• A API é a v1 (/api/v1). Campos novos podem aparecer a qualquer momento nas respostas: ignore o que não conhece. Campos e rotas existentes não mudam de forma nem de significado dentro da v1; uma mudança incompatível só sai como v2, com as duas convivendo por um período anunciado.
• Este guia é gerado do código a cada release e verificado no CI; se algo aqui diverge do comportamento real, é um defeito nosso: escreva para faleaqui@gerenota.com.br.
• Changelog
  • Mudanças na superfície, geradas do git — a partir de 24/09/2026, cada operação que entra ou sai, os parâmetros de cada uma e os campos de primeiro nível dos esquemas aparecem aqui, pelo dia em que mudaram (tirado do histórico de docs/api/superficie.json); campo dentro de objeto livre e valor novo de uma lista de valores ficam nas entradas escritas à mão:
    • 13/10/2026 — campos novos em CompanyOut: pendencia_da_ativacao; esquemas novos: CompetenciaPropostaOut, LocalPrestacaoOut; campos novos em NfseDetalheOut: local_prestacao; campos novos em SugestaoTomadorOut: competencia_proposta.
    • 12/10/2026 — campos novos em DeclaracaoPgdasDetalheOut: cpp_declarada, efetiva_motivo, falhas_leitura, fator_r_declarado, fator_r_motivo, folhas_mensais, por_anexo, total_geral; campos novos em DeclaracaoPgdasOut: cpp_declarada, efetiva_motivo, falhas_leitura, fator_r_declarado, fator_r_motivo; campos novos em gerenota_api__integra_contador__AtividadeOut: anexo, c_atv_sn, classe, exterior, iss_devido_a, retencao_iss, tributos; operações novas: POST /api/v1/companies/{company_id}/lotes/{lote_id}/entregar; esquemas novos: EmailDoCliente, EntregaRecusada, EntregarIn, EntregarOut; campos novos em EmailDoCliente: itens.
    • 11/10/2026 — operações novas: POST /api/v1/automations/{automation_id}/pular; esquemas novos: AutomacaoPuladaOut, PularIn; esquemas novos: RodarIn; campos novos em MeOut: plano_escritorio.
    • 10/10/2026 — operações novas: GET /api/v1/companies/{company_id}/lotes/{lote_id}/recibo.csv, GET /api/v1/lotes/modelo, PATCH /api/v1/companies/{company_id}/lotes/{lote_id}/itens/{item_id}, POST /api/v1/companies/{company_id}/lotes/{lote_id}/continuar, POST /api/v1/companies/{company_id}/lotes/{lote_id}/itens/acao, POST /api/v1/companies/{company_id}/lotes/{lote_id}/pausar, POST /api/v1/companies/{company_id}/lotes/{lote_id}/validar, PUT /api/v1/companies/{company_id}/lotes/{lote_id}/data; esquemas novos: AcaoEmGrupoIn, AcaoEmGrupoOut, DataIn, EditarItemIn, EnderecoLinhaIn, ValidarIn; operações novas: POST /api/v1/companies/{company_id}/certificado/pedidos; esquemas novos: PedidoIn, PedidoOut.
    • 08/10/2026 — operações novas: GET /api/v1/companies/{company_id}/lotes, GET /api/v1/companies/{company_id}/lotes/{lote_id}, GET /api/v1/companies/{company_id}/lotes/{lote_id}/itens, POST /api/v1/companies/{company_id}/lotes, POST /api/v1/companies/{company_id}/lotes/linhas, POST /api/v1/companies/{company_id}/lotes/{lote_id}/cancelar, POST /api/v1/companies/{company_id}/lotes/{lote_id}/confirmar; esquemas novos: ArquivoDoLoteOut, ContagensDoLoteOut, ItemDoLoteOut, ItensDoLoteOut, LinhaIn, ListaDeLotesOut, LoteDaNotaOut, LoteDeLinhasIn, LoteOut, lotes_post; campos novos em MinhaEmpresaOut: pode_emitir; campos novos em NfseDetalheOut: lote; campos novos em NfseResumoOut: lote.
    • 07/10/2026 — campos novos em ConsultaCnpjOut: data_extracao, mes_referencia; campos novos em ReceitaOut: atualizando, data_extracao, fonte, mes_referencia; campos novos em RegimeSugeridoOut: exclusao_marcada, fonte; campos novos em SocioOut: menor; GET /api/v1/consultas/cnpj/{documento} ganhou o parâmetro confirmar; esquemas novos: NaoAchadoNaReceitaOut, PendenciaDaReceitaOut, ReceitaDoCampoOut, SituacaoNaReceitaOut, SugestaoDaReceitaOut; campos novos em AutomacaoExecucaoOut: observacao; campos novos em AutomacaoRunOut: observacao; campos novos em CompanyOut: receita_aviso_regime; campos novos em SugestaoTomadorOut: situacao_na_receita; campos novos em TomadorCriadoOut: receita_campos, receita_mes, receita_nao_achado, receita_pendente, receita_situacao, receita_sugestoes; campos novos em TomadorDaBuscaOut: receita_campos, receita_mes, receita_nao_achado, receita_pendente, receita_situacao, receita_sugestoes; campos novos em TomadorOut: receita_campos, receita_mes, receita_nao_achado, receita_pendente, receita_situacao, receita_sugestoes.
    • 06/10/2026 — esquemas novos: AvisoOut; campos novos em CodigoServicoOut: tomador_pj_responsavel; campos novos em NfseOut: avisos; campos novos em SugestaoCodigoOut: tomador_pj_responsavel.
    • 02/10/2026 — esquemas novos: TomadorDaBuscaOut; POST /api/v1/automations/recorrente ganhou o parâmetro company_id; campos novos em TomadorDaBuscaOut: de_outras_empresas.
    • 01/10/2026 — esquemas novos: PlanoQueResolveOut, UpgradeOut; campos novos em ErroOut: upgrade, volta_em; esquemas novos: CotaDeNotasOut; campos novos em PlanoOut: upgrade_api_mcp, upgrade_relatorios; campos novos em UsoTetoOut: upgrade.
    • 30/09/2026 — esquemas novos: ReceitaDoCadastroOut, TomadorCriadoOut; campos novos em SugestaoTomadorOut: cadastrado.
    • 29/09/2026 — campos novos em AutomacaoExecucaoOut: erro_msg; campos novos em DossieAliquotasOut: receita_abaixo, receita_por_mes; campos novos em RegimeTributario: receita_abaixo.
    • 28/09/2026 — operações novas: GET /api/v1/exports/{export_id}/link; esquemas novos: LinkDoPacoteOut; GET /api/v1/consultas/cnpj/{documento} ganhou o parâmetro fresco; campos novos em CompanyOut: emissao_parada, fora_do_simples; campos novos em MinhaEmpresaOut: emissao_parada; campos novos em RegimeSugeridoOut: nao_optante_explicito.
    • 27/09/2026 — GET /api/v1/nfse ganhou o parâmetro com_problema; GET /api/v1/nfse/agregado ganhou o parâmetro com_problema; esquemas novos: AlertaNotaOut; campos novos em NfseAgregadoOut: com_problema; campos novos em NfseDetalheOut: alertas, fora_depois_da_entrada; campos novos em NfseResumoOut: alertas, fora_depois_da_entrada, origem.
    • 26/09/2026 — POST /api/v1/nfse/{nfse_id}/cancelar ganhou o parâmetro Idempotency-Key.
    • 24/09/2026 — campos novos em MinhaEmpresaOut: aliquota_iss_fora_do_das.
  • 2026-10-13 — O que falta na empresa pendente: GET /companies e GET /companies/{company_id}/status trazem pendencia_da_ativacao — por que a última validação (POST /companies/{company_id}/validate, o link de cadastro ou a saída da lista de espera) não ativou a empresa: codigo (o do erro da validação, como INSCRICAO_MUNICIPAL_OBRIGATORIA, CERTIFICADO_AUSENTE ou VALIDACAO_REPROVADA), mensagem e em, mais cidade (Cidade/UF) na inscrição municipal e checks (cnpj_confere, dentro_da_validade, handshake_govbr) na validação reprovada. Some quando a empresa é ativada — e quando PATCH /companies/{company_id} troca a cidade ou o regime (o motivo era da cidade de antes). Para validar de novo, POST /companies/{company_id}/validate usa o certificado já enviado. A empresa inativa não guarda a pendência e continua inativa depois de validada (status inativa, com o certificado validado): ela volta a emitir pelo POST /companies/{company_id}/reativar, que confere o limite do plano. inscricao_municipal aceita até 15 caracteres (o limite do leiaute da DPS): acima disso, 422 em POST /companies e no PATCH.
  • 2026-10-13 — A recusa do convênio na automação e no lote: a partir de 1º/11/2026, a recusa por E0016, E0037, E0038 ou E0039 a uma ME/EPP de cidade sem adesão (a mesma régua da mensagem explicada) deixa de contar como falha da automação: a execução sai pulada, com o erro_codigo da regra, e a automação tenta de novo no dia seguinte, sem pausar. No lote, a primeira dessas recusas pausa o lote (estado pausado; pausado.motivo com codigo, mensagem e convenio: regra, cidade e ate, o dia e o mês — DD/MM, horário de Brasília — em que a guarda de 7 dias do arquivo cancela o que falta), e a linha espera em vez de virar recusada; POST /companies/{company_id}/lotes/{lote_id}/continuar tenta de novo. A validação no ambiente de teste para do mesmo jeito. A nota que a automação não emitiu (a recusa do convênio, a cota, a falta da alíquota ou uma falha) é tentada de novo com a competência da data agendada, mesmo depois da virada do mês, e a agenda segue a partir dessa data: a nota do mês seguinte sai no dia dela, sem repetir a competência. Com uma nota esperando, POST /automations/{automation_id}/pular pula essa nota, e a pulada da resposta é a data dela.
  • 2026-10-13 — O lote com mais de 7 dias: GET /companies/{company_id}/lotes/{lote_id}/itens volta a responder para o lote que passou da guarda de 7 dias do arquivo (respondia 500). Depois da guarda, a linha guarda só a ligação com a nota: a emitida traz em tomador o nome e o documento da nota, e do email fica a situação da entrega (status, de, suprimido), sem o endereço. POST /companies/{company_id}/lotes/{lote_id}/entregar passa a valer também depois da guarda: o cliente de cada linha vem da nota, e o endereço não fica na linha (com guardar_no_cadastro, ele vai ao cadastro do cliente; o endereço que voltou vem do alerta da nota). Depois da guarda, POST …/itens/{item_id}/conferir responde 410 LOTE_EXPIRADO (a linha não tem mais a nota), e o recibo.csv traz o cliente e a data pela nota. As respostas do lote (GET /companies/{company_id}/lotes e GET …/lotes/{lote_id}) deixam de trazer conversa, que tinha o número do WhatsApp de quem mandou a planilha.
  • 2026-10-12 — A lista de espera da ME/EPP termina em 1º/11/2026 (Resolução CGSN 191/2026): a partir dessa data, 0h de Brasília, POST /companies e o link de cadastro não põem mais a ME ou a EPP em waitlist pelo município. A que estava na lista sai dela e é validada com o certificado já enviado (passando, fica ativa; senão, pendente), e validate deixa de devolver 409 MUNICIPIO_NAO_ADERENTE. A recusa por E0016, E0037, E0038 ou E0039 a uma ME/EPP de cidade sem adesão, com competência a partir de 1º/11/2026, volta com o code da regra e a mensagem explicada. Até 31/10/2026, nada muda.
  • 2026-10-12 — O e-mail do cliente informado depois da emissão: POST /companies/{company_id}/lotes/{lote_id}/entregar manda, pela fila do lote, o PDF e o XML das notas emitidas que ficaram sem e-mail (email.status = "sem_email") ao e-mail informado de cada cliente — e corrige o e-mail que falhou ou voltou. Valem as travas da revisão (recusados); com guardar_no_cadastro, o e-mail vai ao cadastro do cliente. Acompanhe em email.status (a_enviar, enviando, enviado).
  • 2026-10-12 — O lote confere o “já tem nota” de novo na confirmação: POST /companies/{company_id}/lotes/{lote_id}/confirmar marca como ja_tem_nota (fora do lote) a linha que ganhou nota depois da leitura do arquivo — a mesma nota emitida por outro lote, pelo painel, pela API ou por uma automação — e devolve 409 LOTE_COM_NOTA_NOVA, com as linhas em erros[0].linhas: o lote fica na revisão para conferir e confirmar de novo. Na fila, a linha igual (cliente, valor, data e descrição) que já saiu por outro lote vira ja_tem_nota e não sai.
  • 2026-10-08 — O cadastro mensal da Receita: a busca de CNPJ (GET /consultas/cnpj/{documento}, e o cliente só com o CNPJ em POST /tomadores e na emissão) passa a sair do cadastro mensal da Receita — os Dados Abertos do CNPJ, que a Receita publica uma vez por mês e que podem estar algumas semanas atrás do cadastro do dia — e não gasta mais a cota do plano: a resposta traz fonte: "gerecnpj", mes_referencia e data_extracao (também dentro de receita, com receita.fonte e receita.atualizando). O CNPJ que ainda não está no cadastro do mês (aberto depois da extração), o fresco=true e o CPF vão à consulta em tempo real (fonte: "serpro"), que segue com a cota do mês e o limite do dia do plano; a que vai em tempo real porque o cadastro mensal não respondeu fica por conta da plataforma. Teto técnico novo: 300 buscas de CNPJ por dia por conta, igual em todos os planos, contando também as que saem do cache e o CNPJ que não existe (429 LIMITE_CONSULTAS_DIA, sem upgrade). O cache passa a ser por fonte: o mesmo mês do cadastro mensal (até 35 dias) ou 7 dias da consulta em tempo real, de qualquer conta. Na empresa compartilhada, leitor e contabilidade buscam pelo cadastro mensal; a consulta em tempo real continua do operador. No regime_sugerido, o período do Simples vale pela data: o fim no futuro é a saída já marcada — exclusao_marcada, e a empresa segue optante (antes saía como não optante) —, com fonte; no cadastro mensal, periodos_simples traz só o período mais recente, e ele nunca marca nao_optante_explicito: a recusa do cadastro de não optante e a parada da emissão continuam exigindo a consulta em tempo real. O sócio menor vem como “Sócio menor”, sem nome nem representante (menor: true). GET /companies deixa de trazer o quadro societário em receita.qsa: fica a contagem, receita.qsa_total (os sócios são dado pessoal; a ficha da empresa no painel continua com eles). A conferência do município do MEI (422 MUNICIPIO_DO_MEI_DIFERENTE_DO_CNPJ) só barra com o bloco da Receita confirmado em tempo real. Com completo=true&confirmar=true, o “não optante” do cadastro mensal é confirmado em tempo real antes de voltar, por conta da plataforma — é o que o cadastro de uma empresa usa. As fichas dos clientes acompanham a Receita: em GET /tomadores, o cliente CNPJ comparado com o cadastro mensal ganha receita_campos (a origem de cada campo: espelho, que acompanha a Receita, ou cliente), receita_sugestoes (o que a Receita tem de diferente; o e-mail e o telefone só quando a ficha não tem), receita_situacao (o CNPJ baixado, inapto, suspenso ou nulo — só aviso), receita_pendente, receita_nao_achado e receita_mes; GET /tomadores/{documento}/sugestao ganha situacao_na_receita; GET /companies ganha receita_aviso_regime (a reconferência mensal viu a saída do Simples, a saída marcada ou o MEI que virou ME/EPP — só aviso; a emissão para quando a saída se confirma); e as execuções de automação (GET /automations/{id}/runs e o “rodar agora”) ganham observacao, com o município do cliente que mudou pela Receita. Textos: RATE_LIMIT passa a “Muitas buscas seguidas; aguarde um minuto”, o teto técnico do dia a “Limite de 300 buscas na Receita de hoje atingido”, e as dicas de limite dizem quando ele volta — programe pelo code.
  • 2026-10-06 — MEI, obras e eventos conforme o Anexo I: a nota de empresa MEI sai sem pTotTribSN (vai indTotTrib 0) — o Sistema Nacional recusa o percentual para o MEI (E0710) — e, mandado, volta 422 MEI_NAO_INFORMA_PTOTTRIBSN; a retenção do ISS numa empresa MEI volta 422 MEI_NAO_TEM_RETENCAO (E0583); no cadastro do MEI, regime.reg_esp_trib fica 0 e p_tot_trib_sn e p_aliq_iss ficam nulos; e o MEI não entra mais na lista de espera (status waitlist) em município que não emite pelo Sistema Nacional — o MEI emite pelo Emissor Nacional em qualquer município. SERVICO_EXIGE_DADOS_DA_OBRA passa a valer também para 07.05.01, 07.05.02, 07.06.01, 07.06.02, 07.07.01, 07.08.01, 07.17.01, 14.14.03 e 14.14.04, e SERVICO_EXIGE_DADOS_DO_EVENTO, para o 12.13.01 (regras 340 e 357 do Anexo I).
  • 2026-10-01 — O plano que resolve e quando o limite volta: os erros de limite — LIMITE_DO_PLANO, COTA_ESGOTADA, RECURSO_FORA_DO_PLANO (também o 403 do conector MCP), COTA_CONSULTAS_ESGOTADA, LIMITE_CONSULTAS_DIA, LIMITE_DE_LINKS_DO_DIA e LINKS_ABERTOS_NO_TETO — ganham volta_em, o instante em UTC em que o limite volta sozinho (nas cotas do mês, a 0h de Brasília do dia 1º; nos tetos do dia, a 0h do dia seguinte), e upgrade, o plano que resolve, só para o dono da conta (nunca para a chave de API): upgrade.plano com id, nome, rotulo (“Plano Individual”), preco_base e preco_anual (em reais, como texto), upgrade.limite_no_plano (null = sem limite, ou recurso incluído) e upgrade.link (…/billing?plano=…&motivo=…, com o motivo de uma lista fechada: empresas, automacoes, acessos, notas, consultas, consultas_dia, links, relatorios, api). Os outros tetos do dia — LIMITE_EMAILS_DO_DIA, LIMITE_RODAR_AGORA e TETO_DIARIO_PGDAS — ganham só o volta_em. No GET /me do dono, o mesmo objeto em plano.empresas.upgrade, plano.automacoes.upgrade, plano.acessos.upgrade e plano.notas.upgrade (o limite já no teto: o plano em que o próximo item cabe) e em plano.upgrade_relatorios e plano.upgrade_api_mcp (o recurso que o plano não inclui). As mensagens e as dicas citam o plano como “Plano Free”, “Plano Individual”, “Plano Multi” e “Plano Escritório”; a dica nomeia o plano que resolve, sem preço (antes mandava “subir de plano” sem dizer qual), e as empresas do Plano Free e do Plano Individual resolvem no Plano Multi; o Plano Escritório no teto diz como falar com a gente. Programe pelo code, não pelo texto. O mês das cotas vira à 0h de Brasília — antes virava à 0h UTC, às 21h de Brasília do último dia, e a nota ou a consulta das 21h às 24h contava no mês seguinte: vale para a cota de notas, a de consultas e os usadas do GET /me.
  • 2026-09-28 — Só Simples Nacional e MEI: a GereNota passa a atender só empresas do Simples Nacional (ME/EPP) e MEI. POST /companies recusa o regime 1 (não optante) com 422 EMPRESA_FORA_DO_SIMPLES; a criação também recusa o CNPJ que a consulta completa à Receita da própria conta, nos últimos 7 dias, mostrou como não optante (hint: “Pelo cadastro na Receita, esta empresa não é optante do Simples.”). A empresa que saiu do Simples — sabida pelo “Conferir na Receita” do painel ou pela recusa E0160 do Sistema Nacional, que dispara a conferência — ganha fora_do_simples e emissao_parada em GET /companies, GET /companies/{id}/status e GET /minhas-empresas, e toda emissão por ela responde 422 EMPRESA_FORA_DO_SIMPLES (“A emissão está parada: a empresa saiu do Simples Nacional”); as automações dela saem pulada com esse código e tentam de novo no dia seguinte. MEI e ME/EPP: sem mudança.
  • 2026-09-28 — CNPJ com letras (o formato novo da Receita: letras A–Z nas 12 primeiras posições, os 2 últimos continuam números; ex.: 12.ABC.345/01DE-35): todo campo de CNPJ — a empresa emissora, o tomador, a identidade de faturamento, as consultas e os caminhos com {documento} — aceita e devolve o CNPJ com letras, sem pontuação e em maiúsculas (minúscula vira maiúscula); a conta do dígito verificador é a da Receita, que vale também para o CNPJ só de números. As mensagens de erro passam a falar em caracteres: 422 com “CNPJ inválido: confira os 14 caracteres (letras só nas 12 primeiras posições)” ou “CNPJ inválido: os dois últimos dígitos não batem com o resto”; o documento do tomador na emissão, “precisa ter 11 dígitos (CPF) ou 14 caracteres (CNPJ)”. A busca de tomadores (q) trata como documento o termo com letras e números juntos, sem espaço (12.ABC). Série da nota: de 1 a 49999 na criação e na alteração da empresa (422; de 50000 em diante a série é dos emissores do governo e o Sistema Nacional recusaria as notas). Nada muda para quem manda CNPJ só de números.
  • 2026-09-28 — Tetos das consultas pagas e dos envios: as consultas de CNPJ e CPF na Receita ganham teto por dia (Plano Free 3; Plano Individual, Plano Multi e Plano Cortesia 10; Plano Escritório 30 por conta — 429 LIMITE_CONSULTAS_DIA, renova à 0h de Brasília), e a cota do mês passa a somar todas as portas da conta — esta API, o painel, os links de cadastro e o WhatsApp —, com os tetos Plano Free 5, Plano Individual 20, Plano Multi e Plano Cortesia 60 e Plano Escritório 200. A consulta que a Receita responde como “não encontrado” conta (ela é cobrada). O CNPJ consultado nos últimos 7 dias sai do cache sem gastar, venha a consulta de qualquer conta (de_cache: true); o CPF, só da mesma conta, com a mesma data de nascimento, em 24 horas. Quando as consultas pagas da plataforma param até a virada do dia: 503 CONSULTAS_PAUSADAS (Receita) e 503 PGDAS_PAUSADO (PGDAS-D); o POST /companies/{id}/pgdas/sync com forcar passa a 3 consultas pagas por empresa e dia. Envios: até 100 notas por e-mail por dia (429 LIMITE_EMAILS_DO_DIA) e 3 “rodar agora” por automação de relatório e dia (429 LIMITE_RODAR_AGORA).
  • 2026-09-28 — O download de exportação voltou a funcionar: o link temporário do arquivo — o Location do 302 de GET /exports/{id}/download e o link que vai no e-mail — passou a ser assinado em SigV4; o de antes era recusado pelo armazenamento (400) desde 22/09, porque o pacote é cifrado com KMS. O arquivo baixa como anexo, com o nome do período (gerenota-AAAA-MM-a-AAAA-MM.zip). Rota nova, GET /exports/{id}/link: o mesmo link em JSON (url, expira_em, arquivo), para quem não consegue seguir o redirecionamento sem repassar a própria chave — o navegador, por exemplo.
  • 2026-09-27 — Notas com problema e notas emitidas fora do GereNota: a listagem (GET /nfse) e a nota (GET /nfse/{id}) ganham origem na listagem (plataforma ou importada — a nota emitida fora do GereNota, trazida do Sistema Nacional), fora_depois_da_entrada (a de fora emitida depois que a empresa entrou: outro sistema ainda emitindo) e alertas, os problemas da nota com o que fazer (tipo, titulo, texto): o último e-mail ao cliente que voltou, foi recusado ou marcado como spam; a retida com o ISS de outro mês; o município que aplicou outra alíquota; o cancelamento por ofício; e a nota que parece ter saído em dobro (a do GereNota e uma de fora, mesmo cliente, competência e valor, as duas ativas). com_problema=true em GET /nfse e em GET /nfse/agregado traz só essas notas, e o agregado passa a contar com_problema dentro do mesmo filtro.
  • 2026-09-27 — Quem tem recorte vê os clientes das empresas dele: com a chave, o conector ou o login de quem acessa uma empresa compartilhada (ou de um membro recortado), GET /tomadores — a lista, a busca por nome e o prefixo do documento — traz os clientes que já receberam nota dessas empresas e os que a pessoa cadastrou; o CNPJ ou CPF inteiro continua achando qualquer cadastro da conta. O dono e quem não tem recorte: sem mudança.
  • 2026-09-26 — O cancelamento aceita Idempotency-Key e o envio da nota por e-mail ganha teto: repetir POST /nfse/{id}/cancelar com a mesma chave devolve o mesmo cancelamento (200, X-Idempotent-Replay: true) em vez do 409 NFSE_NAO_ATIVA; a chamada simultânea recebe 409 CANCELAMENTO_EM_ANDAMENTO. POST /nfse/{id}/enviar-email aceita até 10 envios por minuto por conta (429 RATE_LIMIT acima disso).
  • 2026-09-26 — O ISS de outro mês não vai mais à nota: numa ME/EPP no DAS, a nota retida sem pAliq de um mês que a plataforma não tem (modo manual sem aquele mês confirmado — inclusive o corrente, antes da confirmação —, ou quando a conta pelas declarações PGDAS-D não fecha para o período) passa a responder 422 ALIQUOTA_ISS_DO_MES_AUSENTE, em vez de sair com o ISS em uso — que é de outro mês, e com alíquota menor que a devida a diferença cai no DAS do prestador (LC 123, art. 21, § 4º, VI). Quem integra manda a pAliq daquele mês. Na nota de um mês que já virou, a dica do erro não manda confirmar a alíquota (a confirmação vale para o mês corrente). A automação com retenção segue a mesma regra: usa a pAliq gravada nela e, sem ela, sai pulada e tenta de novo no dia seguinte; completar uma pendência nessa situação responde 422 com a dica de informar a alíquota na automação. A automação criada pelo histórico (POST /automations/recorrente sem tributacao) numa ME/EPP no DAS deixa de copiar a pAliq da última nota retida — era o ISS de outro mês.
  • 2026-09-25 — O ISS do mês fora do histórico: numa ME/EPP no DAS em modo automático, a retenção sem pAliq de um mês que o histórico mensal não tem passa a levar o ISS daquele mês pela conta das declarações PGDAS-D arquivadas (o anexo e o impedimento daquele período, só com os 12 meses declarados), em vez do ISS em uso — o histórico começava na primeira alíquota registrada, e a nota tardia de antes dele saía com o número de outro mês. O mês calculado passa a constar do historico do dossiê quando uma nota retida sai com esse número. O cadastro com reg_ap_trib_sn 2 ou 3 tira o ISS do DAS também na nota de um mês do histórico. Sem o mês, veja a entrada de 26/09.
  • 2026-09-25 — Retenção do ISS no Simples: numa ME/EPP no DAS, a retenção sem pAliq passa a ser preenchida pela API com o ISS do mês da prestação (o da competência): o do mês corrente, ou o de um mês anterior quando ele está no histórico mensal da empresa — fora dele, o ISS em uso (até 26/09: veja a entrada desse dia). Sem ISS no mês resolvido, 422 ALIQUOTA_ISS_DO_MES_AUSENTE (antes a nota saía sem a alíquota que a lei manda informar). Com o ISS fora do DAS (o sublimite pela declaração, ou reg_ap_trib_sn 2 ou 3), a nota vai sem pAliq, como antes. Automação com retenção: criada por POST /automations/recorrente ou pelo aceite de uma sugestão, passa a exigir o endereço completo do tomador (422 RETENCAO_SEM_TOMADOR) e a pAliq (422 ALIQUOTA_OBRIGATORIA), como o assistente já exigia; em todas as rotas da automação, a ME/EPP no DAS que tem o ISS do mês fica dispensada da pAliq — o disparo usa o ISS do mês da prestação, e a pAliq gravada só vale quando a empresa não tem ISS naquele mês (com o ISS fora do DAS, ela é a alíquota do município). Sem número nenhum, o disparo sai pulada com ALIQUOTA_ISS_DO_MES_AUSENTE e tenta de novo no dia seguinte.
  • 2026-09-24 — Avisos: a execução da automação de relatório diz o que o e-mail teve — além de relatorio_enviado, os valores novos relatorio_parcial e relatorio_nao_entregue — e a automação de relatório pausa sozinha, com pausada_por: sem_destinos, quando o último destino sai da lista pelo link do e-mail.
  • 2026-09-22 — Alíquotas do Simples (47 operações): a tag aliquotas, com o dossiê (GET /companies/{id}/aliquotas: a alíquota do mês com a conta, a próxima, a conferência, os casos e o regime de apuração consultado na Receita Federal), as declarações PGDAS-D como dado (a lista, uma por período, o PDF) e a consulta paga (POST …/pgdas/sync com pa e forcar; 429 TETO_DIARIO_PGDAS; 403 ACEITE_SO_DO_DONO). A conferência da receita traz frases prontas para o cliente (frase_titulo, frase, detalhes) e a dos 12 meses (doze_meses). Empresa ME/EPP sem alíquota nenhuma recebe 422 ALIQUOTA_NAO_CONFIRMADA (antes a nota saía com um padrão de 13,99 %), e a automação nessa situação sai pulada. Exportação sem corte: fila justa, volumes e download?volume=, download por redirecionamento 302, links de 30 dias no e-mail, total_no_recorte sempre igual a total_notas; GET /nfse/agregado ganha exportacao (o que o pacote vai ter antes de pedir); o CSV de GET /reports/nfse vem completo; o relatório mensal sai pela fila (em_fila, repetida). As notas ganham vBC e pAliqAplic (a base e a alíquota que o município aplicou).
  • 2026-09-16 a 18 — Contabilidade (42 operações): POST /servicos/sugerir e GET /servicos/codigo/{codigo}; a situação com data e prova (cancelada_em, substituida_em, substituida_por, evento_situacao, substituida_por_numero), periodo_por=evento com bordas em Brasília, GET /nfse/eventos (cursor desde) e GET /nfse/{id}/eventos/{evento_id}/xml; por_status no agregado; o CSV do contador em português, relatorio.html e eventos/ no ZIP; vISSQN na listagem e a coluna “ISS retido (R$)” no CSV.
  • 2026-09-16 — primeira versão documentada da superfície pública (38 operações); cota mensal e cache nas consultas de CNPJ/CPF; Idempotency-Key passa a barrar emissões simultâneas com 409.

Para assistentes conversacionais: o MCP

Se a integração é uma conversa (Claude, ou qualquer cliente compatível com MCP) e não um sistema, não use chave de API: conecte o assistente ao GereNota pelo conector remoto em https://api.gerenota.com.br/mcp. O login é por código enviado ao e-mail da conta, e o assistente ganha as ferramentas do produto (emitir com prévia e confirmação explícita, listar, cancelar, exportar, automações), com o papel da pessoa respeitado. O guia das ferramentas está dentro do próprio conector (nfse_help). Para a contabilidade, o conector tem o mesmo que a API: nfse_alteracoes (o que mudou de situação, com desde como cursor), nfse_evento_xml (o XML do evento, a prova), nfse_listar com periodo_por=evento e nfse_exportar (o ZIP). Para as alíquotas do Simples, nfse_aliquotas devolve o mesmo dossiê da API (a alíquota do mês com a conta, a próxima, a conferência e as declarações). A API REST deste documento é para sistemas que programam a integração.

Referência

Todas as rotas abaixo ficam sob https://api.gerenota.com.br e exigem Authorization: Bearer gnk_live_…, salvo /health.

Conta

Quem sou eu: identidade, plano e cotas da chave em uso.

Ver a conta, o papel e o plano da chave

GET /api/v1/me

Diz de quem é a chave em uso — conta, usuário e papel efetivo — e como está o plano.

Vale como primeira chamada de uma integração nova: confirma que a chave é válida e mostra o que ela pode fazer. role é operador para chave de escopo emissao e leitor para escopo leitura; o papel efetivo nunca passa do papel de quem criou a chave. empresas conta as empresas próprias da conta e compartilhadas, as de outras contas a que este usuário tem acesso; empresa_padrao traz o company_id que o painel abre por padrão — bom palpite quando a sua integração não recebeu a empresa de outro jeito.

O bloco plano traz o consumo do mês (notas.usadas × notas.cota, consultas.usadas × consultas.cota) e os tetos de empresas, automações e acessos, com a mesma régua que a API usa para barrar; teto/cota em null significa sem limite, e o bloco inteiro pode vir null sem que haja erro (nesse caso, siga e trate o 402 quando ele vier). Para o dono da conta (no painel ou no conector; a chave de API nunca é do dono), o limite já no teto traz upgrade, o plano em que o próximo item cabe, com o preço e o link para assinar, e o recurso que o plano não inclui traz upgrade_relatorios ou upgrade_api_mcp. billing.bloqueada em true quer dizer renovação vencida: as outras rotas respondem 402 CONTA_BLOQUEADA até o pagamento, e só esta continua respondendo.

escopo diz o escopo da própria chave (emissao ou leitura) antes de qualquer chamada de escrita; é nulo na sessão de login do painel.

Exemplo de chamada

curl -X GET "https://api.gerenota.com.br/api/v1/me" \
  -H "Authorization: Bearer $GERENOTA_KEY"

Resposta 200 — Identidade da chave, com plano e sinais de cobrança

Exemplo de resposta

{
  "account_id": "acc_it",
  "billing": {
    "bloqueada": false,
    "vence_hoje": false
  },
  "compartilhadas": 0,
  "email": "it@gerenota.test",
  "empresa_padrao": null,
  "empresas": 0,
  "escopo": null,
  "importacao_auto": false,
  "nome": null,
  "plano": {
    "acessos": {
      "teto": 999,
      "uso": 0
    },
    "api_mcp": true,
    "automacoes": {
      "teto": null,
      "uso": 0
    },
    "consultas": {
      "cota": null,
      "usadas": 0
    },
    "empresas": {
      "teto": null,
      "uso": 0
    },
    "nome": "Dev (interno)",
    "notas": {
      "cota": null,
      "usadas": 0
    },
    "relatorios": true
  },
  "role": "owner",
  "telefone": null,
  "telefone_verificado": false,
  "user_id": "it@gerenota.test"
}

Erros

Empresas

As empresas emissoras da conta: listar, cadastrar, enviar o certificado A1 e validar.

Listar as empresas que a chave pode usar

GET /api/v1/minhas-empresas

Lista as empresas em que você pode operar: as da própria conta e as que outras contas compartilharam com você, cada uma com o seu papel efetivo. É o ponto de partida de qualquer integração: escolha aqui o id e use-o como company_id nas demais rotas.

Para uma empresa compartilhada, acrescente ?company_id=<id> às chamadas: elas rodam na conta dona, com o seu papel. GET /companies lista só as empresas próprias, com mais detalhes.

Exemplo de chamada

curl -X GET "https://api.gerenota.com.br/api/v1/minhas-empresas" \
  -H "Authorization: Bearer $GERENOTA_KEY"

Resposta 200 — Empresas próprias e compartilhadas, com o papel em cada uma

Exemplo de resposta

[
  {
    "aliquota_atual": null,
    "aliquota_competencia": null,
    "aliquota_iss": null,
    "cert_bloqueado": false,
    "cnpj": "12345678000195",
    "estado_aliquotas": "nunca",
    "id": "cmp_9b958e240b9f983f",
    "municipio": "Natal/RN",
    "nome_fantasia": null,
    "papel": "operador",
    "propria": true,
    "razao_social": "EMPRESA COMPARTILHADA LTDA",
    "receita_resumo": null,
    "status": "ativa",
    "tributacao_modo": "auto"
  }
]

Erros

Listar as empresas da conta

GET /api/v1/companies

Lista as empresas emissoras da conta, cada uma com cadastro, regime tributário e situação.

É por aqui que se descobre o company_id das demais rotas: é o campo id de cada item, no formato cmp_…. Só emite nota a empresa com status igual a ativa — pendente ainda não validou o certificado A1 e waitlist está em município que não emite pelo Sistema Nacional. A lista já vem recortada pelo acesso de quem criou a chave; empresas de outra conta compartilhadas com este usuário não aparecem aqui, mas podem ser usadas nas demais rotas pelo company_id que o dono informou. Devolve no máximo 200 empresas, sem paginação nem filtro, e basta escopo leitura.

Exemplo de chamada

curl -X GET "https://api.gerenota.com.br/api/v1/companies" \
  -H "Authorization: Bearer $GERENOTA_KEY"

Resposta 200 — OK

Exemplo de resposta

[
  {
    "aviso": null,
    "cnpj": "12345678000195",
    "criado_em": "2026-09-16T18:39:30.506000Z",
    "email": null,
    "endereco": {
      "CEP": "59064902",
      "cMun": "2408102",
      "nro": "1",
      "xBairro": "CENTRO",
      "xCpl": null,
      "xLgr": "AV X"
    },
    "id": "cmp_157c9bd26b9e0b22",
    "inscricao_municipal": "1234567",
    "nome_fantasia": null,
    "pgdas": null,
    "razao_social": "EMPRESA TESTE ALIQUOTAS LTDA",
    "receita": null,
    "receita_consultado_em": null,
    "regime": {
      "aliquota_confirmada_para": "2026-09",
      "aliquota_detectada": null,
      "aliquota_fonte": "manual",
      "op_simp_nac": "3",
      "p_aliq_iss": null,
      "p_tot_trib_sn": "12.34",
      "reg_ap_trib_sn": "1",
      "reg_esp_trib": "0"
    },
    "serie_padrao": "1",
    "status": "ativa",
    "sync_opcoes": null,
    "telefone": null,
    "tributacao_modo": "manual"
  }
]

Erros

Ver a situação de uma empresa e do certificado

GET /api/v1/companies/{company_id}/status

Devolve a ficha operacional de uma empresa: o cadastro (company), o certificado A1 mais recente (certificate) e o estado da importação automática de notas (importacao).

Use antes de emitir para saber se a empresa está de pé: company.status precisa ser ativa e certificate.status, validado — e olhe certificate.dias_para_vencer, que fica negativo quando o certificado já venceu (nesse caso a emissão passa a falhar). certificate vem null enquanto nenhum arquivo .pfx foi enviado. O bloco importacao é informativo e best-effort: diz se a rodada automática está ligada, quando foi a última e quantas notas antigas ainda faltam entrar; pode vir com indisponivel: true sem que a empresa tenha problema algum.

Responde 404 quando o company_id não existe nesta conta e 403 EMPRESA_FORA_DO_RECORTE quando a empresa está fora do acesso da chave. Basta escopo leitura.

Parâmetros

Exemplo de chamada

curl -X GET "https://api.gerenota.com.br/api/v1/companies/{company_id}/status" \
  -H "Authorization: Bearer $GERENOTA_KEY"

Resposta 200 — OK

Exemplo de resposta

{
  "certificate": {
    "company_id": "cmp_2c15d6b44e32ffd3",
    "dias_para_vencer": 299,
    "id": "crt_35b722208a116264",
    "not_after": "2027-07-13T18:46:13Z",
    "status": "recebido",
    "subject_cn": "EMPRESA TESTE:12345678000195",
    "subject_cnpj": "12345678000195"
  },
  "company": {
    "aviso": null,
    "cnpj": "12345678000195",
    "criado_em": "2026-09-16T18:46:13.336000Z",
    "email": null,
    "endereco": {
      "CEP": "59064902",
      "cMun": "2408102",
      "nro": "1",
      "xBairro": "CENTRO",
      "xCpl": null,
      "xLgr": "AV X"
    },
    "id": "cmp_2c15d6b44e32ffd3",
    "inscricao_municipal": "1234567",
    "nome_fantasia": null,
    "pgdas": null,
    "razao_social": "EMPRESA TESTE INTEGRACAO LTDA",
    "receita": null,
    "receita_consultado_em": null,
    "regime": {
      "aliquota_confirmada_para": null,
      "aliquota_detectada": null,
      "aliquota_fonte": null,
      "op_simp_nac": "3",
      "p_aliq_iss": null,
      "p_tot_trib_sn": null,
      "reg_ap_trib_sn": "1",
      "reg_esp_trib": "0"
    },
    "serie_padrao": "1",
    "status": "pendente",
    "sync_opcoes": null,
    "telefone": null,
    "tributacao_modo": "auto"
  },
  "importacao": {
    "automatica": {
      "ligada": false,
      "motivo_pausa": "desligada",
      "proxima_em": null,
      "ultima_em": null,
      "vencido_em": null
    },
    "em_andamento": false,
    "em_andamento_origem": null,
    "indisponivel": false,
    "legado": {
      "disponiveis": 0,
      "ligado": false,
      "no_painel": 0
    },
    "motivo": "certificado_aguardando_validacao",
    "opcoes": {
      "importar_legado_convertido": false
    },
    "pode_importar": false,
    "progresso": null,
    "ultima": null
  }
}

Erros

Cadastrar uma empresa emissora

POST /api/v1/companies

Cadastra uma empresa emissora na conta e devolve a ficha criada, com o id (cmp_…) que as outras rotas pedem como company_id.

A empresa nasce com status pendente e ainda não emite: o caminho até a primeira nota é enviar o certificado A1 (POST /companies/{company_id}/certificate) e validar (POST /companies/{company_id}/validate). Mande cnpj sem pontuação (ela é aceita e normalizada; o CNPJ pode ter letras nas 12 primeiras posições) e, em endereco.cMun, o código IBGE de 7 dígitos do município da empresa — confirme pelo CEP em GET /consultas/cep/{cep} em vez de adivinhar, porque o código errado só aparece na rejeição da nota. Até 31/10/2026, a ME ou a EPP de município que ainda não emite pelo Sistema Nacional é aceita com status waitlist, e o campo aviso explica: ela não emite até sair da lista. Em 1º/11/2026 ela sai (a partir dessa data, a ME e a EPP emitem pelo Emissor Nacional em qualquer cidade). O MEI não entra na lista.

Erros: 409 quando o CNPJ já está cadastrado nesta conta ou já chega compartilhado por outra (CNPJ_JA_COMPARTILHADO), 402 LIMITE_DO_PLANO quando o plano não comporta mais uma empresa e 503 ADN_INDISPONIVEL quando o serviço do gov.br que informa a adesão do município não responde. Com o company_id de uma empresa compartilhada por outra conta, 403 PERMISSAO_NEGADA: a empresa nova nasce na sua conta, nunca na conta que compartilhou. Exige chave de escopo emissao.

Corpo (JSON)

Exemplo de chamada

curl -X POST "https://api.gerenota.com.br/api/v1/companies" \
  -H "Authorization: Bearer $GERENOTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cnpj": "12345678000195", "endereco": {"CEP": "59064902", "cMun": "2408102", "nro": "1", "xBairro": "CENTRO", "xLgr": "AV X"}, "inscricao_municipal": "1234567", "razao_social": "EMPRESA TESTE ALIQUOTAS LTDA"}'

Resposta 201 — OK

Exemplo de resposta

{
  "aviso": null,
  "cnpj": "12345678000195",
  "criado_em": "2026-09-16T18:39:18.763504Z",
  "email": null,
  "endereco": {
    "CEP": "59064902",
    "cMun": "2408102",
    "nro": "1",
    "xBairro": "CENTRO",
    "xCpl": null,
    "xLgr": "AV X"
  },
  "id": "cmp_a7ee8f7a44edd30e",
  "inscricao_municipal": "1234567",
  "nome_fantasia": null,
  "pgdas": null,
  "razao_social": "EMPRESA TESTE ALIQUOTAS LTDA",
  "receita": null,
  "receita_consultado_em": null,
  "regime": {
    "aliquota_confirmada_para": null,
    "aliquota_detectada": null,
    "aliquota_fonte": null,
    "op_simp_nac": "3",
    "p_aliq_iss": null,
    "p_tot_trib_sn": null,
    "reg_ap_trib_sn": "1",
    "reg_esp_trib": "0"
  },
  "serie_padrao": "1",
  "status": "pendente",
  "sync_opcoes": null,
  "telefone": null,
  "tributacao_modo": "auto"
}

Erros

Pedir o certificado digital a quem é dono

POST /api/v1/companies/{company_id}/certificado/pedidos

Pede o certificado digital A1 da empresa a quem é dono dela — para a contabilidade e o operador; quem é dono libera direto, pelo painel. O pedido não libera nada: quem é dono recebe o aviso por e-mail e WhatsApp e decide, com o código que chega no e-mail de quem é dono; se liberar, o link vai para o e-mail do acesso de quem pediu. O pedido vence em 7 dias. Com um pedido da mesma pessoa para a mesma empresa ainda aberto, devolve esse pedido, sem aviso novo.

Parâmetros

Corpo (JSON)

Exemplo de chamada

curl -X POST "https://api.gerenota.com.br/api/v1/companies/{company_id}/certificado/pedidos" \
  -H "Authorization: Bearer $GERENOTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Resposta 201 — OK

Erros

Alíquotas

Alíquotas do Simples (ME/EPP): o dossiê da empresa (a alíquota do mês com a conta e a explicação, a próxima, a conferência, os casos relevantes), as declarações PGDAS-D arquivadas como dado (13 PAs na entrada, uma por mês depois, versões) e a consulta paga ao Integra Contador.

Ver o dossiê das alíquotas do Simples da empresa

GET /api/v1/companies/{company_id}/aliquotas

O dossiê das alíquotas do Simples da empresa: empresa (o modo, a autorização e o regime de apuração do ano, com a fonte), mes (a alíquota em vigor, a fonte — pgdas, estimada, proporcionalizada, inicio_atividade ou manual — a conta aberta e a explicacao em português, com a base legal), proxima (a do mês seguinte, quando o PGDAS-D já permite), conferencia (a última: alíquota declarada × aplicada, receita declarada × notas — com as frases prontas para mostrar ao cliente em receita.frase_titulo, frase e detalhes —, retificações, notas com retenção afetadas por uma correção), payload_divergencia (notas que chegaram com alíquota própria), casos (os casos relevantes, cada um com gravidade acao | atencao | info, título e texto — o que dizer ao cliente), historico (mês a mês, mais novo primeiro) e declaracoes (as PGDAS-D consultadas; o PDF de cada uma em /pgdas/declaracoes/{pa}/pdf). Só leitura — nada aqui consulta o Integra Contador. Vale para empresa compartilhada em qualquer papel. Qualquer papel com acesso à empresa lê, inclusive o leitor e a chave de API de leitura: quem vê as notas já vê a receita delas. Confirmar ou editar a alíquota segue com dono, operador e contabilidade.

Parâmetros

Exemplo de chamada

curl -X GET "https://api.gerenota.com.br/api/v1/companies/{company_id}/aliquotas" \
  -H "Authorization: Bearer $GERENOTA_KEY"

Resposta 200 — OK

Exemplo de resposta

{
  "base_legal": "Res. CGSN 140/2018, art. 27, I, a: a alíquota de ISS da nota é a efetiva da faixa a que a empresa está sujeita no mês anterior — a receita acumulada nos 12 meses que antecedem o mês anterior",
  "casos": [
    {
      "gravidade": "atencao",
      "texto": "Agosto: a receita declarada bate com as notas (R$ (valor)). A empresa é do caixa: o imposto do mês sai do que foi recebido (R$ (valor) declarados); a alíquota vem do que foi faturado nos últimos 12 meses. Últimos 12 meses (08/2025 a 07/2026): as notas somam R$ (valor) e as declarações somam R$ (valor): R$ (valor) a menos (menos de 1 %). É desse total que sai a alíquota; vale perguntar ao contador. O mês que não bate: janeiro/2026 (R$ (valor) a menos).",
      "tipo": "receita_abaixo",
      "titulo": "A receita dos últimos 12 meses não bate com as notas"
    },
    {
      "gravidade": "info",
      "texto": "A tabela de receitas da declaração mais nova mudou em 08/2025 (R$ (valor) → R$ (valor)), 09/2025 (R$ (valor) → R$ (valor)), 10/2025 (R$ (valor) → R$ (valor)), 11/2025 (R$ (valor) → R$ (valor)), 12/2025 (R$ (valor) → R$ (valor)), 01/2026 (R$ (valor) → R$ (valor)), 02/2026 (R$ (valor) → R$ (valor)), 03/2026 (R$ (valor) → R$ (valor)), 04/2026 (R$ (valor) → R$ (valor)), 05/2026 (R$ (valor) → R$ (valor)), 06/2026 (R$ (valor) → R$ (valor)), 07/2026 (R$ (valor) → R$ (valor)). A RBT12 e a alíquota foram refeitas com a tabela nova.",
      "tipo": "retificacao",
      "titulo": "Declaração retificada pelo contador"
    },
    {
      "gravidade": "info",
      "texto": "A partir de 1º/10/2026: 13,80 % (ISS 4,48 %). 13,80 % (ISS 4,48 %): RBT12 R$ (valor) = Σ set/25..ago/26 do PGDAS 202608 — Anexo III, 4ª faixa Nada muda nas notas deste mês.",
      "tipo": "proxima_muda",
      "titulo": "A alíquota muda em outubro/2026"
    },
    {
      "gravidade": "info",
      "texto": "A empresa é do caixa: o imposto do mês sai do que foi recebido. A alíquota, porém, vem do que foi faturado nos últimos 12 meses, nos dois regimes. Vale até dezembro de 2026: em 2027 toda empresa passa para competência.",
      "tipo": "caixa_ate_dez26",
      "titulo": "Regime de caixa até dezembro/2026"
    }
  ],
  "conferencia": {
    "aliquota": {
      "aplicada": {
        "p_aliq_iss": "4.50",
        "p_tot_trib_sn": "13.86"
      },
      "declarada": {
        "p_aliq_iss": "4.51",
        "p_tot_trib_sn": "13.87"
      },
      "diferenca_pp": "0.01",
      "mes_fechado": false,
      "veredito": "bateu"
    },
    "em": "2026-09-23T01:42:23.682000Z",
    "explicacao": "A declaração PGDAS-D de 08/2026 confirmou a alíquota de 09/2026: declarada 13,87 % × aplicada 13,86 % (tolerância de 0,01 pp). Agosto: a receita declarada bate com as notas (R$ (valor)). A empresa é do caixa: o imposto do mês sai do que foi recebido (R$ (valor) declarados); a alíquota vem do que foi faturado nos últimos 12 meses. Últimos 12 meses (08/2025 a 07/2026): as notas somam R$ (valor) e as declarações somam R$ (valor): R$ (valor) a menos (menos de 1 %). É desse total que sai a alíquota; vale perguntar ao contador. O mês que não bate: janeiro/2026 (R$ (valor) a menos). PA retificado: 08/2025, 09/2025, 10/2025, 11/2025, 12/2025, 01/2026, 02/2026, 03/2026, 04/2026, 05/2026, 06/2026, 07/2026 — a receita mudou na declaração e a conta foi refeita com a tabela nova.",
    "mes": "2026-09",
    "pa": "202608",
    "receita": {
      "avisar": true,
      "base_comparada": "notas_por_competencia",
      "campo_origem": "rpa_competencia",
      "canceladas_apos_transmissao": null,
      "declarada": "34394.37",
      "detalhes": [
        "A empresa é do caixa: o imposto do mês sai do que foi recebido (R$ (valor) declarados); a alíquota vem do que foi faturado nos últimos 12 meses."
      ],
      "diferenca": "0.00",
      "doze_meses": {
        "assinatura": "2026-01:1000.00",
        "cobertura": true,
        "declarada": "618794.01",
        "diferenca": "370.00",
        "frase": "Últimos 12 meses (08/2025 a 07/2026): as notas somam R$ (valor) e as declarações somam R$ (valor): R$ (valor) a menos (menos de 1 %). É desse total que sai a alíquota; vale perguntar ao contador. O mês que não bate: janeiro/2026 (R$ (valor) a menos).",
        "janela": [
          "2025-08",
          "2026-07"
        ],
        "meses_divergentes": [
          {
            "declarada": "51566.16",
            "diferenca": "370.00",
            "mes": "2026-01",
            "notas": "51936.16"
          }
        ],
        "notas": "619164.01",
        "novo": true,
        "pct": "0",
        "veredito": "declarada_abaixo_das_notas"
      },
      "frase": "",
      "frase_titulo": "Agosto: a receita declarada bate com as notas (R$ (valor)).",
      "mes": "2026-08",
      "notas": "34394.37",
      "notas_apos_transmissao": {
        "quantidade": 0,
        "soma": "0.00"
      },
      "pa": "202608",
      "pct": "0",
      "regime_apuracao": "caixa",
      "rotulo": "a receita declarada bate com as notas",
      "rpa_caixa": "64243.51",
      "transmitida_em": "2026-09-17T19:18:56Z",
      "veredito": "bateu"
    },
    "retificados": {
      "2025-08": {
        "antes": "55239.42",
        "depois": "51566.16"
      },
      "2025-09": {
        "antes": "59121.09",
        "depois": "51566.16"
      },
      "2025-10": {
        "antes": "49775.79",
        "depois": "51566.16"
      },
      "2025-11": {
        "antes": "56314.34",
        "depois": "51566.16"
      },
      "2025-12": {
        "antes": "48511.11",
        "depois": "51566.16"
      },
      "2026-01": {
        "antes": "45810.35",
        "depois": "51566.16"
      },
      "2026-02": {
        "antes": "45257.35",
        "depois": "51566.16"
      },
      "2026-03": {
        "antes": "75066.57",
        "depois": "51566.16"
      },
      "2026-04": {
        "antes": "49844.95",
        "depois": "51566.16"
      },
      "2026-05": {
        "antes": "54580.89",
        "depois": "51566.16"
      },
      "2026-06": {
        "antes": "46538.89",
        "depois": "51566.16"
      },
      "2026-07": {
        "antes": "32733.26",
        "depois": "51566.25"
      }
    }
  },
  "declaracoes": [
    {
      "anexo": "III",
      "anexo_confere": true,
      "consultado_em": "2026-09-23T01:42:23.670000Z",
      "faixa": 4,
      "fonte": "sync",
      "impedido_iss_no_das": false,
      "meses_retificados": {
        "2025-08": {
          "antes": "55239.42",
          "depois": "51566.16"
        },
        "2025-09": {
          "antes": "59121.09",
          "depois": "51566.16"
        },
        "2025-10": {
          "antes": "49775.79",
          "depois": "51566.16"
        },
        "2025-11": {
          "antes": "56314.34",
          "depois": "51566.16"
        },
        "2025-12": {
          "antes": "48511.11",
          "depois": "51566.16"
        },
        "2026-01": {
          "antes": "45810.35",
          "depois": "51566.16"
        },
        "2026-02": {
          "antes": "45257.35",
          "depois": "51566.16"
        },
        "2026-03": {
          "antes": "75066.57",
          "depois": "51566.16"
        },
        "2026-04": {
          "antes": "49844.95",
          "depois": "51566.16"
        },
        "2026-05": {
          "antes": "54580.89",
          "depois": "51566.16"
        },
        "2026-06": {
          "antes": "46538.89",
          "depois": "51566.16"
        },
        "2026-07": {
          "antes": "32733.26",
          "depois": "51566.25"
        }
      },
      "p_aliq_iss": "4.51",
      "p_tot_trib_sn": "13.87",
      "pa": "202608",
      "rbt12": "618794.01",
      "regime_apuracao": "caixa",
      "retificadora": false,
      "rpa_caixa": "64243.51",
      "rpa_competencia": "34394.37",
      "tem_pdf": true,
      "transmitida_em": "2026-09-17T19:18:56Z",
      "versao": "001"
    },
    {
      "anexo": "III",
      "anexo_confere": true,
      "consultado_em": "2026-08-21T00:00:00Z",
      "faixa": 4,
      "fonte": "sync",
      "impedido_iss_no_das": null,
      "meses_retificados": {},
      "p_aliq_iss": null,
      "p_tot_trib_sn": null,
      "pa": "202607",
      "rbt12": "642686.65",
      "regime_apuracao": "caixa",
      "retificadora": null,
      "rpa_caixa": null,
      "rpa_competencia": "32733.26",
      "tem_pdf": false,
      "transmitida_em": null,
      "versao": "001"
    }
  ],
  "empresa": {
    "ibs_cbs_no_das": null,
    "id": "cmp_c71a919fd06d9695",
    "nome": "EMPRESA TESTE EMISSAO LTDA",
    "op_simp_nac": "3",
    "pgdas_autorizado": true,
    "regime_apuracao": "caixa",
    "regime_apuracao_ate": "2026-12",
    "regime_apuracao_divergencia": null,
    "regime_apuracao_fonte": "pgdas",
    "regime_consultado_em": "2026-09-23T01:42:23.511000Z",
    "regimes_apuracao": {},
    "tributacao_modo": "auto"
  },
  "historico": [
    {
      "anexo": "III",
      "anterior": null,
      "calculada_em": "2026-09-23T01:42:23.521000Z",
      "conferencia": {
        "aliquota": "bateu",
        "corrigida": false,
        "em": "2026-09-23T01:42:23.682000Z",
        "pa": "202608",
        "receita": "bateu",
        "receita_pct": "0",
        "retificados": [
          "2025-08",
          "2025-09",
          "2025-10",
          "2025-11",
          "2025-12",
          "2026-01",
          "2026-02",
          "2026-03",
          "2026-04",
          "2026-05",
          "2026-06",
          "2026-07"
        ]
      },
      "conta": "13,86 % (ISS 4,50 %): RBT12 R$ (valor) = Σ ago/25..jul/26 do PGDAS 202607 — Anexo III, 4ª faixa",
      "corrigida": false,
      "faixa": 4,
      "fonte": "pgdas",
      "iss_fora_do_das": false,
      "janela": [
        "2025-08",
        "2026-07"
      ],
      "mes": "2026-09",
      "meses_estimados": [],
      "p_aliq_iss": "4.50",
      "p_tot_trib_sn": "13.86",
      "rbt12": "618794.01",
      "tabela": "2018"
    }
  ],
  "mes": {
    "anexo": "III",
    "calculada_em": "2026-09-23T01:42:23.521000Z",
    "conta": "13,86 % (ISS 4,50 %): RBT12 R$ (valor) = Σ ago/25..jul/26 do PGDAS 202607 — Anexo III, 4ª faixa",
    "defasada": false,
    "explicacao": "A alíquota de setembro/2026 é 13,86 % (ISS 4,50 %) porque a receita acumulada de ago/25 a jul/26, por competência, foi R$ (valor) — 4ª faixa do Anexo III: (16.00 % × RBT12 − R$ (valor)) ÷ RBT12, truncada a duas casas. Res. CGSN 140/2018, art. 27, I, a: a alíquota de ISS da nota é a efetiva da faixa a que a empresa está sujeita no mês anterior — a receita acumulada nos 12 meses que antecedem o mês anterior.",
    "faixa": 4,
    "fonte": "pgdas",
    "iss_fora_do_das": false,
    "janela": [
      "2025-08",
      "2026-07"
    ],
    "mes": "2026-09",
    "meses_estimados": [],
    "p_aliq_iss": "4.50",
    "p_tot_trib_sn": "13.86",
    "rbt12": "618794.01",
    "tabela": "2018"
  },
  "meses": [
    "jan",
    "fev",
    "mar",
    "abr",
    "mai",
    "jun",
    "jul",
    "ago",
    "set",
    "out",
    "nov",
    "dez"
  ],
  "payload_divergencia": null,
  "pelo_pgdas": null,
  "pelo_pgdas_seria": null,
  "proxima": {
    "a_partir_de": "2026-10",
    "anexo": "III",
    "calculada_em": "2026-09-23T01:42:23.682000Z",
    "conta": "13,80 % (ISS 4,48 %): RBT12 R$ (valor) = Σ set/25..ago/26 do PGDAS 202608 — Anexo III, 4ª faixa",
    "explicacao": "A partir de 1º/10/2026: 13,80 % (ISS 4,48 %). 13,80 % (ISS 4,48 %): RBT12 R$ (valor) = Σ set/25..ago/26 do PGDAS 202608 — Anexo III, 4ª faixa Nada muda nas notas deste mês.",
    "faixa": 4,
    "fonte": "pgdas",
    "iss_fora_do_das": false,
    "janela": [
      "2025-09",
      "2026-08"
    ],
    "mes": "2026-10",
    "meses_estimados": [],
    "p_aliq_iss": "4.48",
    "p_tot_trib_sn": "13.80",
    "proporcional": false,
    "rbt12": "601622.22",
    "tabela": "2018"
  }
}

Erros

Listar as declarações PGDAS-D arquivadas

GET /api/v1/companies/{company_id}/pgdas/declaracoes

As declarações PGDAS-D arquivadas da empresa — TODAS as versões, da mais nova para a mais antiga (o histórico de entrada traz 13 PAs; cada mês novo entra pelo dia 21; retificadora = versão nova do mesmo PA, a anterior fica). Cada item: PA, versão (001 = original), nº da declaração, regime de apuração, receita do PA por competência e por caixa, RBT12 (e RBT12p/RBA/RBAA), efetiva total e ISS declaradas, anexo/faixa inferidos, meses retificados apontados pela tabela 2.2, transmissão, se o PDF está arquivado. O detalhe de cada uma (tabela mensal de receitas, atividades) sai em …/declaracoes/{pa}. Qualquer papel com acesso à empresa lê, inclusive o leitor e a chave de API de leitura: quem vê as notas já vê a receita delas.

Parâmetros

Exemplo de chamada

curl -X GET "https://api.gerenota.com.br/api/v1/companies/{company_id}/pgdas/declaracoes" \
  -H "Authorization: Bearer $GERENOTA_KEY"

Resposta 200 — OK

Exemplo de resposta

[
  {
    "anexo": "III",
    "anexo_ambiguo": null,
    "anexo_confere": true,
    "consultado_em": "2026-08-21T00:00:00Z",
    "data_abertura": "2019-05-20",
    "faixa": 4,
    "fonte": "sync",
    "impedido_iss_no_das": null,
    "iss_retido_no_pa": null,
    "meses_retificados": {},
    "numero_declaracao": null,
    "p_aliq_iss": null,
    "p_tot_trib_sn": null,
    "pa": "202608",
    "rba": null,
    "rbaa": null,
    "rbt12": "618794.01",
    "rbt12p": null,
    "regime_apuracao": "caixa",
    "retificadora": null,
    "rpa_caixa": null,
    "rpa_competencia": "34394.37",
    "tem_pdf": false,
    "transmitida_em": null,
    "versao": "001"
  },
  {
    "anexo": "III",
    "anexo_ambiguo": false,
    "anexo_confere": true,
    "consultado_em": "2026-09-22T19:14:53.449000Z",
    "data_abertura": "2019-05-20",
    "faixa": 4,
    "fonte": "historico_s3",
    "impedido_iss_no_das": false,
    "iss_retido_no_pa": false,
    "meses_retificados": {},
    "numero_declaracao": "11111111202607001",
    "p_aliq_iss": "4.51",
    "p_tot_trib_sn": "13.87",
    "pa": "202607",
    "rba": "384226.63",
    "rbaa": "659006.28",
    "rbt12": "618794.01",
    "rbt12p": null,
    "regime_apuracao": "caixa",
    "retificadora": false,
    "rpa_caixa": "64243.51",
    "rpa_competencia": "32733.26",
    "tem_pdf": true,
    "transmitida_em": "2026-09-17T19:18:56Z",
    "versao": "001"
  },
  {
    "anexo": "III",
    "anexo_ambiguo": false,
    "anexo_confere": true,
    "consultado_em": "2026-09-22T19:14:53.463000Z",
    "data_abertura": "2019-05-20",
    "faixa": 4,
    "fonte": "historico_s3",
    "impedido_iss_no_das": false,
    "iss_retido_no_pa": false,
    "meses_retificados": {},
    "numero_declaracao": "11111111202606001",
    "p_aliq_iss": "4.51",
    "p_tot_trib_sn": "13.87",
    "pa": "202606",
    "rba": "384226.63",
    "rbaa": "659006.28",
    "rbt12": "618794.01",
    "rbt12p": null,
    "regime_apuracao": "caixa",
    "retificadora": false,
    "rpa_caixa": "64243.51",
    "rpa_competencia": "46538.89",
    "tem_pdf": false,
    "transmitida_em": "2026-09-17T19:18:56Z",
    "versao": "001"
  },
  {
    "anexo": null,
    "anexo_ambiguo": false,
    "anexo_confere": null,
    "consultado_em": "2026-09-22T19:14:53.567000Z",
    "data_abertura": "2019-05-20",
    "faixa": null,
    "fonte": "sync",
    "impedido_iss_no_das": false,
    "iss_retido_no_pa": false,
    "meses_retificados": {},
    "numero_declaracao": "11111111202605001",
    "p_aliq_iss": "4.20",
    "p_tot_trib_sn": "13.00",
    "pa": "202605",
    "rba": "384226.63",
    "rbaa": "659006.28",
    "rbt12": "370000.00",
    "rbt12p": null,
    "regime_apuracao": "caixa",
    "retificadora": false,
    "rpa_caixa": "64243.51",
    "rpa_competencia": "3700.00",
    "tem_pdf": true,
    "transmitida_em": "2026-09-17T19:18:56Z",
    "versao": "001"
  },
  {
    "anexo": null,
    "anexo_ambiguo": false,
    "anexo_confere": null,
    "consultado_em": "2026-09-22T19:14:53.686000Z",
    "data_abertura": "2019-05-20",
    "faixa": null,
    "fonte": "sync",
    "impedido_iss_no_das": false,
    "iss_retido_no_pa": false,
    "meses_retificados": {},
    "numero_declaracao": "11111111202604001",
    "p_aliq_iss": "4.20",
    "p_tot_trib_sn": "13.00",
    "pa": "202604",
    "rba": "384226.63",
    "rbaa": "659006.28",
    "rbt12": "370000.00",
    "rbt12p": null,
    "regime_apuracao": "caixa",
    "retificadora": false,
    "rpa_caixa": "64243.51",
    "rpa_competencia": "3700.00",
    "tem_pdf": true,
    "transmitida_em": "2026-09-17T19:18:56Z",
    "versao": "001"
  },
  {
    "anexo": null,
    "anexo_ambiguo": false,
    "anexo_confere": null,
    "consultado_em": "2026-09-22T19:14:53.913000Z",
    "data_abertura": "2019-05-20",
    "faixa": null,
    "fonte": "sync",
    "impedido_iss_no_das": false,
    "iss_retido_no_pa": false,
    "meses_retificados": {},
    "numero_declaracao": "11111111202602001",
    "p_aliq_iss": "4.20",
    "p_tot_trib_sn": "13.00",
    "pa": "202602",
    "rba": "384226.63",
    "rbaa": "659006.28",
    "rbt12": "370000.00",
    "rbt12p": null,
    "regime_apuracao": "caixa",
    "retificadora": false,
    "rpa_caixa": "64243.51",
    "rpa_competencia": "3700.00",
    "tem_pdf": true,
    "transmitida_em": "2026-09-17T19:18:56Z",
    "versao": "001"
  },
  {
    "anexo": null,
    "anexo_ambiguo": false,
    "anexo_confere": null,
    "consultado_em": "2026-09-22T19:14:54.030000Z",
    "data_abertura": "2019-05-20",
    "faixa": null,
    "fonte": "sync",
    "impedido_iss_no_das": false,
    "iss_retido_no_pa": false,
    "meses_retificados": {},
    "numero_declaracao": "11111111202601001",
    "p_aliq_iss": "4.20",
    "p_tot_trib_sn": "13.00",
    "pa": "202601",
    "rba": "384226.63",
    "rbaa": "659006.28",
    "rbt12": "370000.00",
    "rbt12p": null,
    "regime_apuracao": "caixa",
    "retificadora": false,
    "rpa_caixa": "64243.51",
    "rpa_competencia": "3700.00",
    "tem_pdf": true,
    "transmitida_em": "2026-09-17T19:18:56Z",
    "versao": "001"
  },
  {
    "anexo": null,
    "anexo_ambiguo": false,
    "anexo_confere": null,
    "consultado_em": "2026-09-22T19:14:54.169000Z",
    "data_abertura": "2019-05-20",
    "faixa": null,
    "fonte": "sync",
    "impedido_iss_no_das": false,
    "iss_retido_no_pa": false,
    "meses_retificados": {},
    "numero_declaracao": "11111111202512001",
    "p_aliq_iss": "4.20",
    "p_tot_trib_sn": "13.00",
    "pa": "202512",
    "rba": "384226.63",
    "rbaa": "659006.28",
    "rbt12": "370000.00",
    "rbt12p": null,
    "regime_apuracao": "caixa",
    "retificadora": false,
    "rpa_caixa": "64243.51",
    "rpa_competencia": "3700.00",
    "tem_pdf": true,
    "transmitida_em": "2026-09-17T19:18:56Z",
    "versao": "001"
  },
  {
    "anexo": null,
    "anexo_ambiguo": false,
    "anexo_confere": null,
    "consultado_em": "2026-09-22T19:14:54.287000Z",
    "data_abertura": "2019-05-20",
    "faixa": null,
    "fonte": "sync",
    "impedido_iss_no_das": false,
    "iss_retido_no_pa": false,
    "meses_retificados": {},
    "numero_declaracao": "11111111202511001",
    "p_aliq_iss": "4.20",
    "p_tot_trib_sn": "13.00",
    "pa": "202511",
    "rba": "384226.63",
    "rbaa": "659006.28",
    "rbt12": "370000.00",
    "rbt12p": null,
    "regime_apuracao": "caixa",
    "retificadora": false,
    "rpa_caixa": "64243.51",
    "rpa_competencia": "3700.00",
    "tem_pdf": true,
    "transmitida_em": "2026-09-17T19:18:56Z",
    "versao": "001"
  },
  {
    "anexo": null,
    "anexo_ambiguo": false,
    "anexo_confere": null,
    "consultado_em": "2026-09-22T19:14:54.409000Z",
    "data_abertura": "2019-05-20",
    "faixa": null,
    "fonte": "sync",
    "impedido_iss_no_das": false,
    "iss_retido_no_pa": false,
    "meses_retificados": {},
    "numero_declaracao": "11111111202510001",
    "p_aliq_iss": "4.20",
    "p_tot_trib_sn": "13.00",
    "pa": "202510",
    "rba": "384226.63",
    "rbaa": "659006.28",
    "rbt12": "370000.00",
    "rbt12p": null,
    "regime_apuracao": "caixa",
    "retificadora": false,
    "rpa_caixa": "64243.51",
    "rpa_competencia": "3700.00",
    "tem_pdf": true,
    "transmitida_em": "2026-09-17T19:18:56Z",
    "versao": "001"
  },
  {
    "anexo": null,
    "anexo_ambiguo": false,
    "anexo_confere": null,
    "consultado_em": "2026-09-22T19:14:54.526000Z",
    "data_abertura": "2019-05-20",
    "faixa": null,
    "fonte": "sync",
    "impedido_iss_no_das": false,
    "iss_retido_no_pa": false,
    "meses_retificados": {},
    "numero_declaracao": "11111111202509001",
    "p_aliq_iss": "4.20",
    "p_tot_trib_sn": "13.00",
    "pa": "202509",
    "rba": "384226.63",
    "rbaa": "659006.28",
    "rbt12": "370000.00",
    "rbt12p": null,
    "regime_apuracao": "caixa",
    "retificadora": false,
    "rpa_caixa": "64243.51",
    "rpa_competencia": "3700.00",
    "tem_pdf": true,
    "transmitida_em": "2026-09-17T19:18:56Z",
    "versao": "001"
  },
  {
    "anexo": null,
    "anexo_ambiguo": false,
    "anexo_confere": null,
    "consultado_em": "2026-09-22T19:14:54.647000Z",
    "data_abertura": "2019-05-20",
    "faixa": null,
    "fonte": "sync",
    "impedido_iss_no_das": false,
    "iss_retido_no_pa": false,
    "meses_retificados": {},
    "numero_declaracao": "11111111202508001",
    "p_aliq_iss": "4.20",
    "p_tot_trib_sn": "13.00",
    "pa": "202508",
    "rba": "384226.63",
    "rbaa": "659006.28",
    "rbt12": "370000.00",
    "rbt12p": null,
    "regime_apuracao": "caixa",
    "retificadora": false,
    "rpa_caixa": "64243.51",
    "rpa_competencia": "3700.00",
    "tem_pdf": true,
    "transmitida_em": "2026-09-17T19:18:56Z",
    "versao": "001"
  }
]

Erros

Ver uma declaração PGDAS-D como dado

GET /api/v1/companies/{company_id}/pgdas/declaracoes/{pa}

UMA declaração PGDAS-D como dado (pa = AAAAMM; versao omitida = a mais recente): tudo da lista mais receitas_mensais (a tabela 2.2 — receita por competência de cada mês desde janeiro do ano anterior; é dela que sai a RBT12 de qualquer mês), atividades (seção 2.7: receita e débitos por atividade, o que dá a efetiva), versoes (todas as versões do PA) e pdf (o caminho do PDF arquivado). 404 DECLARACAO_NAO_ENCONTRADA quando o PA não está no histórico — POST …/pgdas/sync com pa e forcar=true consulta esse PA (R$ 0,24). Qualquer papel com acesso à empresa lê, inclusive o leitor e a chave de API de leitura: quem vê as notas já vê a receita delas.

Parâmetros

Exemplo de chamada

curl -X GET "https://api.gerenota.com.br/api/v1/companies/{company_id}/pgdas/declaracoes/{pa}" \
  -H "Authorization: Bearer $GERENOTA_KEY"

Resposta 200 — OK

Exemplo de resposta

{
  "anexo": "III",
  "anexo_ambiguo": false,
  "anexo_confere": true,
  "atividades": [
    {
      "descricao": "Prestação de Serviços, exceto para o exterior - Não sujeitos ao fator “r” e tributados pelo Anexo III, sem retenção/substituição tributária de ISS, com ISS devido ao próprio Município do estabelecimento",
      "iss": "2062.43",
      "receita": "45756.47",
      "total": "6345.94"
    },
    {
      "descricao": "Prestação de Serviços, exceto para o exterior - Não sujeitos ao fator “r” e tributados pelo Anexo III, com retenção/substituição tributária de ISS",
      "iss": "0.00",
      "receita": "18487.04",
      "total": "1730.67"
    }
  ],
  "consultado_em": "2026-09-22T19:14:53.449000Z",
  "data_abertura": "2019-05-20",
  "faixa": 4,
  "fonte": "historico_s3",
  "impedido_iss_no_das": false,
  "iss_retido_no_pa": false,
  "meses_retificados": {},
  "numero_declaracao": "11111111202607001",
  "p_aliq_iss": "4.51",
  "p_tot_trib_sn": "13.87",
  "pa": "202607",
  "pdf": "/api/v1/companies/cmp_3b50e1e07a2e1cbe/pgdas/declaracoes/202607/pdf?versao=001",
  "rba": "384226.63",
  "rbaa": "659006.28",
  "rbt12": "618794.01",
  "rbt12p": null,
  "receitas_mensais": {
    "2025-01": "49272.72",
    "2025-02": "57480.75",
    "2025-03": "60995.57",
    "2025-04": "54043.34",
    "2025-05": "53693.34",
    "2025-06": "57932.91",
    "2025-07": "56625.90",
    "2025-08": "55239.42",
    "2025-09": "59121.09",
    "2025-10": "49775.79",
    "2025-11": "56314.34",
    "2025-12": "48511.11",
    "2026-01": "45810.35",
    "2026-02": "45257.35",
    "2026-03": "75066.57",
    "2026-04": "49844.95",
    "2026-05": "54580.89",
    "2026-06": "46538.89"
  },
  "regime_apuracao": "caixa",
  "retificadora": false,
  "rpa_caixa": "64243.51",
  "rpa_competencia": "32733.26",
  "tem_pdf": true,
  "transmitida_em": "2026-09-17T19:18:56Z",
  "versao": "001",
  "versoes": [
    {
      "consultado_em": "2026-09-22T19:14:53.449000Z",
      "numero_declaracao": "11111111202607001",
      "retificadora": false,
      "tem_pdf": true,
      "transmitida_em": "2026-09-17T19:18:56Z",
      "versao": "001"
    }
  ]
}

Erros

Baixar o PDF arquivado de uma declaração PGDAS-D

GET /api/v1/companies/{company_id}/pgdas/declaracoes/{pa}/pdf

O PDF arquivado da declaração PGDAS-D do PA (AAAAMM; versao omitida = a mais recente), servido pela própria API (application/pdf, Content-Disposition: inline) — como o DANFSE, sem link do S3: o painel baixa com o token. 404 quando a declaração não foi consultada ou não tem PDF (consultas anteriores ao arquivamento). A empresa precisa estar no recorte de quem chama. Qualquer papel com acesso à empresa lê, inclusive o leitor e a chave de API de leitura: quem vê as notas já vê a receita delas.

Parâmetros

Exemplo de chamada

curl -X GET "https://api.gerenota.com.br/api/v1/companies/{company_id}/pgdas/declaracoes/{pa}/pdf" \
  -H "Authorization: Bearer $GERENOTA_KEY" \
  -o declaracao.pdf

Resposta 200 — O PDF da declaração (application/pdf)

Exemplo de resposta

{
  "_binario": "application/pdf",
  "_bytes": 11
}

Erros

Consultar a declaração PGDAS-D no Integra Contador (paga)

POST /api/v1/companies/{company_id}/pgdas/sync

Consulta a declaração PGDAS-D no Integra Contador (paga) e absorve o resultado: a declaração inteira (regime de apuração, receita do PA por competência e por caixa, RBT12, RBA, a tabela de receitas mensais, a data de transmissão) entra no histórico da empresa com o PDF arquivado; a alíquota do mês é recalculada (só entra se o mês ainda não tinha) e a proxima anunciada; a declaração é conferida contra o mês que ela prova. pa pede um PA só (uma consulta); sem ele, a ordem do calendário.

PAs antigos: cada declaração consultada fica no histórico (GET …/pgdas/declaracoes). Na autorização a plataforma busca sozinha, em segundo plano (poucos minutos), os 13 PAs a partir da declaração mais recente (ela + os 12 meses que formam a RBT12 dela; empresa mais nova, desde a abertura) — uma consulta paga por PA, R$ 0,24, contada e não repassada. Para um PA específico fora disso, chame com pa (AAAAMM) e forcar=true: uma consulta, a declaração entra no histórico e, se for mais antiga que a atual, a alíquota e a ficha da empresa não mudam. O aceite (termo assinado em nome da empresa) é ato do dono — 403 ACEITE_SO_DO_DONO para os demais papéis; a empresa precisa estar no recorte de quem chama (403 EMPRESA_FORA_DO_RECORTE). Chave de API com escopo emissao (papel operador/contabilidade); a de leitura recebe 403 — consultar é operação fiscal (e paga). Custo: cada PA consultado é uma requisição paga; pela API há um teto diário por empresa (429 TETO_DIARIO_PGDAS, 3 consultas) — o histórico entra sozinho, em segundo plano. Quando as consultas pagas da plataforma param até a virada do dia, a resposta é 503 PGDAS_PAUSADO; a alíquota do mês não muda.

Parâmetros

Corpo (JSON)

Exemplo de chamada

curl -X POST "https://api.gerenota.com.br/api/v1/companies/{company_id}/pgdas/sync" \
  -H "Authorization: Bearer $GERENOTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"aceite": true}'

Resposta 200 — OK

Exemplo de resposta

{
  "aliquota": {
    "aplicada": true,
    "atual": {
      "anexo": "III",
      "conta": "13,86 % (ISS 4,50 %): RBT12 R$ (valor) = Σ ago/25..jul/26 do PGDAS 202608 — Anexo III, 4ª faixa",
      "faixa": 4,
      "fonte": "pgdas",
      "iss_fora_do_das": false,
      "janela": [
        "2025-08",
        "2026-07"
      ],
      "mes": "2026-09",
      "meses_estimados": [],
      "p_aliq_iss": "4.50",
      "p_tot_trib_sn": "13.86",
      "proporcional": false,
      "rbt12": "618794.01",
      "tabela": "2018"
    },
    "legado": false,
    "manual": false,
    "mudou_atual": true,
    "mudou_proxima": true,
    "proxima": {
      "anexo": "III",
      "conta": "13,79 % (ISS 4,48 %): RBT12 R$ (valor) = Σ set/25..ago/26 do PGDAS 202608 — Anexo III, 4ª faixa",
      "faixa": 4,
      "fonte": "pgdas",
      "iss_fora_do_das": false,
      "janela": [
        "2025-09",
        "2026-08"
      ],
      "mes": "2026-10",
      "meses_estimados": [],
      "p_aliq_iss": "4.48",
      "p_tot_trib_sn": "13.79",
      "proporcional": false,
      "rbt12": "597948.96",
      "tabela": "2018"
    }
  },
  "anexo": "III",
  "anexo_confere": true,
  "autorizado_em": "2026-09-23T01:42:26.679000Z",
  "conferencia": {
    "aliquota": {
      "veredito": "sem_aliquota"
    },
    "em": "2026-09-23T01:42:26.801972Z",
    "mes": "2026-09",
    "pa": "202608",
    "receita": {
      "avisar": false,
      "base_comparada": "notas_por_competencia",
      "campo_origem": "rpa_competencia",
      "declarada": "34394.37",
      "detalhes": [],
      "doze_meses": {
        "cobertura": false,
        "janela": [
          "2025-08",
          "2026-07"
        ],
        "sem_notas": [
          "2025-08",
          "2025-09",
          "2025-10",
          "2025-11",
          "2025-12",
          "2026-01",
          "2026-02",
          "2026-03",
          "2026-04",
          "2026-05",
          "2026-06",
          "2026-07"
        ]
      },
      "frase": "O PGDAS-D declarou R$ (valor)",
      "frase_titulo": "Agosto: não há nota desse mês no GereNota para comparar.",
      "mes": "2026-08",
      "motivo": "nenhuma nota ativa do mês no GereNota — nada a comparar",
      "notas": "0.00",
      "notas_apos_transmissao": {
        "quantidade": 0,
        "soma": "0.00"
      },
      "pa": "202608",
      "regime_apuracao": "caixa",
      "rotulo": "sem nota no GereNota para comparar",
      "rpa_caixa": "64243.51",
      "transmitida_em": "2026-09-17T19:18:56Z",
      "veredito": "sem_notas"
    },
    "retificados": {}
  },
  "consultado_em": "2026-09-23T01:42:26.821000Z",
  "declaracao": {
    "anexo": "III",
    "anexo_ambiguo": false,
    "anexo_confere": true,
    "consultado_em": "2026-09-23T01:42:26.790881Z",
    "data_abertura": "2019-05-20",
    "faixa": 4,
    "fonte": "sync",
    "impedido_iss_no_das": false,
    "iss_retido_no_pa": false,
    "meses_retificados": {},
    "numero_declaracao": "11111111202608001",
    "p_aliq_iss": "4.51",
    "p_tot_trib_sn": "13.87",
    "pa": "202608",
    "rba": "384226.63",
    "rbaa": "659006.28",
    "rbt12": "618794.01",
    "rbt12p": null,
    "regime_apuracao": "caixa",
    "retificadora": false,
    "rpa_caixa": "64243.51",
    "rpa_competencia": "34394.37",
    "tem_pdf": true,
    "transmitida_em": "2026-09-17T19:18:56Z",
    "versao": "001"
  },
  "faixa": 4,
  "fonte": "pgdas",
  "impedido_iss_no_das": false,
  "iss_retido_no_pa": false,
  "numero_declaracao": "11111111202608001",
  "p_aliq_iss": "4.51",
  "p_tot_trib_sn": "13.87",
  "pa_consultado": "202608",
  "periodo_apuracao": "202608",
  "principal": true,
  "rba": "384226.63",
  "rbaa": "659006.28",
  "rbt12": "618794.01",
  "rbt12p": null,
  "regime_apuracao": "caixa",
  "regime_apuracao_divergencia": null,
  "regime_apuracao_fonte": "rfb",
  "regime_consultado_em": "2026-09-23T01:42:26.848000Z",
  "regimes_apuracao": {
    "2021": "competencia",
    "2025": "caixa",
    "2026": "caixa"
  },
  "rpa_caixa": "64243.51",
  "rpa_competencia": "34394.37",
  "transmitida_em": "2026-09-17T19:18:56Z",
  "versao": "001"
}