Referência

Documentação da API v1

Um único contrato REST para emitir, cancelar e confirmar NF-e, NFC-e e NFS-e. Todas as respostas são JSON com o corpo em dados ou erro.

Autenticação

Gere uma chave no painel, em Chaves de API. A chave é exibida uma única vez e fica vinculada a uma organização, opcionalmente a uma empresa, e a um ambiente (homologação ou produção).

Authorization: Bearer fsk_a1b2c3_restante-da-chave
# alternativa
x-api-key: fsk_a1b2c3_restante-da-chave

Escopos disponíveis: nfe:emitir, nfe:cancelar, nfe:consultar.

Endpoints

POST/api/public/v1/documentosescopo: nfe:emitir

Emite NF-e (55), NFC-e (65) ou NFS-e. Aceita header Idempotency-Key para evitar duplicidade.

curl -X POST https://flux-fiscal-api.lovable.app/api/public/v1/documentos \
  -H "Authorization: Bearer fsk_xxx_yyy" \
  -H "Idempotency-Key: pedido-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": "nfe",
    "empresa_id": "00000000-0000-0000-0000-000000000000",
    "natureza_operacao": "Venda de mercadoria",
    "destinatario": { "nome": "Cliente LTDA", "documento": "12345678000199" },
    "itens": [
      { "codigo": "SKU-1", "descricao": "Produto", "ncm": "61091000",
        "cfop": "5102", "unidade": "UN", "quantidade": 2, "valor_unitario": 49.9 }
    ]
  }'

GET/api/public/v1/documentos

Lista documentos da organização com filtros por tipo, status, empresa e período.

GET/api/public/v1/documentos/{id}

Detalha o documento com itens e a trilha completa de eventos fiscais.

GET/api/public/v1/documentos/{id}/xml

Baixa o XML do documento (layout 4.00 para NF-e/NFC-e, RPS ABRASF 2.04 para NFS-e).

GET/api/public/v1/documentos/{id}/pdf

Gera o DANFE, o DANFE NFC-e ou o DANFS-e em PDF pronto para impressão.

POST/api/public/v1/documentos/{id}/cancelarescopo: nfe:cancelar

Cancela o documento autorizado. Exige justificativa de 15 a 255 caracteres.

curl -X POST .../documentos/{id}/cancelar \
  -H "Authorization: Bearer fsk_xxx_yyy" \
  -d '{ "justificativa": "Pedido cancelado pelo cliente antes do envio" }'

POST/api/public/v1/documentos/{id}/carta-correcaoescopo: nfe:emitir

Registra CC-e (até 20 sequências) para NF-e e NFC-e autorizadas.

GET · POST/api/public/v1/inutilizacoes

Consulta e registra inutilização de faixas de numeração não utilizadas.

Ciclo de vida do documento

rascunhoDocumento criado, ainda não enfileirado.

em_processamentoNa fila de transmissão para SEFAZ/prefeitura.

autorizadaAutorizada com protocolo; XML e PDF disponíveis.

rejeitadaRejeitada pelo fisco; veja motivo_status.

denegadaDenegada por irregularidade do emitente ou destinatário.

canceladaCancelada com evento registrado.

inutilizadaFaixa de numeração inutilizada.

Webhooks assinados

Cadastre a URL no painel e valide a assinatura HMAC SHA-256 do corpo bruto usando o segredo do webhook.

x-fiscalis-evento: documento.autorizado
x-fiscalis-assinatura: sha256=<hmac_sha256(segredo, corpo)>

{
  "evento": "documento.autorizado",
  "enviado_em": "2026-01-01T12:00:00.000Z",
  "dados": {
    "documento_id": "uuid",
    "status": "autorizada",
    "protocolo": "135240000123456",
    "chave_acesso": "35240100000000000000550010000000011000000017"
  }
}

• documento.autorizado
• documento.rejeitado
• documento.cancelado
• documento.denegado
• documento.carta_correcao
• inutilizacao.concluida

Erros

400 JSON inválido · 401 chave inválida · 403 escopo insuficiente · 404 não encontrado · 409 conflito de estado · 422 payload inválido (lista de detalhes).