Guia da Debit API

Guia prático da Debit API — cálculos jurídicos e financeiros do Brasil (Lei 14.905/2024, manual CNJ 2022, EC 103/2019) via REST e MCP.

• Referência interativa (Redoc): /v1/docs
• OpenAPI (JSON): /v1/openapi.json
• Schema de campos de um tipo: GET /v1/describe/{type}
• Resumo para IAs: /v1/llms.txt

Base URL de produção: https://a-api.debit.com.br/debitapi (ajuste conforme o host/prefixo do seu ambiente). Nos exemplos abaixo use $BASE.

1. Autenticação

Toda rota (exceto /health e /v1/auth/*) exige Authorization: Bearer <credencial>. Há quatro tipos:

Chave criada no site (sem escrever código)

Basta logar em debit.com.br, abrir o menu API e criar uma chave — a mesma que já valia na API de atualização monetária (client-api.debit.com.br/atualiza-v1, onde ela vai no campo apikey do corpo). Aqui ela vale em todas as rotas /v1/* e também no MCP, mas viaja no cabeçalho:

curl -s "$BASE/v1/indices" -H "Authorization: Bearer b62d5a5f-....-............"

A mesma chave nas duas APIs:

Diferenças em relação à chave dbt_live_:

• escopos: a chave do site recebe todos os escopos (a tela não tem seletor);
• gerenciamento: criar/apagar é no site (apagar lá derruba o acesso na hora), não em /v1/keys;
• não gerencia chaves: /v1/keys continua exigindo JWT (403 HUMAN_ONLY);
• guarda: o valor fica em texto puro no banco legado, enquanto a dbt_ guarda só o sha256 — para integrações críticas prefira a dbt_.

Em GET /v1/keys (com JWT) as chaves do site aparecem em frontendKeys, com o prefixo apenas. Chave inexistente, apagada no site ou fora da liberação de acesso → 401 INVALID_API_KEY.

Quem opera o servidor tem três chaves de configuração (.env) para essa via: LEGACY_KEYS_ENABLED (desliga), LEGACY_KEYS_REQUIRE_PLAN (só contas com plano, regra da API v1) e LEGACY_KEYS_SCOPES (restringe os escopos concedidos).

Login (JWT)

curl -X POST "$BASE/v1/auth/login" \
  -H 'Content-Type: application/json' \
  -d '{"identifier":"meu_login","senha":"minha_senha"}'
# → { "user": {...}, "accessToken": "eyJ...", "refreshToken": "..." }

Criar uma chave de API (usando o JWT)

curl -X POST "$BASE/v1/keys" \
  -H "Authorization: Bearer $JWT" -H 'Content-Type: application/json' \
  -d '{"name":"Integração","scopes":["index:read","calc:read","calc:write","calc:export"]}'
# → { "id": 7, "key": "dbt_live_...", "warning": "Guarde a chave agora — não será exibida de novo." }

Escopos

index:read · calc:read · calc:write · calc:export · extract:run · account:read. Sem o escopo necessário → 403. Sem credencial válida → 401.

2. Conceitos

• Cálculo salvo: criar/rodar grava na conta real do usuário — o cálculo aparece no dashboard do site.
• hash: ao criar um cálculo você recebe calcId + hash. O hash é o token de capacidade — é obrigatório em PATCH, run e export.
• Tipos de cálculo: 11 tipos (tabela na seção 5). Cada um tem campos próprios — descubra-os em GET /v1/describe/{type}.
• Índices: correção monetária usa um indexador (ID). Liste em GET /v1/indices.

3. Fluxo de um cálculo salvo

POST /v1/calc                      → cria         → { calcId, hash }
PATCH /v1/calc/{type}/{id}         → preenche     (envia hash + fields)
POST  /v1/calc/{type}/{id}/run     → roda         → totais + memória
GET   /v1/calc/{type}/{id}/export  → PDF/HTML/Excel

Exemplo completo (atualização monetária) — curl

# 1) criar
CREATE=$(curl -s -X POST "$BASE/v1/calc" -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -d '{"type":"atualizacaoMonetaria","name":"Correção IPCA-E"}')
ID=$(echo "$CREATE" | jq -r .calcId); HASH=$(echo "$CREATE" | jq -r .hash)

# 2) preencher (campos do GET /v1/describe/atualizacaoMonetaria)
curl -s -X PATCH "$BASE/v1/calc/atualizacaoMonetaria/$ID" -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -d "{
    \"hash\":\"$HASH\",
    \"fields\":{
      \"indexador\":45,
      \"dia_atualiza\":\"01/06/2026\",
      \"lista\":[{\"dia\":\"01/03/2019\",\"valor\":10000,\"desc\":\"Principal\"}],
      \"calc_jurosm\":true, \"juros_moratorios.percentual\":\"1\"
    }}"

# 3) rodar
curl -s -X POST "$BASE/v1/calc/atualizacaoMonetaria/$ID/run" -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -d "{\"hash\":\"$HASH\"}"

# 4) exportar PDF
curl -s "$BASE/v1/calc/atualizacaoMonetaria/$ID/export?format=pdf&hash=$HASH" \
  -H "Authorization: Bearer $KEY" -o calculo.pdf

O mesmo em JavaScript (fetch)

const h = { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' };
const base = process.env.BASE;

const { calcId, hash } = await (await fetch(`${base}/v1/calc`, {
  method: 'POST', headers: h, body: JSON.stringify({ type: 'atualizacaoMonetaria', name: 'Correção' }),
})).json();

await fetch(`${base}/v1/calc/atualizacaoMonetaria/${calcId}`, {
  method: 'PATCH', headers: h, body: JSON.stringify({
    hash,
    fields: {
      indexador: 45, dia_atualiza: '01/06/2026',
      lista: [{ dia: '01/03/2019', valor: 10000 }],
      calc_jurosm: true, 'juros_moratorios.percentual': '1',
    },
  }),
});

const resultado = await (await fetch(`${base}/v1/calc/atualizacaoMonetaria/${calcId}/run`, {
  method: 'POST', headers: h, body: JSON.stringify({ hash }),
})).json();

Atalho: correção monetária em uma chamada

Para atualizacaoMonetaria, o POST /v1/correct faz criar→preencher→rodar de uma vez:

curl -s -X POST "$BASE/v1/correct" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{
  "index":"ipca_e", "updateTo":"01/06/2026",
  "items":[{"date":"01/03/2019","amount":10000,"description":"Principal"}],
  "juros":{"percentual":"1","from":"citacao"}, "save":false
}'

4. Nomes de campo (importante)

Os campos enviados em fields (PATCH) usam chaves achatadas — as mesmas que o GET /v1/describe/{type} lista. Regras por família de tipo:

• atualizacaoMonetaria / pensaoAlimenticia / rmiPrevidenciaria: chaves pontilhadas como juros_moratorios.percentual ou segurado.sexo (sem o prefixo info.). Arrays especiais: lista, sc, dependentes, pagamentos.
• calculoTrabalhista: configuração CLT vai como variaveis.<campo> (ex.: variaveis.dataad).
• cartaoPonto: horario recebe um objeto estruturado por marcação; demais campos no topo.
• calculosJudiciais / tabelasJudiciais / saldoDevedor / tabelasFinanciamento / prevCT / prevDifNRecebidas: chave = o próprio nome do campo (topo).

Sempre confira a lista oficial em GET /v1/describe/{type} — ela traz campo, tipo, required, descricao e valores (enums).

5. Tipos de cálculo

Os campos completos (todos, com enums e descrições) de cada tipo estão em GET /v1/describe/{type}. Esta tabela mostra só os mínimos para um cálculo válido.

Destaques de valores

• rmiPrevidenciaria → beneficio (slug): aposentadoria_idade_urbana, aposentadoria_tempo_contribuicao, aposentadoria_especial, aposentadoria_professor, aposentadoria_pcd, aposentadoria_empregado_rural, aposentadoria_hibrida, incapacidade_permanente, pensao_morte, auxilio_reclusao, auxilio_doenca, auxilio_acidente, salario_maternidade, rural_idade, bpc_loas, auxilio_inclusao, salario_familia, seguro_defeso.
• pensaoAlimenticia → fixacao.tipo: percentual_sm, valor_fixo, percentual_liquido, percentual_bruto, mista.
• tabelasFinanciamento → sistema: PRICE, SAC, SACRE.
• juros_periodo / iof_periodo: m (ao mês) ou a (ao ano).
• jurosTab[].modo (judicial): L=taxa legal, 6=0,5% a.m., 12=1% a.m., P=poupança.

6. Extração de documentos (IA)

POST /v1/extract (escopo extract:run) lê CNIS, sentença, cartão de ponto ou doc trabalhista:

curl -s -X POST "$BASE/v1/extract" -H "Authorization: Bearer $KEY" \
  -F 'docType=cnis' -F '[email protected]'
# ou JSON: { "docType":"cnis", "fileBase64":"...", "filename":"cnis.pdf" }

docType: cnis | sentenca | cartaoPonto | trabalhista. O resultado pode alimentar sc (rmi), valorList, etc.

7. MCP (agentes de IA)

Endpoint POST /mcp (Streamable HTTP, JSON-RPC 2.0), mesma autenticação. As tools espelham o REST: debit_list_indices, debit_describe_calculation_type, debit_correct_value, debit_create_calculation, debit_set_calculation_fields, debit_run_calculation, debit_get_calculation, debit_list_my_calculations, debit_export_calculation, debit_extract_document.

Conectores remotos (Claude/ChatGPT) descobrem o OAuth via /.well-known/oauth-authorization-server e abrem o "Login com Debit".

8. Erros

Formato padrão:

{ "error": { "code": "FORBIDDEN_SCOPE", "message": "Escopo necessário: calc:write", "hint": "…", "docUrl": "…" } }

Principais: BAD_REQUEST (400), INVALID_CREDENTIALS/NOT_ALLOWED (401), FORBIDDEN_SCOPE (403), INVALID_TYPE/HASH_REQUIRED/INDEX_NOT_FOUND/TYPE_NOT_DESCRIBED (400/404), KEY_NOT_FOUND (404).