Documentação da API

Autenticação

Toda chamada usa uma API key no header Authorization. Chaves tb_test_ operam no ambiente de testes e tb_live_ em produção. O segredo é exibido uma única vez e armazenado apenas como hash SHA-256.

Authorization: Bearer tb_live_xxxxxxxxxxxxxxxx

Idempotência

Envie Idempotency-Key em requisições de escrita. Uma repetição com a mesma chave e o mesmo corpo retorna a resposta original, sem gerar nova operação. Um corpo diferente com a mesma chave retorna 409 Conflict.

POST /api/v1/tax/calculate

POST /api/v1/tax/calculate
Authorization: Bearer tb_test_xxxxxxxx
Idempotency-Key: order-12345
Content-Type: application/json

{
  "company_id": "00000000-0000-0000-0000-000000000000",
  "customer": { "type": "company", "state": "RJ" },
  "product": {
    "sku": "ABC-123",
    "ncm": "00000000",
    "quantity": 2,
    "unit_price": 1250.00
  },
  "operation": {
    "type": "sale",
    "origin_state": "SP",
    "destination_state": "RJ",
    "date": "2027-01-10"
  }
}

Resposta:

{
  "object": "tax.calculation",
  "calculation_id": "5f0f2c1e-8f7a-4b19-9c2e-7a3d5e1f0b44",
  "request_id": "req_01HZX3",
  "environment": "test",
  "execution_mode": "test",
  "status": "partially_determined",
  "coverage_status": "partial",
  "currency": "BRL",
  "operation_date": "2027-01-10",
  "taxes": [
    {
      "tax_type_code": "CBS",
      "status": "determined",
      "base": "2500.00",
      "rate": "0.00900000",
      "amount": "22.50",
      "reason_codes": [],
      "components": [
        {
          "tax_type_code": "CBS",
          "component_code": "FEDERAL",
          "base": "2500.00",
          "rate": "0.00900000",
          "amount": "22.50",
          "status": "determined",
          "legal_basis_available": true
        }
      ]
    },
    {
      "tax_type_code": "IBS",
      "status": "indeterminate",
      "base": "2500.00",
      "rate": null,
      "amount": null,
      "reason_codes": ["jurisdiction_municipality_unknown"],
      "components": [
        {
          "tax_type_code": "IBS",
          "component_code": "MUNICIPAL",
          "base": "2500.00",
          "rate": null,
          "amount": null,
          "status": "indeterminate",
          "legal_basis_available": false
        }
      ]
    }
  ],
  "rules_applied": [
    { "rule_code": "CBS_STD_2026", "rule_version": 3, "tax_type_code": "CBS", "applied": true }
  ],
  "reason_codes": ["jurisdiction_municipality_unknown"],
  "warnings": [],
  "errors": [],
  "trace_available": true,
  "calculated_at": "2027-01-10T12:00:00.000Z",
  "processing_time_ms": 12
}

Todos os valores monetários e alíquotas trafegam como strings decimais (dinheiro com 2 casas, alíquotas com 8) — nunca como número de ponto flutuante. O status pode ser determined, partially_determined, indeterminate ou error. Quando não existe regra ou alíquota vigente, o campo vem como null — o TaxBridge nunca devolve 0 no lugar de indeterminado, e nunca inventa alíquotas.

GET /api/v1/tax/calculations/:id

GET /api/v1/tax/calculations/5f0f2c1e-8f7a-4b19-9c2e-7a3d5e1f0b44
Authorization: Bearer tb_test_xxxxxxxx

Devolve exatamente o mesmo recurso retornado no cálculo original. É um snapshot imutável: mudanças posteriores em regras ou alíquotas não alteram um cálculo já registrado. Cálculos de outra organização retornam 404. Requer o escopo tax:read.

GET /api/v1/tax/calculations/:id/trace

Explicabilidade auditável: quais regras foram avaliadas e aplicadas, jurisdição e vigência por componente, política de arredondamento e base legal. O trace é sanitizado por allowlist — não expõe identificadores internos, contexto normalizado nem dados pessoais.

{
  "object": "tax.calculation.trace",
  "trace_schema_version": "1.0",
  "calculation_id": "5f0f2c1e-8f7a-4b19-9c2e-7a3d5e1f0b44",
  "engine_version": "2.0.0",
  "determination_status": "partially_determined",
  "coverage": { "status": "partial", "reason_codes": ["jurisdiction_municipality_unknown"] },
  "rule_pack": { "code": "BR_CBS_IBS_2026", "version": 1, "status": "ACTIVE" },
  "rate_pack": { "code": "BR_RATES_2026", "version": 2, "status": "ACTIVE" },
  "rounding": { "code": "BR_STD", "precision": 2, "method": "half_up" },
  "rules": [
    {
      "rule_code": "CBS_STD_2026",
      "rule_version": 3,
      "applied": true,
      "effects": [{ "type": "set_tax_rate", "target": "cbs.rate" }]
    }
  ],
  "components": [
    {
      "component_code": "FEDERAL",
      "jurisdiction": { "level": "federal", "code": "BR", "name": "Brasil" },
      "effective_period": { "valid_from": "2026-01-01", "valid_until": null },
      "rate": "0.00900000"
    }
  ],
  "legal_basis": [
    {
      "source_title": "Lei Complementar 214/2025",
      "authority": "Congresso Nacional",
      "reference_type": "article",
      "article": "12",
      "official_url": "https://www.planalto.gov.br/..."
    }
  ]
}

POST /api/v1/tax/validate

POST /api/v1/tax/validate
Authorization: Bearer tb_test_xxxxxxxx
Content-Type: application/json

{
  "company_id": "00000000-0000-0000-0000-000000000000",
  "product": { "sku": "ABC-123", "ncm": "00000000", "quantity": 1, "unit_price": 0 },
  "operation": { "type": "sale", "origin_state": "SP", "destination_state": "RJ", "date": "2027-01-10" }
}

Retorna valid, além de listas de erros, avisos e recomendações com códigos estáveis para tratamento automático no seu sistema. A validação é read-only: não gera cálculo, não consome numeração e não é recuperável via /tax/calculations.

POST /api/v1/economics/analyze

POST /api/v1/economics/analyze
Authorization: Bearer tb_test_xxxxxxxx
Content-Type: application/json

{
  "company_id": "e2f1...",
  "lines": [
    {
      "tax": {
        "product": { "sku": "SKU-1", "quantity": "1", "unit_price": "1000.00" },
        "operation": { "origin_state": "SP", "destination_state": "SP", "date": "2026-01-15" }
      },
      "gross_revenue": "1000.00",
      "current_taxes": { "icms": "180.00", "pis": "16.50", "cofins": "76.00" },
      "buyer": { "counterparty_id": "8a1c..." }
    }
  ]
}

Executa a análise econômica completa (vendedor, comprador e canal) sobre o mesmo motor usado na aplicação. Cada linha carrega em tax o contrato de /tax/calculate sem company_id. A resposta é congelada e recuperável em GET /api/v1/economics/analyses/:id; a memória de cálculo fica em /trace. Escopos: economics:calculate e economics:read.

POST /api/v1/economics/pricing/simulate

Simulação determinística de preços propostos sobre o baseline econômico: margem do vendedor, custo efetivo do comprador, margem de contribuição do canal, distâncias aos preços neutros e faixa de negociação. Não persiste análise. Escopo: economics:pricing.

Códigos de erro