API operacionalDevelopers / Fiscal API · v1

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.

Solicitar acesso Ver quickstart

HMAC: SHA-256 assinado
8: endpoints fiscais
5 min: janela de assinatura
120/min: rate limit padrao

primeira-requisicao.sh

bash

API_KEY="ak_live_xxxxxxxx"
API_SECRET="sk_live_xxxxxxxx"
METHOD="GET"
ROUTE="/api/external/fiscal/workspace"
TS="$(date +%s)"
NONCE="$(openssl rand -hex 16)"
BODY=""

# payload = METHOD \n originalUrl \n timestamp \n nonce \n rawBody
PAYLOAD="$METHOD\n$ROUTE\n$TS\n$NONCE\n$BODY"
SIG="$(printf '%b' "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_SECRET" | awk '{print $2}')"

curl -sS "https://api.finnextho.com$ROUTE" \
  -H "X-API-Key: $API_KEY" \
  -H "X-API-Timestamp: $TS" \
  -H "X-API-Nonce: $NONCE" \
  -H "X-API-Signature: sha256=$SIG"

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.

Para quem e

Construida para tres perfis de integrador.

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.

Base URL

Um host, um prefixo, tenant por credencial.

Todas as chamadas da API externa partem do mesmo host com o prefixo /api/external. O originalUrl usado na assinatura inclui a query string.

Protocolo

HTTPS apenas

Formato

JSON (UTF-8)

Auth

API key + HMAC

base-url

https://api.finnextho.com/api/external

exemplo-de-rota

GET https://api.finnextho.com/api/external/fiscal/workspace

A credencial e provisionada pelo time e pertence a uma unica empresa. Nao ha host de sandbox publico separado nesta v1: o acesso assistido cobre validacao e testes iniciais.

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.

X-API-Key

X-API-Signature

X-API-Timestamp

X-API-Nonce

assinatura

text

payload = METHOD + "\n" + originalUrl + "\n" + timestamp + "\n" + nonce + "\n" + rawBody
signature = HMAC_SHA256(secret, payload)  // hex

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.

Ficha tecnica da assinatura

Algoritmo: HMAC SHA-256, assinatura em hex
Payload assinado: METHOD + originalUrl + timestamp + nonce + rawBody
Janela de timestamp: 5 minutos — aceita epoch em segundos ou ms
Nonce: Minimo 8 caracteres, uso unico (anti-replay)
Prefixo da assinatura: Aceita com ou sem sha256=
Escopo de tenant: Uma credencial = uma empresa dona

Quickstart

Assine, chame e leia o contexto fiscal em uma requisicao.

Os exemplos abaixo montam o payload assinado exatamente como o servidor espera. Troque a API key e o secret provisionados, escolha sua linguagem e copie.

API_KEY="ak_live_xxxxxxxx"
API_SECRET="sk_live_xxxxxxxx"
METHOD="GET"
ROUTE="/api/external/fiscal/workspace"
TS="$(date +%s)"
NONCE="$(openssl rand -hex 16)"
BODY=""

# payload = METHOD \n originalUrl \n timestamp \n nonce \n rawBody
PAYLOAD="$METHOD\n$ROUTE\n$TS\n$NONCE\n$BODY"
SIG="$(printf '%b' "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_SECRET" | awk '{print $2}')"

curl -sS "https://api.finnextho.com$ROUTE" \
  -H "X-API-Key: $API_KEY" \
  -H "X-API-Timestamp: $TS" \
  -H "X-API-Nonce: $NONCE" \
  -H "X-API-Signature: sha256=$SIG"

Receba a credencial

API key e secret sao provisionados pelo time com escopos e allowlist de IP.

Monte a assinatura

Concatene method, rota, timestamp, nonce e body; gere o HMAC SHA-256.

Chame o endpoint

Envie os 4 headers X-API-*. A resposta vem no envelope padrao com requestId.

Respostas

Envelope previsivel com requestId e traceId em toda chamada.

Sucesso e erro seguem um contrato fixo. O requestId e otraceId sempre voltam para correlacao e suporte.

200 — Sucesso

200.json

json

{
  "success": true,
  "data": {
    "company": { "id": "665f0c...", "name": "Acme Servicos ME" },
    "fiscalProfile": { "regime": "simples_nacional", "uf": "SP" },
    "certificate": { "status": "valid", "expiresAt": "2026-02-10T00:00:00.000Z" }
  },
  "meta": {
    "requestId": "req_9f2c7a1b4e",
    "traceId": "trc_5a1b8c3d2f",
    "clientId": "ak_live_xxxxxxxx",
    "companyId": "665f0c..."
  }
}

4xx — Erro

erro.json

json

{
  "success": false,
  "error": "Assinatura invalida",
  "errorCode": "external_signature_invalid",
  "requestId": "req_9f2c7a1b4e",
  "traceId": "trc_5a1b8c3d2f"
}

Scopes fiscais

O contrato publico atual e orientado a leitura, status e supervisao.

Scope

fiscal:read

Workspace fiscal consolidado

Le contexto agregado da empresa autenticada em um unico payload.

Scope

fiscal:profile:read

Perfil fiscal

Le regime, inscricoes e dados-base necessarios para operacao fiscal.

Scope

fiscal:certificate:read

Status do certificado

Le configuracao, validade e risco de expiracao do certificado.

Scope

fiscal:capabilities:read

Capabilities por tipo

Le suporte atual por documento e exigencias minimas da superficie fiscal.

Scope

fiscal:documents:read

Documentos fiscais

Le documentos paginados com filtros basicos por tipo, periodo e direcao.

Scope

fiscal:queue:read

Fila de pendencias

Le fila fiscal operacional para casos em contingencia.

Scope

fiscal:webhooks:read

Status 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.

GET/api/external/fiscal/workspace

Retorna a visao consolidada da empresa autenticada.

Bom para escritorio ou integrador que quer um snapshot inicial.

Scope

fiscal:read

Status

Disponivel

GET/api/external/fiscal/companies

Lista o contexto fiscal da empresa dona da credencial.

Hoje o escopo e company-scoped. Nao e carteira multiempresa nativa.

Scope

fiscal:read

Status

Disponivel

GET/api/external/fiscal/profile

Perfil fiscal e dados-base da empresa.

Foco em leitura e integracao de contexto.

Scope

fiscal:profile:read

Status

Disponivel

GET/api/external/fiscal/certificate/status

Status atual do certificado da empresa.

Leitura apenas. Upload/configuracao seguem fora da API publica.

Scope

fiscal:certificate:read

Status

Disponivel

GET/api/external/fiscal/capabilities

Suporte fiscal e exigencias minimas por documento.

Importante para ERP e escritorio decidirem o que automatizar.

Scope

fiscal:capabilities:read

Status

Disponivel

GET/api/external/fiscal/documents

Lista documentos fiscais paginados.

Leitura. Nao documenta emissao/transmissao externa nesta v1.

Scope

fiscal:documents:read

Status

Disponivel

GET/api/external/fiscal/pending

Fila de pendencias e contingencia.

Boa para supervisao operacional.

Scope

fiscal:queue:read

Status

Disponivel

GET/api/external/fiscal/webhooks/status

Estado atual do feed fiscal.

Hoje expomos status. Nao ha onboarding publico de webhook outbound do parceiro.

Scope

fiscal:webhooks:read

Status

Disponivel com restricao

Tratamento de erros

Cada falha tem um errorCode estavel para o seu retry e log.

O campo errorCode e maquina-legivel e nao muda de texto. Trate por ele, nunca pela mensagem.

HTTPStatuserrorCode / motivo

401client

external_credentials_missing

Falta um dos headers X-API-* obrigatorios.

401client

external_timestamp_invalid

X-API-Timestamp nao e um numero valido.

401client

external_timestamp_expired

Timestamp fora da janela de 5 minutos.

401client

external_nonce_invalid

Nonce com menos de 8 caracteres.

401client

external_client_invalid

API key inexistente ou cliente inativo.

401client

external_client_expired

Credencial expirada (expiresAt no passado).

403client

external_ip_not_allowed

IP de origem fora da allowlist do cliente.

401client

external_signature_invalid

HMAC nao confere com o payload assinado.

409client

external_replay_detected

Nonce ja utilizado dentro da janela.

429client

external_rate_limit_exceeded

Limite de requisicoes do cliente excedido.

403client

external_scope_forbidden

Credencial sem o scope exigido pelo endpoint.

500server

external_auth_unavailable

Falha interna ao validar a credencial.

Rate limits

Limite por cliente, com headers para o seu backoff.

O teto e contado por credencial dentro de uma janela. O default e 120 requisicoes por 60 segundos e pode ser ajustado no provisionamento. Ao estourar, a API responde 429 comRetry-After.

120

req / janela (default)

60s

janela (default)

Headers de resposta

x-rate-limit-limit

Teto de requisicoes na janela. Default 120, configuravel por cliente.

x-rate-limit-window

Tamanho da janela em segundos. Default 60.

x-rate-limit-remaining

Requisicoes restantes na janela atual.

Retry-After

Segundos ate liberar novas chamadas. Enviado no 429.

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.

Solicitar acesso Programa de parceiros