Developers

Assine, chame e leia o contexto fiscal em uma requisição.

Os exemplos montam o payload assinado exatamente como o servidor espera. Troque a key e o secret provisionados, escolha a 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)"

# payload = METHOD \n originalUrl \n timestamp \n nonce \n rawBody
PAYLOAD="$METHOD\n$ROUTE\n$TS\n$NONCE\n"
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"

API key + HMAC SHA-256, com escopo por empresa.

Cada requisição é assinada e validada contra uma janela curta de timestamp, com proteção a replay por nonce. A credencial pertence a uma única empresa — governança simples, sem ambiguidade de tenant.

payload = METHOD + "\n"
        + originalUrl + "\n"
        + timestamp + "\n"
        + nonce + "\n"
        + rawBody

signature = HMAC_SHA256(secret, payload)  // hex

Envelope previsível, com requestId em toda chamada.

Sucesso e erro seguem um contrato fixo. O requestId e o traceId sempre voltam para correlação e suporte — o seu log de produção fica limpo desde o primeiro dia.

{
  "success": true,
  "data": {
    "company": { "id": "665f0c...", "name": "Acme Serviços 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..."
  }
}

Oito rotas de leitura. Nenhum write path que ainda não esteja aberto.

Um contrato público orientado a leitura, status e supervisão.

Um errorCode estável para cada falha, com headers de backoff.

O errorCode é máquina-legível e não muda de texto. Trate por ele, nunca pela mensagem. Ao estourar o limite, a API responde 429 com Retry-After.

{
  "success": false,
  "error": "Assinatura inválida",
  "errorCode": "external_signature_invalid",
  "requestId": "req_9f2c7a1b4e",
  "traceId": "trc_5a1b8c3d2f"
}

A parte mais importante: o que ainda não deve ser vendido como pronto.

Preferimos uma narrativa precisa a uma documentação que promete mais do que entrega.