API da NFS-e nacional: o que é e como integrar

Q: Preciso saber o cTribNac para emitir?

Só no cadastro do serviço, uma vez; o catálogo em GET /v1/catalogo/servicos?q= acha o código pela descrição. A emissão usa o serviço principal ou o servicoid que você mandar. Confirme o código com o contador do cliente.

Q: O que acontece se o portal cair no meio da emissão?

O pedido fica incerta até o emissaoja conseguir conferir. Chame POST /v1/emissoes/{id}/conferir; se não resolver, confira no portal antes de emitir de novo. Enquanto houver uma incerta pendente, nova emissão igual volta 409 incertapendente.

A NFS-e nacional é o padrão único de Nota Fiscal de Serviço eletrônica que substitui, município a município, os sistemas próprios das prefeituras. A empresa emite pelo Emissor Nacional, com CNPJ e senha ou certificado, e a nota é guardada no Ambiente de Dados Nacional (ADN). A API do emissaoja fala com esse padrão por você: você envia tomador, valor e descrição, e recebe a nota autorizada com número, chave de acesso, PDF e XML.

O que é a NFS-e nacional

Antes do padrão nacional, cada prefeitura tinha um sistema, um leiaute e um login. O padrão nacional unifica os três:

Emissor Nacional: o portal do governo (nfse.gov.br) onde a empresa emite, consulta e cancela notas. Para MEI e empresas do Simples Nacional, aceita entrar com CNPJ e senha, sem certificado digital.
ADN (Ambiente de Dados Nacional): o repositório onde todas as notas do padrão ficam guardadas e de onde a prefeitura e o tomador as consultam.
Municípios aderentes: pela lista oficial do portal da NFS-e, praticamente todos os municípios têm convênio com o padrão nacional, mas só parte deles emite pelo Emissor Nacional; os outros usam o emissor próprio da prefeitura, integrado ao ambiente nacional. A página de cada cidade em /emitir-nfse/ existe só para municípios que emitem pelo Emissor Nacional e mostra as alíquotas de ISS publicadas.

Se o município do seu cliente usa emissor próprio, a nota sai pelo sistema da prefeitura, em geral com certificado digital. Veja /api-nfse-sem-certificado-digital para esse recorte.

O que a API abstrai

O leiaute nacional pede dados que o seu sistema normalmente não tem. A API do emissaoja resolve cada um deles uma vez, no cadastro da empresa, e deixa a emissão com três campos.

Código nacional do serviço (cTribNac). Cada serviço do padrão tem um código da lista nacional. Você cadastra o serviço em POST /v1/servicos com descricao, c_trib_nac, trib_issqn e retem_iss; o catálogo em GET /v1/catalogo/servicos?q= encontra o código por texto. Na emissão, omitir servico_id usa o serviço principal.

NBS e código municipal. A Nomenclatura Brasileira de Serviços (nbs) e o código municipal (c_trib_mun) são opcionais no cadastro do serviço e só entram quando o município exige.

Alíquota e regime. Ao conectar a empresa, o emissaoja lê o cadastro fiscal no portal. O que o cadastro não responde sozinho, como a alíquota do Simples de uma ME, aparece em GET /v1/empresa/onboarding e é respondido em PUT /v1/empresa/fiscal. Emitir antes de onboarding.estado chegar a pronto devolve 422 nota_bloqueada com bloqueios[] e a acao de cada um. A alíquota depende do município e do regime; confirme com o contador o que a API pedir.

Autorização assíncrona. O Emissor Nacional não responde na hora. Por isso POST /v1/notas devolve 202 com um pedido, e você acompanha em GET /v1/emissoes/{id} até o estado sair de na_fila → emitindo → confirmando para autorizada, recusada ou incerta. A resposta traz proxima_consulta_ms para a próxima consulta. Quando o portal não confirma a tempo se a nota saiu, o estado fica incerta e POST /v1/emissoes/{id}/conferir tenta resolver; o emissaoja não emite de novo até saber.

Idempotência. O cabeçalho Idempotency-Key é obrigatório. Repetir a mesma chave devolve o mesmo pedido com repetido: true; nota igual no mesmo dia volta 409 possivel_duplicada.

Cancelamento. POST /v1/notas/{origem}/{id}/cancelar com motivo "1" ou "2" e justificativa opcional devolve 202 com a operacao, acompanhada em GET /v1/operacoes/{id}. Nota não se altera: para corrigir, cancele e emita outra.

Como começar

Crie a conta em https://sandbox.emissaoja.com.br com o Google e gere uma chave ej_test_ em Conta → API. O sandbox tem um Emissor Nacional simulado: nada existe no fisco, nada é cobrado.
Conecte uma empresa de exemplo. 11111111000191 é um MEI pronto para emitir; 22222222000191 é uma ME que pede a alíquota do Simples antes, útil para testar o onboarding.
Crie um tomador e emita.

curl -X POST https://sandbox.emissaoja.com.br/v1/notas \
  -H "Authorization: Bearer ej_test_SUA_CHAVE" \
  -H "Idempotency-Key: pedido-2026-10-0001" \
  -H "Content-Type: application/json" \
  -d '{"tomador_tipo":"pj","tomador_id":"<id do tomador>","valor":1500,"descricao":"Consultoria de outubro"}'

Para ver cada estado final, use os valores com significado do sandbox: 13,13 gera uma nota incerta que conferir resolve como autorizada, 77,77 uma incerta que não saiu e 99,99 uma recusada. O sandbox é reiniciado a cada publicação do emissaoja: a empresa continua conectada, as notas somem.

Em produção, troque a base por https://emissaoja.com.br e a chave por uma ej_live_. O passo a passo completo, com exemplos em JavaScript e Python, está em /docs/.

Limites conhecidos

Público: MEI, ME e EPP optantes pelo Simples Nacional, em um município. Quem não é do Simples ou emite em mais de um município fica fora.
Tributação: trib_issqn aceita tributavel e nao_incidencia. Isenção, imunidade e exportação não são atendidas.
CNPJ: só com números. CNPJ com letras ainda não é aceito.
Uma empresa por conta. Para vários CNPJs, uma conta e uma chave por empresa.
Taxas: 60 chamadas por minuto por chave, 10 emissões por minuto, 120 em buscas e catálogo. Acima disso, 429 rate_limited com Retry-After.
Plano: o Grátis tem 1 nota por mês; os pagos vão de 5 notas (R$ 19,90) a ilimitado (R$ 199,90). A nota conta quando o Emissor Nacional aceita o pedido; recusada não conta. No limite, 402 limite_notas.
Webhooks: ainda não. Acompanhe o pedido com proxima_consulta_ms. Com o portal fora, 503 motor_indisponivel ou fila_indisponivel: repita com a mesma Idempotency-Key.

Há também o caminho por assistente, em /emitir-nota-fiscal-por-ia.

Perguntas frequentes

Minha cidade usa emissor próprio, e não o Emissor Nacional. A API funciona?

Não. O emissaoja emite só pelo Emissor Nacional. Confira a cidade em /emitir-nfse/; quando a prefeitura passar a emitir pelo Emissor Nacional, basta conectar a empresa.

Preciso saber o cTribNac para emitir?

Só no cadastro do serviço, uma vez; o catálogo em GET /v1/catalogo/servicos?q= acha o código pela descrição. A emissão usa o serviço principal ou o servico_id que você mandar. Confirme o código com o contador do cliente.

O que acontece se o portal cair no meio da emissão?

O pedido fica incerta até o emissaoja conseguir conferir. Chame POST /v1/emissoes/{id}/conferir; se não resolver, confira no portal antes de emitir de novo. Enquanto houver uma incerta pendente, nova emissão igual volta 409 incerta_pendente.