Visão geral

A API da LideraNota emite NFS-e no padrão nacional a partir do seu sistema. Este guia explica como integrar, com exemplos de requisição HTTP e de curl que servem para qualquer linguagem de programação. O detalhe de cada campo, com tipos, tamanhos e padrões, está na referência da API.

Fluxo assíncrono

A emissão é assíncrona e em lote: o seu sistema envia de 1 a 500 notas numa requisição, recebe a resposta 202 na hora, com o resultado da recepção de cada nota, e fica sabendo do desfecho (autorizada ou rejeitada pela Sefin Nacional) pelo webhook ou pela consulta.

 Seu sistema                                  LideraNota                       Sefin Nacional
      │  POST /v1/lotes (Authorization)          │                                    │
      │─────────────────────────────────────────►│ recebe as notas aceitas            │
      │◄───── 202: loteId e resultado por nota ──│                                    │
      │                                          │ monta, assina e transmite ────────►│
      │                                          │◄─────────────── autorizada ou      │
      │                                          │                 rejeitada          │
      │◄───── POST no seu webhook (X-Lwnfse-Token)                                    │
      │────── 2xx ──────────────────────────────►│                                    │
      │  GET /v1/notas/{notaId}/xml e /danfse    │                                    │
      │─────────────────────────────────────────►│                                    │

Envio do lote: o seu sistema envia as notas em POST /v1/lotes e guarda o loteId e o id de cada nota aceita (envio do lote).
Desfecho pelo webhook: a LideraNota chama o endereço de webhook do seu sistema a cada desfecho de nota (webhook).
Consulta: a qualquer momento o seu sistema consulta o lote ou a nota, como alternativa e complemento ao webhook (consulta).
Documentos: com a nota autorizada, o seu sistema baixa o XML e o DANFSe (XML e DANFSe).

Depois da autorização, a nota pode ser cancelada (cancelamento), substituída por uma nota corrigida (substituição) ou, quando o cancelamento direto não é mais aceito, levada à análise fiscal do município (análise fiscal).

Status da nota

Status	Significado	O que o seu sistema faz
`recebida`, `pronta`, `enviada`	Em processamento	Aguarda o webhook ou consulta a nota
`autorizada`	NFS-e autorizada pela Sefin Nacional; traz `numeroNfse`, `chaveAcesso`, `autorizadaEm` e `links`. Continua `autorizada` durante uma análise fiscal e depois de um indeferimento	Baixa o XML e, se precisar, o DANFSe
`rejeitada`	Desfecho: recusada pela Sefin Nacional ou pela validação antes do envio; traz `erro` com `codigo` e `mensagem`	Corrige os dados e envia como operação nova, com outro `idOperacao`
`pendente_intervencao`	A emissão não foi concluída por um problema de ambiente (certificado digital, Sefin Nacional sem resposta) e a LideraNota está tratando a causa. Não é rejeição e não traz `erro`	Não reenvia com outro `idOperacao` (a nota pode já estar registrada na Sefin Nacional) e continua consultando: o status ainda pode mudar para `autorizada` ou `rejeitada`. Não gera webhook. Se a nota continuar pendente e você precisar de retorno sobre ela, a LideraNota executa este passo: pedir pelo WhatsApp
`cancelamento_solicitado`	Pedido de cancelamento aceito, aguardando a Sefin Nacional	Aguarda o webhook `cancelada` ou `cancelamento_rejeitado`
`cancelada`	Desfecho: cancelamento registrado, pelo cancelamento direto ou pelo deferimento de uma análise fiscal	Baixa de novo o XML ou o DANFSe, se quiser a marca de cancelada
`substituida`	Desfecho da nota original de uma substituição: a substituta foi autorizada e a Sefin Nacional cancelou a original. Traz `substituidaPor`	Passa a referenciar a nota substituta

Formato das mensagens

JSON em UTF-8 nas requisições e nas respostas, exceto nos downloads do XML e do PDF. Toda requisição com corpo leva Content-Type: application/json.
Datas em ISO 8601: competencia como AAAA-MM-DD; instantes em UTC, por exemplo 2026-11-10T14:03:12.345Z.
Campos sem valor ficam ausentes na resposta, nunca null.
Campos novos: versões novas da API podem acrescentar campos às respostas e ao evento do webhook. O seu sistema deve ignorar o campo que não conhece, em vez de recusar a resposta.
Identificadores: loteId, o id da nota (notaId) e eventoId são UUID.

Próximos passos

Acesso e ambientes: token de acesso, homologação e produção.
Envio do lote e consulta.
Webhook.
Download do XML e do DANFSe.
Cancelamento, substituição e análise fiscal.
Códigos de erro e limites.