← voltar ao site

Gerado do código a cada release · a referência completa fica na sua conta, em Integrações

API do GereNota

A API REST do GereNota emite, consulta, cancela e substitui a NFS-e do Sistema Nacional (o Emissor Nacional, do gov.br) a partir do seu sistema — o ERP, a loja, o SaaS ou os seus scripts —, com o certificado A1 da empresa guardado no GereNota. Sem certificado, basta uma autorização da empresa no gov.br: aí a API emite e substitui, e o cancelamento sem substituta fica com a empresa, no Emissor Nacional. A API entra no Plano Individual e nos planos acima; a chave é criada no painel, em Integrações.

O que dá para fazer

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. O 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 o certificado válido ou a autorização do gov.br confirmada (GET /companies/{id}/status diz se ela pode emitir). Uma empresa pode ser cadastrada pela API (POST /companies), mas o certificado A1 ou a autorização do gov.br fica com o 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": "11222333000180", "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

Teste × valendo

Idempotência: nunca emita duas vezes

Erros

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

{ "code": "EMPRESA_NAO_ENCONTRADA", "message": "Empresa não encontrada", "hint": "…", "field": "…" }

Limites

A referência completa

Fica na sua conta, nos planos com a API: em Integrações → API para o seu sistema, cada rota com o exemplo de chamada, e o botão Copiar guia para a sua IA, com o guia inteiro em Markdown — os campos, as respostas, os erros e o registro de mudanças. Com a chave, GET /api/v1/guia devolve o mesmo guia: aponte a sua IA para ele.

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.

Mudanças recentes