# Notas fiscais — visão geral

A ValidaPay emite nota fiscal de serviço (NFS-e) pelo CNPJ do seu cliente, a partir de uma **configuração fiscal** cadastrada uma vez por empresa emissora.

Hoje o único modelo suportado é `NFSE`. O campo `type` já existe nas rotas para quando outros modelos forem liberados.

## Configuração fiscal

É o cadastro da empresa emissora: CNPJ, regime tributário, certificado digital A1, tributos padrão e o momento da emissão. Fica em `/v1/invoices/notas/config` e devolve um `id` no formato `unc_...`.

Esse `id` circula com dois nomes:

| Onde | Campo |
|---|---|
| Emissão avulsa (`POST /v1/invoices/notas`) | `configId` |
| Cobrança, produto e assinatura | `nfConfigId` |

Uma conta pode ter várias configurações — uma por empresa. O CNPJ em `prestador.cnpj` define de qual empresa a nota sai.

Criar ou atualizar uma configuração valida e registra a empresa emissora. Se essa etapa falhar, nada é gravado e o certificado enviado é descartado: não existe configuração pela metade.

### Certificado e credencial da prefeitura

O certificado digital A1 (`certificate.pfx_base64` + `password`) é o que autoriza a emissão. A senha nunca volta nas consultas — a resposta traz apenas `has_certificate` e `expiry_date`.

Municípios com sistema próprio podem exigir também uma credencial do portal, no bloco `prefeitura` — nem todos pedem `login`, e há municípios em que só a senha é necessária. Em parte deles o que vai em `senha` é uma chave digital gerada no portal, e não a senha de acesso.

O mesmo bloco leva a numeração da NFS-e municipal: `serie_rps` e `proximo_numero_rps` continuam a sequência que a prefeitura já registrou para a empresa. Em branco, ela começa do início. No PUT, `prefeitura` é mesclado com o que já está gravado — dá para alterar só a série sem reenviar a senha.

No padrão nacional a série equivalente é `serie_dps`, no primeiro nível da configuração: ela é declarada no cadastro da empresa e vai em cada emissão, então precisa bater com a registrada na prefeitura.

## Municipal ou nacional

O código IBGE em `prestador.codigo_municipio` decide por qual padrão a nota sai, e isso muda quais campos da configuração são lidos:

| Padrão | Quando | Campos usados |
|---|---|---|
| NFS-en nacional | Município no padrão nacional — a maioria | `codigo_tributacao_nacional_iss`, `tributacao_iss`, `tipo_retencao_iss`, `serie_dps`, PIS/COFINS ou Simples |
| NFS-e municipal | Município com sistema próprio | `item_lista_servico`, `aliquota_iss`, `iss_retido`, `natureza_operacao`, `codigo_cnae`, `codigo_tributario_municipio`, `prefeitura.serie_rps` |

A rota é resolvida na emissão, a partir do município. `tipo_nf` (`municipal` ou `nacional`) força um dos dois e só faz sentido quando o município aceita ambos.

Na dúvida, preencha os dois conjuntos: o que não se aplica ao padrão do município é ignorado.

## Campos exigidos pelo regime

O regime vem de `prestador.codigo_opcao_simples_nacional`, sempre número:

| Valor | Regime | Campos obrigatórios |
|---|---|---|
| 1 | Não optante | `situacao_tributaria_pis_cofins`, `aliquota_pis`, `aliquota_cofins` |
| 2 | MEI | `percentual_total_tributos_simples_nacional` |
| 3 | ME/EPP | `percentual_total_tributos_simples_nacional` |

Faltando um deles, a configuração não é gravada e a resposta traz a mensagem da validação com o código `INTERNAL_ERROR`.

## Como uma nota nasce

| Caminho | Rota | Quando usar |
|---|---|---|
| Automática pela cobrança | `nfConfigId` em `POST /v1/charges` | A nota sai junto da cobrança, sem chamada extra |
| Automática pela assinatura | `nfConfigId` no produto ou na assinatura | Emissão a cada ciclo, sem repetir o campo por cobrança |
| Avulsa | `POST /v1/invoices/notas` | Serviço cobrado fora da plataforma |
| Manual de uma cobrança | `POST /v1/invoices/notas/{notaId}/emitir` | Cobrança que ficou sem nota ou cuja emissão falhou |

Com `nfConfigId` na cobrança, `customer.address` passa a ser obrigatório — a nota precisa do endereço do tomador.

## Momento da emissão

`invoiceTiming`, na configuração fiscal, vale para as notas geradas por cobrança:

| Valor | Emissão |
|---|---|
| `IMMEDIATE` | Junto com a cobrança. É o padrão |
| `AFTER_CONFIRMATION` | Após a confirmação do pagamento |
| `DAYS_AFTER_CONFIRMATION` | `daysAfterConfirmation` dias após a confirmação (padrão 1) |

A emissão avulsa sai sempre na hora, qualquer que seja o valor configurado.

Configurações criadas pelo painel trazem também `quando_emitir`, com os mesmos valores — é apenas o espelho gravado pela tela. Quem define o agendamento é `invoiceTiming`.

## Status da nota

| Status | Significado |
|---|---|
| `PROCESSING` | Enviada; a prefeitura ainda não respondeu |
| `ISSUED` / `AUTHORIZED` | Autorizada. Equivalentes: o primeiro vem da emissão síncrona, o segundo da confirmação da prefeitura |
| `FAILED` / `ERROR` | Recusada; `nf.errors` traz as mensagens |
| `CANCELED` | Cancelada na prefeitura |
| `REPLACED` | Substituída por uma reemissão |

No filtro `status` da listagem os pares são intercambiáveis: `AUTHORIZED` traz também as `ISSUED`, e `ERROR` traz também as `FAILED`.

**Não há evento de webhook para nota fiscal.** A prefeitura responde de forma assíncrona: acompanhe o desfecho consultando a nota.

## O identificador da nota

Todas as rotas de nota usam o mesmo identificador, o campo `invoiceId` da listagem:

- na nota avulsa, é o `ref` que você informou na emissão (ou o gerado pela API, quando omitido);
- na nota de cobrança, é o identificador da cobrança.

O campo `ref` da resposta é outra coisa: o identificador interno da nota, útil só para suporte.

## Rotas

| Método | Path | Função |
|---|---|---|
| GET | `/v1/invoices/notas` | Lista as notas. Filtros: `limit`, `lastKey`, `search`, `taxId`, `customerName`, `status`, `startDate`, `endDate` |
| GET | `/v1/invoices/notas/summary` | Totais por status, em quantidade e valor |
| GET | `/v1/invoices/notas/{notaId}` | Detalhe, links de PDF e XML, erros da prefeitura |
| POST | `/v1/invoices/notas` | Emite nota avulsa |
| POST | `/v1/invoices/notas/{notaId}/emitir` | Emite a nota de uma cobrança existente |
| POST | `/v1/invoices/notas/{notaId}/verificar-emissao` | Confere os dados sem emitir |
| POST | `/v1/invoices/notas/{notaId}/reemitir` | Nova tentativa para uma emissão recusada |
| POST | `/v1/invoices/notas/{notaId}/reenviar` | Reenvia a nota por e-mail, até 10 destinatários |
| DELETE | `/v1/invoices/notas/{notaId}?motivo=` | Cancela na prefeitura |
| GET | `/v1/invoices/notas/config` | Lista as configurações fiscais e os `defaults` da conta |
| GET | `/v1/invoices/notas/config/{configId}` | Detalhe da configuração |
| POST | `/v1/invoices/notas/config` | Cria a configuração fiscal |
| PUT | `/v1/invoices/notas/config/{configId}` | Atualiza a configuração |
| DELETE | `/v1/invoices/notas/config/{configId}` | Exclui a configuração |

Escopos: `nota.fiscal/read` nas consultas, `nota.fiscal/write` nas demais.

## Erros

| Código | Significado |
|---|---|
| `MISSING_FIELDS` | Falta `customer.document`, `amount`, `descricao` ou `configId` |
| `NOTA_TYPE_NOT_SUPPORTED` | `type` diferente de `NFSE` |
| `NOTA_CONFIG_NOT_FOUND` | Configuração inexistente ou desabilitada |
| `NF_CONFIG_REQUIRED` | Nenhuma configuração encontrada para a cobrança |
| `NF_INCOMPLETE_DATA` | Faltam dados do tomador; `details` lista o que falta |
| `INVOICE_STATUS_NOT_EMITTABLE` | Só emite cobrança pendente, aguardando pagamento ou paga |
| `NOTA_ALREADY_ISSUED` | Já existe nota autorizada, vinculada ou agendada |
| `NOTA_PROCESSING` | Emissão em andamento aguardando o retorno da prefeitura |
| `NOTA_NOT_ISSUED` | Reenvio de nota que ainda não foi autorizada |
| `TOO_MANY_EMAILS` | Mais de 10 destinatários no reenvio |
| `NF_NOT_AUTHORIZED` | Cancelamento de nota que não está autorizada |
| `NF_CANCEL_FAILED` | A prefeitura recusou o cancelamento — normalmente prazo vencido |
| `NOTA_NOT_FOUND` | Nota inexistente, excluída ou de outra conta |

## Boas práticas

- Rode `POST /v1/invoices/notas/{notaId}/verificar-emissao` antes de emitir: ele devolve em `pendencias` exatamente o que falta no cadastro do cliente, sem emitir nada.
- Guarde o `invoiceId` da nota logo após a emissão — é a chave de todas as outras rotas.
- Acompanhe `certificate.expiry_date` das configurações: certificado vencido derruba a emissão inteira da empresa.
- Corrija a causa antes de reemitir. A mensagem da prefeitura está em `nf.errors`, na consulta da nota.
- Nota autorizada não se corrige: cancele dentro do prazo do município e emita outra.