# Documentação do NFSeIA

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

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](https://nfseia.com.br/docs/mcp).
- **API:** o seu sistema emite com uma chamada HTTP. Veja [Emitir a primeira nota](https://nfseia.com.br/docs/primeira-nota).
- **Automático:** nota recorrente, que sai sozinha todo mês, e emissão ao receber pagamento, pelos
  [gatilhos de pagamento](https://nfseia.com.br/docs/gatilhos).

## 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

|  | Teste | Produção |
| --- | --- | --- |
| Chave | `nfs_test_...` | `nfs_live_...` |
| Certificado digital | não precisa | e-CNPJ A1 da empresa |
| SEFIN | simulada | real |
| Valor fiscal | nenhum | nota de verdade |
| E-mail da nota | só para você | para o seu cliente e para você |
| Conta na cota do plano | não | sim |

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](https://nfseia.com.br/docs/autenticacao): chaves, escopos, idempotência e formatos.
- [Emitir a primeira nota](https://nfseia.com.br/docs/primeira-nota): em curl, Node e Python.
- [Integre usando IA](https://nfseia.com.br/docs/integre-com-ia): um pedido pronto para o seu assistente de código.
- [Webhooks](https://nfseia.com.br/docs/webhooks) e [gatilhos de pagamento](https://nfseia.com.br/docs/gatilhos).
- [Erros e limites](https://nfseia.com.br/docs/erros) e a [referência da API](https://nfseia.com.br/docs/referencia).