API v1 — FLUXO NFE

Como autenticar, quais escopos marcar e como emitir NF-e, NFS-e, cobranças avulsas e recorrentes.

OpenAPI JSON Changelog Voltar ao Master
Contrato v1 congelado desde 2026-08-06: não fazemos breaking changes em rotas, escopos nem no envelope de resposta. Novidades são só aditivas; remoções exigem futura /api/v2. Veja a política em /api-changelog.html ou GET /api/v1/changelog.
A chave completa (fnfe_…) aparece uma vez ao criar. Crie a chave no tenant (Empresas → Configurar → API Keys ou Configurações da loja), marcando os escopos necessários. Digitar só notas não funciona — use os códigos da lista (ex.: notas:emitir).

Autenticação

Base URL (exemplo lab): http://192.168.4.100:5000/api/v1 · Produção: https://saas.fluxonfe.com.br/api/v1

X-Api-Key: fnfe_xxxxxxxxxxxxxxxx
# ou
Authorization: Bearer fnfe_xxxxxxxxxxxxxxxx

Teste rápido:

GET /api/v1/health          (público — inclui stability: frozen)
GET /api/v1/scopes          (público — catálogo de escopos)
GET /api/v1/changelog       (público — política + histórico)
GET /api/v1/openapi.json    (público — OpenAPI 3)
GET /api/v1/me              (autenticado — empresa_id e scopes da chave)

Escopos

Marque na criação da chave. Sem o escopo correto a API responde 403.

EscopoPermite
notas:emitirEmitir NF-e e NFS-e
notas:lerConsultar notas, XML, PDF, status
notas:cancelarCancelar notas
cadastros:lerLer clientes e produtos
cadastros:escreverCriar clientes
cobrancas:lerListar/consultar cobranças avulsas
cobrancas:criarCriar e enviar cobranças ao gateway
cobrancas:gerenciarMarcar paga / cancelar
contratos:lerListar contratos recorrentes
contratos:escreverCriar / atualizar / desativar contratos
contratos:gerarGerar cobrança a partir do contrato

Formato de resposta

Sucesso

{
  "success": true,
  "data": { "...": "..." },
  "meta": { "pagination": { "total": 10, "pagina": 1 } }
}

Erro

{
  "success": false,
  "error": {
    "code": "INVALID_SCOPES",
    "message": "Escopo necessário: notas:emitir"
  }
}

NF-e e NFS-e

Mesmo endpoint. Informe tipo: "NFE" ou tipo: "NFSE". Header Idempotency-Key obrigatório na emissão.

POST /api/v1/notas
X-Api-Key: fnfe_...
Idempotency-Key: pedido-12345
Content-Type: application/json

{
  "tipo": "NFSE",
  "cnpj_tomador": "12345678000199",
  "razao_social_tomador": "Cliente Exemplo LTDA",
  "valor_total": 150.00,
  "descricao_servico": "Serviço de instalação",
  "itens": [{ "descricao": "Instalação", "quantidade": 1, "valor_unitario": 150.00 }]
}
MétodoRotaEscopo
POST/notasnotas:emitir
GET/notas · /notas/:idnotas:ler
GET/notas/:id/xml · /pdf · /statusnotas:ler
POST/notas/:id/cancelarnotas:cancelar

Filtros na listagem: ?tipo=NFSE&status=autorizada&pagina=1&limite=20

Cobranças avulsas

POST /api/v1/cobrancas
X-Api-Key: fnfe_...
Content-Type: application/json

{
  "cliente_id": 12,
  "descricao": "Serviço avulso agosto",
  "valor": 199.90,
  "meio": "pix",
  "vencimento_em": "2026-08-20",
  "enviar_gateway": true,
  "emitir_nf": false
}
MétodoRotaEscopo
GET/cobrancas · /cobrancas/:id · /:id/eventoscobrancas:ler
POST/cobrancas · /:id/enviarcobrancas:criar
POST/:id/marcar-paga · /:id/cancelarcobrancas:gerenciar

meio: pix | boleto | cartao. Gateway precisa estar configurado no tenant.

Cobranças recorrentes (contratos)

POST /api/v1/contratos
X-Api-Key: fnfe_...
Content-Type: application/json

{
  "cliente_id": 12,
  "descricao": "Mensalidade suporte",
  "valor": 97.00,
  "meio": "pix",
  "dia_vencimento": 10,
  "antecipacao_dias": 5,
  "alerta_intervalo_horas": 24,
  "alerta_max": 10,
  "emitir_nf": false,
  "tipo_nf": "nenhuma"
}
POST /api/v1/contratos/3/gerar
{ "competencia": "2026-08" }
MétodoRotaEscopo
GET/contratos · /contratos/:idcontratos:ler
POST / PUT / DELETE/contratoscontratos:escrever
POST/contratos/:id/gerarcontratos:gerar

Cadastros

MétodoRotaEscopo
GET/clientes · /clientes/busca/:documentocadastros:ler
POST/clientescadastros:escrever
GET/produtos · /produtos/:idcadastros:ler

Webhooks (receber eventos)

Configure a URL no painel. Eventos assinados com HMAC-SHA256 no header X-Webhook-Signature.

GET /api/v1/webhooks/events

Rate limits

Spec completa: /api/v1/openapi.json · Changelog: /api-changelog.html · JSON: /api/v1/changelog