# APIFacil Nota Fiscal API v1

> API de emissao de nota fiscal eletronica direto nos ambientes do governo, sem revenda nem intermediario. Autenticacao via header `Authorization: seu_token` (SEM prefixo Bearer), o mesmo token da API de WhatsApp. Este arquivo e o indice: cada modalidade de nota tem o seu proprio llms.txt, completo e autossuficiente.

## Escolha a modalidade

Cada modalidade tem pre-requisitos, leiaute e fluxo de emissao diferentes. Va direto para a que voce precisa:

| Documento | Quando usar | llms.txt | Situacao |
|---|---|---|---|
| **NFS-e** (servico) | Prestacao de servico, qualquer municipio que aderiu ao Padrao Nacional | https://apifacil.dev/fiscal/nfse/llms.txt | disponivel |
| **NF-e** modelo 55 (mercadoria) | Venda para outra empresa, venda para outro estado, remessa, devolucao, transferencia | https://apifacil.dev/fiscal/nfe/llms.txt | em preparacao |
| **NFC-e** modelo 65 (consumidor) | Venda de produto no balcao ou entrega em domicilio ao consumidor final, dentro do estado | https://apifacil.dev/fiscal/nfce/llms.txt | disponivel no RS |

A NFC-e ja emite em producao no Rio Grande do Sul e e liberada estado a estado; fora das UFs habilitadas a emissao em producao devolve 422 com a lista, mas a homologacao esta aberta em qualquer UF. A NF-e continua desligada em todos os estados: qualquer emissao devolve 422, e a documentacao esta publicada so para voce conhecer o contrato — nao conte com ela para fechar contrato.

Apenas o Padrao Nacional da NFS-e e suportado: municipios com emissor proprio da prefeitura nao entram.

## Base URL

A API fiscal responde em um dominio proprio, separado do produto de WhatsApp. Chamar `apifacil.dev/api/v1/...` retorna 404 — o host correto e `nts.apifacil.dev`.

```
Producao: https://nts.apifacil.dev/api/v1
```

## Autenticacao

```
Authorization: seu_token_aqui
Content-Type: application/json
```

Token direto, sem `Bearer`. Gere ou copie no painel do usuario em https://apifacil.dev.

## Assinatura e ambientes

Cada emitente tem um `ambiente`: `1` = producao, `2` = homologacao.

- Homologacao e liberada sem custo, sem assinatura. Use para integrar.
- Producao exige um servico fiscal ativo na conta. Sem ele, os endpoints de emissao respondem `403`.

Cobranca, sempre por CNPJ emitente e por mes:

- **Nota Fiscal** — R$ 39,90, 200 NFS-e inclusas. Excedente por faixa: R$ 0,15 ate 1.000, R$ 0,12 ate 5.000, R$ 0,10 ate 20.000, R$ 0,08 acima disso.
- **Nota Fiscal Varejo** — R$ 59,90, 500 NFC-e inclusas mais 100 documentos dos demais modelos. Excedente: R$ 0,06 por cupom ate 20.000 e R$ 0,04 acima disso; R$ 0,15 por NF-e ou NFS-e alem das 100.

A franquia e a contagem sao por CNPJ emitente e reiniciam todo dia 1. Homologacao nao consome franquia. Documento rejeitado nao consome franquia; documento autorizado que depois foi cancelado consome.

## O que e comum a todas as modalidades

- **Emitente**: o CNPJ que assina a nota. Cadastro e certificado A1 (.pfx) sao feitos uma vez no painel `nts.apifacil.dev`; o certificado nunca trafega pela API.
- **Idempotencia**: mande `referencia_externa` (ate 80 caracteres) em toda emissao. Uma segunda chamada com a mesma referencia no mesmo emitente e recusada em vez de gerar nota duplicada.
- **Consulta, cancelamento, XML**: os endpoints `/api/v1/documentos/...` sao os mesmos para as tres modalidades.
- **Trilha de auditoria**: toda emissao, cancelamento, consulta e download fica registrada numa trilha append-only, visivel em `nts.apifacil.dev/auditoria`, com filtros e exportacao CSV. Nao pode ser editada nem apagada por ninguem, nem pelo suporte.
- **Rate limit**: 120 emissoes por minuto por conta, so nos endpoints que criam documento. `GET /documentos/{id}` e o download do XML ficam fora de qualquer teto. Os endpoints que batem no fisco a cada chamada (`POST /documentos/{id}/consultar` e `GET /emitentes/{id}/status-sefaz`) tem teto proprio de 30 por minuto. Maximo de 990 itens por documento.
- **Emissao assincrona (NFS-e e NFC-e)**: `POST` responde `202` com a nota em `processando`. Guarde o `id`, consulte `GET /api/v1/documentos/{id}` a cada 2 segundos ate sair de `processando`, e nao reemita por demora — use `POST /documentos/{id}/consultar` uma vez se passar de 30 segundos. A NF-e e sincrona: responde `201` ou `422` na propria chamada.
- **Guarde o XML por 5 anos**: e ele que vale perante o fisco, nao o PDF.

## Documentacao em HTML

- NFS-e: https://apifacil.dev/docs/nfse
- NF-e: https://apifacil.dev/docs/nfe
- NFC-e: https://apifacil.dev/docs/nfce
- Painel do emitente, certificado, CSC e auditoria: https://nts.apifacil.dev
- llms.txt da API de WhatsApp v2: https://apifacil.dev/v2/llms.txt