# 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 (13): debit_list_indices, debit_list_judicial_tables, debit_get_index_series,
  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_delete_calculation, 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 econômicos (slug, cobertura).
- GET  /v1/indices/{slug}               — detalhe de um índice.
- GET  /v1/indices/{slug}/series        — série mês a mês (from/to, format=csv, sampling=daily).
- GET  /v1/tables                       — lista de TABELAS judiciais (CJF, TJ/SP…). O `id` daqui
                                         é o que vai em `indexador` de um calculosJudiciais.
- GET  /v1/tables/{id}                  — detalhe de uma tabela.
- GET  /v1/tables/{id}/series           — coeficientes mês a mês (from/to, format=csv, asOf).
- 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. Os campos vao DENTRO de `fields`:
                                         {"fields":{"dia_atualiza":"25/08/2026"}}. Campo na raiz
                                         do corpo = 400 NO_FIELDS (nada e gravado em silencio).
- DELETE /v1/calc/{type}/{id}           — manda o calculo para a lixeira (soft-delete, igual ao site).
- 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|docx|excel  — demonstrativo. HTML nos 8 tipos; PDF em
  atualizacaoMonetaria, calculosJudiciais, pensaoAlimenticia, tabelasJudiciais e cartaoPonto; DOCX em
  atualizacaoMonetaria e calculosJudiciais; Excel so em pensaoAlimenticia. Nao decore: GET /v1/describe/{type} traz
  `exportFormats` daquele tipo. Formato indisponivel → 400 EXPORT_UNAVAILABLE com a lista.
  O DOCX e OOXML de verdade (o Word abre sem aviso, tabela continua tabela) e traz o MESMO laudo do
  HTML e do PDF — mesma redacao, mesmos numeros, mesma ordem.
  Pelo MCP, debit_export_calculation devolve o HTML inline e o ARQUIVO de pdf/docx/excel — bloco
  `resource` com o conteudo em base64, pronto para salvar. Nao e link: os bytes chegam no mesmo turno.
- POST /v1/extract                       — extração por IA (multipart "file" ou fileBase64; docType: cnis|sentenca|cartaoPonto|trabalhista).
  Retenção: o arquivo e os dados extraídos são apagados do servidor 48h depois do upload. A resposta é a única cópia — guarde-a ou aplique-a a um cálculo na mesma sessão.
  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).
- INDICE e TABELA sao coisas diferentes e vivem em rotas diferentes: indice (uma serie: IPCA-E,
  INPC, Selic) em /v1/indices; TABELA judicial (qual indice corrige CADA MES, mais os juros) em
  /v1/tables. Ate 26/08/2026 as duas vinham juntas em /v1/indices, e a tabela aparecia com o id
  deslocado em +1000 — quem copiava aquele id para `indexador` recebia o valor NOMINAL com HTTP 200.
  Hoje o id publicado em /v1/tables e o calcId real, o MESMO das tabelas que voce cria; o id antigo
  e recusado com 400 INDEX_LEGACY_ID dizendo o numero certo.
- 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 422 ENGINE_NO_RESULT.
- atualizacaoMonetaria de geracao anterior (tipo ATUA/A2 no banco): so existe como PDF arquivado;
  run/PATCH/get dao 409 LEGACY_CALC_READ_ONLY, e export?format=pdf devolve o demonstrativo.

## Serie (GET /v1/indices/{slug}/series e GET /v1/tables/{id}/series)
- Leia o campo `basis` antes de usar os numeros: ele diz QUAL campo corrige. Em indice `perc`
  quem corrige e o accumulated, nao o value (value e a variacao do mes). O accumulatedPositive
  vem junto, mas e a VARIANTE que expurga mes negativo -- nao e o padrao da debit e nao bate com
  POST /v1/correct. Na SELIC o fator e a SOMA de value no periodo (ela e aditiva); a coluna
  accumulated da SELIC e nula em 359 das 481 linhas e vem como null.
- value:null + published:false = mes ainda nao publicado (nao e deflacao). A linha fica na serie
  porque o accumulated dela e valido.
- sampling: dolar, euro, ufesp e ufir tem serie DIARIA. O padrao devolve so o dia 1o, que e o que
  o calculo usa; sampling=daily devolve a serie real.
- Tabela judicial (kind=judicial_table, id>=1000) NAO tem serie guardada: o coeficiente e calculado.
  asOf RECALCULA, nao recorta. E factor e selicAccrued andam juntos: nos meses de SELIC o factor
  vale 1 e a correcao toda esta no selicAccrued, que e ADITIVO
  (corrigido = valor * factor * (1 + selicAccrued/100)). Usar so o factor erra o calculo.
- A serie nao traz juros. Correcao e juros sao contas separadas; juros em POST /v1/correct.
- Tool MCP debit_get_index_series devolve no maximo 240 meses; serie inteira e CSV so no REST.

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

## Janela do plano gratuito (retroativo de 2 anos)
- O `run` roda na CONTA do usuario, com o plano que ela tem. Conta sem assinatura ativa calcula os
  ultimos 2 anos; lancamento com data anterior entra no total pelo VALOR NOMINAL — sem correcao,
  juros, multa nem SELIC. Vale em atualizacaoMonetaria e calculosJudiciais.
- Em calculosJudiciais o resultado ganha `bloqueio_assinatura` {aplicado, anos, dia_minimo,
  dia_minimo_int, mensagem, linhas[]} e cada linha atingida traz `bloqueada_assinatura: true` +
  `mensagem_bloqueio`. As duas chaves SO existem quando algo foi bloqueado — assinante nao as ve.
- No demonstrativo a data sai com asterisco, o texto dos criterios explica, e o anexo mes a mes
  (`anexarTabela`) comeca na data da janela.
- PAGAMENTO NUNCA E BLOQUEADO: valor negativo e deducao, e derruba-lo para o nominal aumentaria o
  debito contra o devedor. Parcela pode ficar sem correcao; deducao, nao.
- A API antiga /api/v2/calculosJudiciais e cobrada pela apikey e NAO aplica esta janela.

## 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 do INDICE) OU tabelaJudicial(id de /v1/tables),
  dia_atualiza(DD/MM/AAAA), lista[{dia,valor,desc?,custas?}].
  ATENCAO: aqui indice e tabela sao campos DIFERENTES, e mandar os dois e 400. `indexador` e um
  indice economico; para corrigir por tabela do CJF/tribunal use `tabelaJudicial`. E o unico tipo
  com essa separacao — em calculosJudiciais a tabela vai no proprio `indexador`.
  opc: calc_jurosm, juros_moratorios.percentual, juros_moratorios.a_partir(vencimento|citacao),
  juros_moratorios.data_citacao, juros_moratorios.modo(s=ao mes|a=ao ano),
  juros_moratorios.tipo_calculo(s=simples|c=capitalizados), juros_moratorios.pro_rata,
  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,
  opcoes_selic.fim, opcoes_selic.base(a|am|aj|ajm), opcoes_selic.versao(1|2), calc_multa_774, multa_774.*,
  imputacao.ativa, imputacao.art354, imputacao.ordem(vencimento|onerosidade), imputacao.permitir_vincendas,
  calc_custas, modo_indexador(um|multi|personal), multiIndexador{nome,id,indices[{id,inicio,fim}]}.
  HONORARIOS DO ART. 523: o campo e `multa523.honorarios523_a_parte` (bool) — NAO existe
  `calc_honorarios_ncpc`. Com ele ligado o valor sai destacado em `valor_honorarios_ncpc`, e
  `multa523.custas` inclui as custas na base. A chave `honorarios523_a_parte` na raiz e o gemeo
  historico: calculo novo usa a de dentro de multa523.
- MULTA DO ART. 774, paragrafo unico, CPC (ato atentatorio a dignidade da justica): ate 20% do valor
  atualizado do debito em execucao, revertida ao exequente. NAO e automatica — o percentual e fixado
  pelo juiz. Existe nos dois tipos: `calc_multa_774`/`multa_774` na atualizacaoMonetaria e
  `calcularMulta774`/`multa774` em calculosJudiciais. modo=p (percentual, padrao) ou v (valor em R$
  arbitrado, entra pelo nominal). A base tem os 8 componentes TODOS marcados por padrao — igual a
  base do art. 523 —, mais base_multa523/base_honorarios523 desmarcados (sancao sobre sancao exige
  escolha explicita) e, so na atualizacaoMonetaria, base_deducoes (padrao true: abate pagamentos).
  Objeto PARCIAL e aceito; chave ausente vem do padrao. Acima de 20% calcula e o laudo ressalva.
- IMPUTACAO DE PAGAMENTOS (arts. 352 a 355 do CC): valor NEGATIVO na lista (`lista` na
  atualizacaoMonetaria, `valorList` em calculosJudiciais) e PAGAMENTO. Sem opcao nenhuma ele abate
  principal e juros ao mesmo tempo — comportamento historico e ainda o padrao. Com
  `imputacao.ativa=true` o pagamento quita PRIMEIRO os juros vencidos e so o excedente reduz o
  capital (art. 354), na ordem do art. 355; o saldo remanescente passa a render juros sobre o capital
  reduzido, entao o total fica ACIMA do abatimento direto. Campos iguais nos dois tipos:
  imputacao.ativa (false), imputacao.art354 (true), imputacao.ordem (vencimento|onerosidade),
  imputacao.permitir_vincendas (false — imputar em vincenda e COMPENSACAO, nao imputacao).
  Na atualizacaoMonetaria a METODOLOGIA vem do campo que ja existia, `calc_abater_valores`:
  false = os juros param de correr sobre a parte quitada na data do pagamento; true = apura todos os
  juros ate a data de atualizacao e so entao imputa. NAO ha chave nova para isso.
  O excedente sem parcela vencida NAO abate nada: sai em imputacao_credito_nao_imputado
  (atualizacaoMonetaria) / imputacao.credito_nao_imputado (calculosJudiciais).
  Em trecho de SELIC nao ha juros destacados e o art. 354 fica sem objeto: o pagamento abate o saldo
  unico, e o laudo declara isso.
- SELIC entra por DOIS caminhos e eles NUNCA somam: calc_selic (EC 113, a partir de selic_inicio) ou
  os blocos de SELIC da tabela judicial escolhida (automatico, ex.: tabelas CJF com SELIC 12/2021-08/2025).
  calc_selic=true por cima de tabela com SELIC SUBSTITUI a da tabela.
  opcoes_selic.fim fecha o periodo da SELIC da EC 113 (so vale com calc_selic=true): depois dele o
  indice volta a corrigir e os juros voltam a correr. NAO recorta a SELIC de tabela judicial.
  opcoes_selic.base = base de incidencia; omitido em calculo existente vale ajm (historico), novo nasce am.
  opcoes_selic.versao decide como as DATAS da SELIC sao lidas: 1 (ou ausente) conta por MES e o dia de
  selic_inicio/opcoes_selic.fim e IGNORADO — comportamento de todo calculo salvo; 2 conta por DIA e o mes
  em que a SELIC entra vale so os dias que lhe cabem, junto com o pro-rata da correcao
  (calc_perc_prorata, ou calc_tj_prorata em tabela judicial). Nao existe serie diaria de SELIC: a do
  Bacen e mensal, entao o pro-rata e LINEAR sobre a taxa do mes. So a ponta inicial e prorateada,
  igual ao calculosJudiciais — pedir a mesma coisa nos dois produtos tem de dar o mesmo numero.
  Calculo novo nasce com versao 2; chamada por API e sempre nova, entao informe 2 para contar o dia.
- calculosJudiciais — obrig: indexador, dataAtual, valorList[{dia,valor,desc?}].
  ATENCAO: `indexador` e o id de uma TABELA JUDICIAL — o `id` de GET /v1/tables, ou o calcId de um
  calculo tipo tabelasJudiciais seu. NAO use id de indice (ipca_e, inpc, selic) nem o id antigo do
  catalogo (calcId+1000): os dois sao recusados com 400, porque sem tabela o calculo sairia com o
  valor NOMINAL. -1 = serie inline em tabelaPersonalizada.
  opc: sucumList, jurosFaixas[{inicio,fim,tipo:s|c|taxalegal|poupanca_204_simples|tr,percentual}],
  jurosCompFaixas(idem), jurosProRata(bool, padrao TRUE), jurosProprios(bool, padrao FALSE),
  jurosTab(LEGADO), jurosDataInicio(DD/MM/AAAA), jurosDetalhado(bool), calc_selic, selic_inicio,
  modoSelic(princ|princJuros), calcularHonoSucum,
  honoSucumModo(causa|condenacao|certo|valorExecucao|baseUsuario|apenasSucumbecia), honoSucumPercentual,
  calcularMulta + multa{percentual,tipo_calculo(p|d),multa_sobre_juros,multa_sobre_valor_original,
  multa_valor_vincendo} (o objeto inteiro tambem e aceito, e SUBSTITUI o anterior),
  anexarTabela(bool, padrao TRUE — false devolve so os totais, sem a tabela mes a mes).
  correcaoProRata=true corrige PRO-RATA DIE pela data da parcela (15/03 rende so os dias dela em
  marco). Padrao false: contar a correcao por dia e escolha de metodologia, nao refinamento — o
  Manual da JF trabalha em meses inteiros. No atualiza a chave e `calc_tj_prorata`. INDEPENDENTE
  do jurosDetalhado.
  jurosFaixas e o formato PREFERIDO dos juros: faixas com data completa. inicio vazio na 1a faixa =
  desde a data de cada parcela; fim vazio na ULTIMA = ate a data do calculo (grave em branco, nao a
  data literal, senao os juros congelam quando dataAtual mudar). A faixa seguinte comeca no dia
  SEGUINTE ao fim da anterior - data igual e recusada, porque faixas sobrepostas sao SOMADAS.
  percentual com virgula e recusado (viraria zero calado). Informar jurosFaixas liga o modo por dia.
  jurosProprios=true faz jurosFaixas VENCER os juros da tabela judicial. Padrao FALSE: as tabelas
  CJF trazem a metodologia de juros delas e, desligado, jurosFaixas fica gravado mas NAO entra na
  conta. O padrao nao pode inverter - todo calculo nasce com faixa {s,0} "sem juros", e a
  precedencia invertida zeraria os juros de todo calculo novo sobre tabela CJF. Ligado, o laudo
  declara a substituicao. Nao alcanca indice especial (210/211) nem SELIC.
  jurosProRata (padrao TRUE) conta os dias quebrados. Com false conta por MES e um periodo de 22 dias
  pode render ZERO - e NAO e o motor mensal antigo, costuma dar MENOS juros que ele. Poupanca ignora.
  jurosDetalhado=true conta os juros por DIA (pro-rata die), igual ao Debit Atualiza: meses inteiros
  + dias restantes/30. Padrao false nesta rota = juros por MES INTEIRO, o dia da parcela e ignorado.
  Com todas as datas no dia 1 os dois modos dao o MESMO numero.

- 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). Para trocar de indice no MEIO do mes o item aceita `corte`:
  {m,i,corte:[{dia,i}]}, com `dia` = 1o dia do indice novo e `i` seguindo como o do 1o segmento
  (ex.: {m:24245,i:45,corte:[{dia:12,i:23}]} = maio/2020 com 11 dias de IPCA-E e 20 de Selic).
  As series sao MENSAIS: o mes partido e pro-rata dos dias sobre a variacao do mes, nao indice
  diario — diga isso no laudo. `fixo` (i:-1) e os indices 210/211 NAO podem comecar no meio do mes.
  opc: juros{faixas:[{inicio,fim,tipo,percentual}]} com
  tipo s|sa|c|taxalegal|tr|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).