Developers / Fiscal API
API fiscal externa para parceiros que precisam operar com clareza, nao com promessa vazia.
Esta pagina documenta a superficie publica fiscal que a Finnextho ja expoe hoje para parceiros contabilistas, ERP e automacao supervisionada por IA. O que esta aqui e o que existe. O que ainda nao entregamos fica marcado como limite atual, sem inflar narrativa.
v1 publica atual
Leitura e supervisao fiscal
Workspace, perfil, certificado, capabilities, documentos, fila e status do feed fiscal.
Onboarding controlado
Acesso provisionado por cliente API com escopos, allowlist de IP, expiracao e rotacao de secret.
Sem overpromise de emissao
Esta v1 publica nao vende emissao, transmissao ou cancelamento fiscal externo como capability pronta.
Escritorio contabil
Leitura estruturada do contexto fiscal da empresa cliente, certificado, capabilities e fila de pendencias sem depender de navegacao manual no painel.
ERP parceiro
Consome status, perfil fiscal e documentos para sincronizacao, conciliacao de contexto e operacao assistida sem prometer emissao externa completa.
Automacao supervisionada por IA
Usa a API para inspecao, triagem e rotina supervisionada. A camada publica nao vende automacao fiscal cega.
Autenticacao e governanca
Camada externa com API key + HMAC e escopo por empresa.
A credencial atual e provisionada por empresa. Isso simplifica governanca, reduz ambiguidade de tenant e evita vender uma API publica irrestrita antes da hora.
Assinatura
METHOD + "\n" + originalUrl + "\n" + timestamp + "\n" + nonce + "\n" + rawBody
Cliente API provisionado por empresa, com escopos, status, expiracao opcional e allowlist de IP.
Assinatura HMAC SHA-256 em cada requisicao com API key, timestamp, nonce e raw body.
Janela de timestamp curta e protecao contra replay de nonce.
Rate limit por cliente provisionado, com configuracao operacional no cadastro do cliente API.
Scopes fiscais
O contrato publico atual e orientado a leitura, status e supervisao.
Scope
fiscal:readWorkspace fiscal consolidado
Le contexto agregado da empresa autenticada em um unico payload.
Scope
fiscal:profile:readPerfil fiscal
Le regime, inscricoes e dados-base necessarios para operacao fiscal.
Scope
fiscal:certificate:readStatus do certificado
Le configuracao, validade e risco de expiracao do certificado.
Scope
fiscal:capabilities:readCapabilities por tipo
Le suporte atual por documento e exigencias minimas da superficie fiscal.
Scope
fiscal:documents:readDocumentos fiscais
Le documentos paginados com filtros basicos por tipo, periodo e direcao.
Scope
fiscal:queue:readFila de pendencias
Le fila fiscal operacional para casos em contingencia.
Scope
fiscal:webhooks:readStatus do feed fiscal
Le status do feed e estado atual de entrega, sem configurar webhooks de parceiro.
Endpoints v1
Superficie fiscal publica atual, sem prometer write path que ainda nao esta aberta.
/api/external/fiscal/workspaceRetorna a visao consolidada da empresa autenticada.
Bom para escritorio ou integrador que quer um snapshot inicial.
Scope
fiscal:readStatus
Disponivel
/api/external/fiscal/companiesLista o contexto fiscal da empresa dona da credencial.
Hoje o escopo e company-scoped. Nao e carteira multiempresa nativa.
Scope
fiscal:readStatus
Disponivel
/api/external/fiscal/profilePerfil fiscal e dados-base da empresa.
Foco em leitura e integracao de contexto.
Scope
fiscal:profile:readStatus
Disponivel
/api/external/fiscal/certificate/statusStatus atual do certificado da empresa.
Leitura apenas. Upload/configuracao seguem fora da API publica.
Scope
fiscal:certificate:readStatus
Disponivel
/api/external/fiscal/capabilitiesSuporte fiscal e exigencias minimas por documento.
Importante para ERP e escritorio decidirem o que automatizar.
Scope
fiscal:capabilities:readStatus
Disponivel
/api/external/fiscal/documentsLista documentos fiscais paginados.
Leitura. Nao documenta emissao/transmissao externa nesta v1.
Scope
fiscal:documents:readStatus
Disponivel
/api/external/fiscal/pendingFila de pendencias e contingencia.
Boa para supervisao operacional.
Scope
fiscal:queue:readStatus
Disponivel
/api/external/fiscal/webhooks/statusEstado atual do feed fiscal.
Hoje expomos status. Nao ha onboarding publico de webhook outbound do parceiro.
Scope
fiscal:webhooks:readStatus
Disponivel com restricao
Casos de uso que fazem sentido
- Escritorio contabil que quer enxergar certificado, profile, capabilities e pendencias de cada cliente sem depender do painel.
- ERP parceiro que precisa consumir documentos e status fiscal para compor rotinas e dashboards proprios.
- Operacao supervisionada por IA que analisa contexto fiscal, identifica pendencias e aciona humano antes de qualquer passo sensivel.
Camada base de integracao
Vendors
Existe camada externa para vendors com create e read.
Catalogo
Existe camada externa para produtos e servicos com create e update.
Sales
Existe create de pedidos de venda para integracao operacional.
Limites atuais
A parte mais importante desta pagina: o que ainda nao deve ser vendido.
Nao documentamos emissao, transmissao, cancelamento, CC-e, manifestacao ou inutilizacao como parte da API fiscal publica v1.
Nao existe onboarding publico self-serve; o acesso continua controlado e provisionado pelo time.
Nao existe modo escritorio multi-carteira nativo nesta superficie publica. A credencial atual e dona de uma empresa por vez.
Nao existe endpoint publico para upload de certificado, upload de XML/PDF ou configuracao fiscal por parceiro externo.
Nao existe pacote publico de webhooks fiscais outbound para parceiros; hoje a superficie exposta e de status.
Onboarding
A API fiscal publica ja e vendavel, mas o acesso continua assistido e controlado.
Se o seu caso de uso envolve escritorio contabil, ERP parceiro ou operacao supervisionada por IA, o proximo passo e alinhar escopos, empresa dona da credencial, limite operacional e o que fica dentro da v1 publica. A Finnextho prefere uma narrativa precisa a uma documentacao que promete mais do que entrega.