Prévia: a API abre junto com o painel.

Documentação do NFSeIA

O NFSeIA emite nota fiscal de serviço (NFS-e Nacional) para empresas de serviço do Simples Nacional (ME e EPP) e MEI, com tomador no Brasil (pessoa física ou empresa), com ou sem ISS retido. Não emite nota de produto (NF-e, NFC-e) e ainda não atende Lucro Presumido, Lucro Real nem cliente no exterior.

Há quatro jeitos de emitir, todos com as mesmas regras e a mesma proteção contra nota em dobro:

• Painel: para emitir à mão, sem programar.
• IA: o Claude ou o ChatGPT emitem por você, pela conexão MCP. Veja Conectar no Claude e no ChatGPT.
• API: o seu sistema emite com uma chamada HTTP. Veja Emitir a primeira nota.
• Automático: nota recorrente, que sai sozinha todo mês, e emissão ao receber pagamento, pelos gatilhos de pagamento.

Como uma nota sai

1. Você manda tomador, serviço e valor, com uma referência sua: o id do pedido, da fatura ou da cobrança no seu sistema.
2. O NFSeIA confere tudo antes de enviar. O que a SEFIN recusaria volta na hora, em português, com o campo e o que fazer.
3. O cofre monta a declaração do serviço (DPS), assina com o certificado digital A1 da empresa e envia ao sistema nacional da nota (SEFIN).
4. A SEFIN autoriza. Voltam o número da nota, a chave de acesso, o XML oficial e o PDF, e o seu cliente recebe a nota por e-mail.

Se a SEFIN não responder a tempo, ou se a resposta ainda precisar ser conferida, a nota fica pendente, com o motivo. O NFSeIA consulta a SEFIN pela mesma DPS até ter resposta definitiva e avisa o seu sistema por webhook. Uma nota pendente nunca é enviada de novo com outro número, e a referência dela não é liberada. Se as consultas acabarem sem resposta, a nota fica pendente com o motivo requer_intervencao e a sua empresa é avisada por e-mail.

Ambientes

A chave de teste sai na hora, no cadastro. A produção só é liberada no painel, pelo dono da conta, com confirmação pelo e-mail da empresa. Recursos criados com uma chave (notas, tomadores, recorrências, gatilhos, webhooks) ficam no ambiente dela: nada atravessa de um para o outro.

Nota em dobro, nunca

O mesmo pedido não vira duas notas, mesmo com clique duplo, tentativa automática do seu sistema ou queda de conexão no meio do caminho. A proteção tem quatro camadas:

1. Idempotency-Key: repetir a mesma requisição devolve a mesma resposta.
2. referencia_externa: única por empresa e ambiente e reservada, junto com o número da DPS, antes de qualquer envio. Repetir a referência, mesmo ao mesmo tempo, devolve a nota que já existe; ela só é liberada se a nota for recusada de forma definitiva.
3. Id da DPS fixo: o número da declaração é reservado antes do envio e nunca muda, então a SEFIN recusa um segundo envio da mesma nota.
4. Consulta antes de reenviar: se a SEFIN não respondeu, o NFSeIA pergunta se a nota existe antes de qualquer nova tentativa.

Palavras que aparecem nesta documentação

• Prestador: a sua empresa, dona do certificado.
• Tomador: o seu cliente, quem recebe o serviço.
• Intermediário: quem intermediou o serviço, quando há.
• DPS: a declaração de prestação de serviço que o NFSeIA monta e envia; a SEFIN responde com a NFS-e.
• NFS-e: a nota fiscal de serviço eletrônica, no padrão nacional.
• SEFIN: o sistema nacional que autoriza a nota.
• Chave de acesso: os 50 números que identificam a nota em qualquer consulta oficial.
• Competência: a data do serviço a que a nota se refere.
• Código de tributação nacional: o código do serviço na lista nacional, escolhido por você e pelo seu contador.
• ISS retido: quando o tomador (ou o intermediário) recolhe o ISS no lugar do prestador.
• Padrões da nota: código, descrição, local e impostos definidos no cadastro, usados quando a emissão não informa.

Por onde seguir

• Autenticação e ambientes: chaves, escopos, idempotência e formatos.
• Emitir a primeira nota: em curl, Node e Python.
• Integre usando IA: um pedido pronto para o seu assistente de código.
• Webhooks e gatilhos de pagamento.
• Erros e limites e a referência da API.