Documentação da API & Swagger Interativo
Integre seu ERP, e-commerce ou sistema contábil com a plataforma Finzio Fiscal. Consulte rotas, teste endpoints ao vivo no Swagger UI e gere suas chaves de API no painel.
Esquemas de Autenticação
A API do Finzio Fiscal utiliza dois métodos de autenticação:
Ideal para sistemas externos, ERPs e integrações machine-to-machine. As chaves são criadas no menu Administração → Chaves de API e usam HTTP Basic, com o Client ID como usuário e o Client Secret como senha:
Obtido em POST /auth/login. Utilizado pelas telas e por automações de usuários, com controle de perfil e permissões. O login direto pela API cria uma sessão sem renovação automática: vale até o token expirar e é encerrada após um período sem requisições (30 minutos por padrão) ou por POST /auth/logout.
Catálogo por Linha de Produto
A API foi organizada por modelo de negócio para simplificar a jornada de integração:
Entrada de Documentos (DFe)
Sincronização contínua com a SEFAZ através da Distribuição DFe com controle inteligente de NSU, download de XML/PDF e registro de eventos de Manifestação do Destinatário (NF-e) e Desacordo de Transporte (CT-e).
Principais Rotas:
- GET/dfe-docsListagem de documentos recebidos da SEFAZ
- POST/nfe-events/manifestManifestação de NF-e (Ciência, Confirmação, Desconhecimento)
- POST/cte-events/desacordoRegistro de Desacordo de CT-e
- GET/fiscal-documents/lookup/:accessKeyConsulta e download de XML por Chave de Acesso
Emissão Fiscal Multi-Modelo
Emissão síncrona e assíncrona em lote de NF-e (55), NFC-e (65), CT-e (57) e MDF-e (58), com assinatura digital A1 pelo cofre, autorização na SEFAZ, Cancelamento (Tempestivo e Extemporâneo) e Carta de Correção (CC-e).
Principais Rotas:
- POST/integration/nfe-emissionsEmissão de NF-e / CT-e / MDF-e via API de Integração
- POST/integration/nfe-emissions/batchEmissão em lote compactado ZIP
- POST/integration/emission-commandsEmissão assíncrona: 202 na hora, transmissão em fila com retentativa
- GET/integration/emission-commands/:idAndamento do comando e resumo da emissão
- POST/nfe-emissions/:id/cancelCancelamento de NF-e (cStat 135 / 155 extemporâneo)
- POST/nfe-emissions/:id/correctionCarta de Correção Eletrônica (CC-e cumulativa)
Emissão de NFS-e Nacional
NFS-e no padrão nacional pela Sefin, com contrato JSON versionado, numeração de DPS reservada pelo Finzio, assinatura com o A1 do cofre e reconciliação pelo Id da DPS: resposta perdida nunca vira segunda nota. Produção liberada por município homologado.
Principais Rotas:
- POST/integration/nfse-emissionsEmissão de NFS-e (idempotente pela idempotencyKey)
- GET/integration/nfse-emissions/:idSituação, chave de acesso e motivos da Sefin
- POST/integration/nfse-emissions/:id/retryNova tentativa: consulta a Sefin antes de reenviar
- POST/integration/nfse-emissions/:id/cancelCancelamento (evento e101101) dentro do prazo do município
- GET/integration/nfse-emissions/:id/xmlXML da NFS-e autorizada
- GET/integration/nfse-emissions/:id/danfseDANFSe em PDF
Gestão, Cofre e Relatórios
Administração multi-tenant de empresas, cofre de certificados digitais A1 criptografados (AES-GCM), exportação de relatórios analíticos em Excel e auditoria imutável com encadeamento de hash.
Principais Rotas:
- GET/companiesListagem e gestão de empresas cadastradas
- POST/companies/:id/certificateUpload de Certificado Digital A1 (.pfx)
- GET/reports/nfe.xlsxExportação de relatórios analíticos de notas
- GET/audit-logTrilha de auditoria com validação de integridade
Exemplos Rápidos de Requisição
Copie e execute comandos cURL diretamente em seu terminal:
curl -X POST "/api/integration/nfe-emissions" \
-u "<CLIENT_ID>:<CLIENT_SECRET>" \
-H "Content-Type: application/json" \
-d '{
"companyId": "d0df01dd-3cd6-48d4-be48-45554219a1ac",
"modelo": "55",
"numero": 1052,
"serie": 1,
"naturezaOperacao": "VENDA DE MERCADORIA",
"destinatario": {
"cnpj": "11222333000181",
"xNome": "CLIENTE EXEMPLO LTDA"
},
"itens": [
{
"numero": 1,
"codigo": "PROD-001",
"descricao": "PRODUTO FISCAL TESTE",
"ncm": "84713012",
"cfop": "5102",
"quantidade": 1,
"valorUnitario": 150.00
}
]
}'curl -X POST "/api/integration/nfse-emissions" \
-u "<CLIENT_ID>:<CLIENT_SECRET>" \
-H "Content-Type: application/json" \
-d '{
"versao": "1",
"idempotencyKey": "pedido-2026-000123",
"companyId": "d0df01dd-3cd6-48d4-be48-45554219a1ac",
"competencia": "2026-09-28",
"prestador": { "opcaoSimplesNacional": "1", "regimeEspecialTributacao": "0" },
"tomador": { "cnpj": "11222333000181", "nome": "CLIENTE EXEMPLO LTDA" },
"servico": {
"municipioPrestacao": "3550308",
"codigoTributacaoNacional": "010101",
"descricao": "Desenvolvimento de software sob encomenda"
},
"valores": {
"valorServico": 1500.00,
"issqn": { "tributacao": "1", "retencao": "1", "aliquota": 2 }
}
}'curl -X POST "/api/nfe-events/manifest" \
-H "Authorization: Bearer <SEU_TOKEN_JWT>" \
-H "Content-Type: application/json" \
-d '{
"companyId": "d0df01dd-3cd6-48d4-be48-45554219a1ac",
"accessKey": "32260805997742000408550010002117021063754805",
"tipo": "CONFIRMACAO_DA_OPERACAO",
"justificativa": "Operacao realizada e conferida no estoque"
}'curl -X POST "/api/nfe-emissions/37436f6b-ad93-4cbd-ac7c-d33261deea23/cancel" \
-H "Authorization: Bearer <SEU_TOKEN_JWT>" \
-H "Content-Type: application/json" \
-d '{
"xJust": "Cancelamento extemporaneo homologado pela SEFAZ (Proc: 2026/012345)"
}'Municípios com NFS-e em produção
A emissão de NFS-e em produção é liberada por município e regime depois da homologação com evidência registrada. Município fora da lista é recusado antes de qualquer envio, sem consumir quota.
Carregando municípios...
Pronto para testar a API?
Acesse o console interativo do Swagger UI para autorizar suas requisições, enviar payloads e inspecionar as respostas da SEFAZ em tempo real.