# Debit API — cálculos jurídicos e financeiros do Brasil

> A debit oferece cálculos de alta precisão (Lei 14.905/2024, manual CNJ 2022, EC 103/2019)
> via API REST e servidor MCP, para agentes de IA. Tudo requer autenticação.

- Base REST: https://mcp.debit.com.br/v1
- Endpoint MCP: https://mcp.debit.com.br/mcp
- Documentação: https://mcp.debit.com.br/v1/docs (referência) · https://mcp.debit.com.br/v1/guia (manual)

## Autenticação
- Crie uma conta na debit.com.br e pegue uma chave. Duas opções, ambas válidas:
  - chave criada no site (painel → menu API), no formato UUID `b62d5a5f-...`;
  - chave desta API, no formato `dbt_live_...` (`POST /v1/keys`, permite restringir escopos).
- Envie em todas as chamadas: `Authorization: Bearer <chave>`
- Sem credencial válida → 403/401. Não há acesso anônimo.

## Indice do host
- GET https://mcp.debit.com.br/ — publico, sem credencial. Com Accept: application/json devolve
  {service, descricao, autenticacao, links{mcp, guia, referencia, openapi, llms, health}}.

## MCP (recomendado para agentes)
- Endpoint: `https://mcp.debit.com.br/mcp` (Streamable HTTP).
- Auth: chave de API (`Authorization: Bearer dbt_live_...` ou a chave UUID criada no site)
  OU **OAuth 2.1 "Login com Debit"**
  (Authorization Code + PKCE + Dynamic Client Registration). Discovery em
  `/.well-known/oauth-authorization-server` e `/.well-known/oauth-protected-resource`.
- Tools (10): 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.
- Cálculos criados ficam SALVOS na conta do usuário e aparecem no site.
- O calcId é a única referência necessária: a credencial identifica a conta e a posse do cálculo
  é conferida antes de qualquer operação (cálculo de outra conta → 403). O `hash` é o token do
  LINK PÚBLICO do cálculo (?id=…&hash=…, abre sem login) — aceito, nunca exigido.

## REST (resumo)
- GET  /v1/indices                      — lista de índices (slug, cobertura).
- GET  /v1/indices/{slug}               — detalhe de um índice.
- GET  /v1/describe/{type}              — schema de campos de um tipo de cálculo.
- POST /v1/correct                      — correção monetária (one-shot ou save:true).
- POST /v1/calc                         — cria cálculo salvo.
- PATCH /v1/calc/{type}/{id}            — preenche campos.
- POST /v1/calc/{type}/{id}/run         — roda e retorna totais + memória.
- GET  /v1/calc                         — lista os cálculos do usuário (mesma lista do dashboard,
  inclusive os criados no site). É por aqui que se retoma um cálculo antigo: pegue o calcId e siga.
  Cada item: {calcId, type, name, createdAt, updatedAt}.
- GET  /v1/calc/{type}/{id}             — abre o cálculo (o corpo traz o campo `hash`, para o link público).
- GET  /v1/calc/{type}/{id}/export?format=html|pdf|excel  — demonstrativo. HTML em todos os 8 tipos;
  PDF e Excel so em pensaoAlimenticia. Formato indisponivel → 400 EXPORT_UNAVAILABLE com a lista.
  Pelo MCP, debit_export_calculation devolve HTML inline; pdf/excel voltam como {download: URL ABSOLUTA},
  que se baixa com a mesma chave em Authorization: Bearer.
- POST /v1/extract                       — extração por IA (multipart "file" ou fileBase64; docType: cnis|sentenca|cartaoPonto|trabalhista).
  Limite: 25 MB por arquivo (multipart evita os ~33% do base64). Acima disso, 413 FILE_TOO_LARGE;
  documento ilegivel/nao suportado, 502 EXTRACT_FAILED com o motivo.
- OpenAPI completo: /v1/openapi.json  · Docs: /v1/docs

## Exemplo (correção por IPCA-E)
POST /v1/correct
{ "index":"ipca_e", "updateTo":"01/06/2026",
  "items":[{"date":"01/03/2019","amount":10000}], "juros":{"percentual":"1"} }

## Indices: slug x id
- Todo indice tem id; a maioria tem slug. GET /v1/indices/{slug|id} resolve os dois.
- Nunca ha dois indices com o mesmo slug: quando dois compartilham a serie, o mais antigo mantem o
  nome historico e o outro ganha o seu — selic (23) e selic_mais1 (31); indice_tj_tabela_uniforme_geral
  (58, TJ/MA) e tjmt (69). Entradas sem slug sao TABELAS judiciais, referenciadas por id.
- Indice do catalogo nao serve a todo tipo: selic_mais1 so vale dentro de uma tabela judicial
  (vl:[{m,i:31}]); em atualizacaoMonetaria o motor responde 502 ENGINE_NO_RESULT.

## Tipos de cálculo
atualizacaoMonetaria, calculosJudiciais, cartaoPonto, pensaoAlimenticia, saldoDevedor,
tabelasFinanciamento, tabelasJudiciais, prevDifNRecebidas.

## Validacao de entrada
- O lote e validado ANTES de gravar: se um campo falha, nada e gravado (400 com o motivo).
- Vale para datas (DD/MM/AAAA ou MM/AAAA, recusando 31/02, mes 13, 29/02 nao bissexto), enums,
  numeros/booleanos, IDs de indice/tabela e TAMBEM para itens de array: o erro aponta lista[1].dia.
- Sem isso o motor aceitaria o lixo e devolveria 200 com total R$ 0,00 — laudo zerado com cara de pronto.

## Campos por tipo (resumo — use GET /v1/describe/{type} para a lista completa, com enums)
> Em `fields` (PATCH /v1/calc/{type}/{id}) use chaves achatadas. Famílias com chave pontilhada
> (a.b → info.a.b): atualizacaoMonetaria e pensaoAlimenticia. Os demais usam o nome do campo no topo.

- atualizacaoMonetaria — obrig: indexador(id), dia_atualiza(DD/MM/AAAA), lista[{dia,valor,desc?,custas?}].
  opc: calc_jurosm, juros_moratorios.percentual, juros_moratorios.a_partir(vencimento|citacao),
  jurosTab[{modo:L|6|12|P, ate}], calc_multa, multa.percentual, multa.tipo_calculo(p|d),
  calc_honorarios, honorarios.modo(p|v), honorarios.valor, calc_selic, selic_inicio, calc_multa_ncpc.
- calculosJudiciais — obrig: indexador, dataAtual, valorList[{dia,valor,desc?}].
  ATENCAO: `indexador` e o id de uma TABELA JUDICIAL (as entradas SEM slug de GET /v1/indices, ou o
  calcId de um calculo tipo tabelasJudiciais). NAO use id de indice com slug (ipca_e, inpc, selic):
  o calculo responde 200 e devolve o valor NOMINAL, sem correcao. -1 = serie inline em tabelaPersonalizada.
  opc: sucumList, jurosTab, calc_selic, selic_inicio, modoSelic(princ|princJuros), calcularHonoSucum,
  honoSucumModo(causa|condenacao|certo|valorExecucao|baseUsuario|apenasSucumbecia), honoSucumPercentual.

- cartaoPonto — jornada[{seg..dom,folga}], jornadas[{jornada,ate10..60}]; horario{mesano,dia,periodo,es,valor}
  — UMA marcação por chamada; mesano e o MES ABSOLUTO (ano*12+mes), inteiro, nao "MM/AAAA": 03/2024 = 24291;
  dia 1-31; periodo 0-5 (par entrada/saida do dia); es: e|s|modo-dia|modo-periodo; valor HH:MM.
  Uma jornada 8h-12h/13h-18h sao QUATRO chamadas. Demais: toleranciaCLT, intrajornada{ativo,modo}, interjornada, bancoHoras,
  regime12x36, sobreaviso, salarioBase{valor,divisor}, adicionalNoturnoProrrogado, dsrSobreHE.
- pensaoAlimenticia — obrig: fixacao.tipo(percentual_sm|valor_fixo|percentual_liquido|percentual_bruto|mista),
  dia_atualiza, lista[{mes_ano,salario_base?}] (só campos de entrada; derivados são do motor).
  opc: fixacao.percentual, fixacao.valor_fixo,
  fixacao.data_inicio_vigencia, parametrosAtualizacao.indice_correcao(id), parametrosAtualizacao.juros.percentual,
  parametrosAtualizacao.juros.a_partir(vencimento|citacao), parametrosAtualizacao.prescricao.modo(bienal|quinquenal),
  parametrosAtualizacao.imputacao.modo(retroativa|prospectiva|competencia) — destino do excedente de um pagamento;
  retroativa quita as parcelas vencidas mais antigas (arts. 352-355 CC) e nunca imputa em vincendas (Súmula 621 STJ),
  parametrosAtualizacao.imputacao.{metodologia(decorrer|final),art354,imputar_em_prescritas,in_natura_compensa},
  processo.*, partes.alimentante/alimentando/representante.{nome,cpf,qualificacao},
  pagamentos[{competencia_id,tipo,valor(positivo),data,descricao}].
- saldoDevedor — obrig: dia, valor, parcelas, juros, juros_periodo(m|a). opc: carencia, correcao_monetaria,
  indexador, modo_saldo, iof(+iof_perc,iof_periodo,iof_juros,iof_saldoDevedor,iof_tac), seguro, seguro_valor,
  tac, tacList[{dia,valor}], amortizacao, amortizacaoList.
- tabelasFinanciamento — obrig: dia, valor, parcelas, juros, juros_periodo(m|a), sistema(PRICE|SAC|SACRE),
  carencia(0=à vista|1=próx mês|N). opc: correcao_monetaria, indexador, recalcular, modo_saldo, iof*, seguro,
  modo_seguro(antes|depois), tac, tacList.
- tabelasJudiciais — NAO atualiza valores: MONTA a tabela de correcao que os calculos consomem.
  obrig: vl[{m,i,especial?}] — um item por MARCO de mudanca de indice; m = mes absoluto (ano*12+mes),
  i = id do indice que corrige dali em diante (o motor propaga ate o proximo marco e devolve a serie
  completa desde out/1964). i:-1 + especial{mostrarPercentualEspecifico,valorEspecifico,modo} crava um
  percentual fixo no mes (expurgos). opc: juros{faixas:[{inicio,fim,tipo,percentual}]} com
  tipo s|sa|c|taxalegal|selics|selica|poupanca|poupanca_nova|poupanca_204 (+ variantes _simples);
  selic_calc + selic_inicio; lei; dataAtualizacao; descricao; origem.
  Para USAR a tabela: crie um calculosJudiciais com indexador = calcId dela.
- prevDifNRecebidas — obrig: especieBeneficio(código ex "42"), dataInicioBeneficio, dataLimite, dataAtual,
  indexador (TABELA judicial, mesma regra de calculosJudiciais), valorList[{dia:MM/AAAA,valorDevido,valorPago}]. opc: genero(m|f), dataAjuizamento, dataCitacao,
  calcularParcelasVincendas, jurosTab[{modo:0|6|12|P,ate}], calcularHonoSucum,
  honoSucumModo(causa|condenacao|condenacaoSentenca|condenacaoAcordao|certo).