# Integre o NFSeIA no seu sistema usando IA

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

Se você usa um assistente de código (Claude Code, Cursor, ChatGPT ou outro), ele pode escrever a
integração por você. Copie o pedido abaixo, cole no assistente aberto no seu projeto e acompanhe:
ele lê o contrato da API, mostra o plano e só então mexe nos arquivos.

O assistente lê duas fontes, sempre atualizadas:

- [openapi.yaml](https://nfseia.com.br/docs/openapi.yaml): o contrato da API (OpenAPI 3.1), com todos os campos, erros e
  exemplos.
- [llms-full.txt](https://nfseia.com.br/llms-full.txt): a documentação inteira em texto, feita para IA.

## O pedido para colar

```text
Você vai integrar o NFSeIA (emissão de nota fiscal de serviço, NFS-e Nacional) neste projeto.

Fontes (leia antes de escrever código):
- Contrato OpenAPI 3.1: https://nfseia.com.br/docs/openapi.yaml
- Documentação completa em texto: https://nfseia.com.br/llms-full.txt

Contexto:
- Endereço base: https://api.nfseia.com.br/v1. Autenticação: "Authorization: Bearer <chave>".
- Use a chave de teste (nfs_test_...) lida da variável de ambiente NFSEIA_CHAVE. Nunca escreva a
  chave no código, em log ou no front-end.
- Campos em português e snake_case. Valores em texto com ponto e duas casas ("1500.00").

O que fazer:
1. Ache no projeto o momento em que a nota deve sair (pedido pago, fatura quitada, serviço
   concluído) e me mostre antes de mudar qualquer coisa.
2. Crie um módulo pequeno para a API do NFSeIA: emitir (POST /notas), consultar (GET /notas/{id}),
   cancelar (POST /notas/{id}/cancelar) e baixar o PDF, com tempo limite de 35 segundos.
3. Na emissão, use referencia_externa = id do pedido no nosso banco (sem os prefixos reservados
   pagamento:, recorrencia: e mcp:). Gere a Idempotency-Key uma vez por tentativa, guarde junto do
   pedido e reutilize em toda repetição da mesma chamada.
4. Trate as respostas: 201 autorizada (guarde id, numero, chave_acesso e links); 202 pendente
   (guarde o id e o pendencia.motivo e espere o webhook); 200 a nota já existia (é sucesso); 400
   dados_invalidos e 422 nota_rejeitada (mostre erro.mensagem, erro.como_resolver e erro.detalhes,
   não repita sem corrigir); 409 idempotencia_em_andamento, 429 e 5xx (repita com a mesma
   Idempotency-Key, respeitando Retry-After).
5. Crie a rota que recebe os webhooks nota.autorizada, nota.rejeitada, nota.pendente_resolvida e
   nota.cancelada. Confira o cabeçalho NFSeIA-Assinatura antes de ler o JSON: HMAC-SHA256 de
   "{t}.{corpo bruto}" com o segredo do webhook, recusando t a mais de 5 minutos do horário atual
   (no passado ou no futuro), comparação em tempo constante, aceitando qualquer v1 que confira.
   Descarte eventos repetidos pelo id do corpo já autenticado. Responda 2xx em menos de 10 segundos
   e processe depois.
6. Guarde no nosso banco o id da nota, o status, o número, a chave de acesso e os links. Não guarde
   o XML nem o PDF; baixe quando precisar.
7. Escreva testes com a chave de teste. Na descrição do serviço, [simular:rejeitada] e
   [simular:pendente] forçam esses caminhos.

Regras:
- Use só a chave de teste. A produção é liberada pelo dono da conta no painel do NFSeIA.
- Não decida código de serviço, alíquota nem retenção de ISS: use os padrões da empresa
  (GET /empresa, campo padroes_da_nota) ou me pergunte.
- Não registre em log a chave, o segredo do webhook, o corpo das notas nem e-mail, CPF ou CNPJ de
  clientes.
- Responda em português e me mostre o plano antes de editar arquivos.
```

## Boas práticas que o pedido já cobre

- **Uma nota por pedido, sempre.** A `referencia_externa` é o id do pedido; mesmo que o seu sistema
  repita a chamada, a nota é uma só. Veja [Autenticação e ambientes](https://nfseia.com.br/docs/autenticacao#idempotencia).
- **Pendente não é erro.** Quando a SEFIN demora, a nota fica `pendente` e o NFSeIA resolve sozinho.
  Não emita de novo com outra referência.
- **Webhook com assinatura conferida.** Sem conferir a assinatura, qualquer um poderia marcar um
  pedido como faturado no seu sistema. Veja [Webhooks](https://nfseia.com.br/docs/webhooks).
- **Teste antes.** O ambiente de teste imita a emissão de verdade, inclusive recusa e demora da
  SEFIN.

## Prefere que a IA emita a nota, sem programar?

Isso é outra coisa: conectar o NFSeIA direto no Claude ou no ChatGPT, para pedir a nota numa
conversa. Veja [Conectar no Claude e no ChatGPT](https://nfseia.com.br/docs/mcp).