{"openapi":"3.1.0","info":{"title":"Debit API","version":"1.0.0","x-logo":{"url":"https://www.debit.com.br/img/logo.png","altText":"Debit"},"description":"API unificada da **debit** para cálculos jurídicos e financeiros do Brasil (Lei 14.905/2024, manual CNJ 2022, EC 103/2019), com alta precisão e os mesmos motores do site.\n\n## Autenticação\nTODAS as rotas exigem `Authorization: Bearer <credencial>`, exceto `/health` e `/v1/auth/*`. A credencial pode ser:\n\n| Tipo | Formato | Obtido em | Uso |\n|------|---------|-----------|-----|\n| **Chave do site** | UUID (`b62d5a5f-…`) | Painel debit → menu **API** | Jeito mais simples; todos os escopos |\n| **Chave de API** | `dbt_live_…` / `dbt_test_…` | `POST /v1/keys` | Servidor a servidor, agentes; escopos restritos |\n| **JWT** | `eyJ…` (15 min) | `POST /v1/auth/login` | Sessão humana; **obrigatório** para gerenciar chaves |\n| **OAuth 2.1** | Bearer emitido via \"Login com Debit\" | `/authorize` (PKCE + DCR) | Conectores MCP (Claude, ChatGPT) |\n\nSem credencial válida → **401**. Escopo insuficiente → **403**.\n\n## Escopos\n`index:read` · `calc:read` · `calc:write` · `calc:export` · `extract:run` · `account:read`. Uma chave nasce com todos por padrão; restrinja em `POST /v1/keys`. A chave criada no site não tem seletor de escopo — recebe todos.\n\n## Tipos de cálculo\n`atualizacaoMonetaria`, `calculosJudiciais`, `calculoTrabalhista`, `cartaoPonto`, `rmiPrevidenciaria`, `pensaoAlimenticia`, `saldoDevedor`, `tabelasFinanciamento`, `tabelasJudiciais`, `prevDifNRecebidas`, `prevCT`. Use `GET /v1/describe/{type}` para o schema de campos de cada um.\n\n## Cálculos salvos\nCriar/rodar um cálculo grava na **conta real do usuário** — ele aparece no dashboard do site. O fluxo é: `POST /v1/calc` (retorna `calcId` + `hash`) → `PATCH /v1/calc/{type}/{id}` (preenche campos, exige o `hash`) → `POST /v1/calc/{type}/{id}/run` (totais + memória) → `GET …/export` (PDF/HTML/Excel). O atalho `POST /v1/correct` faz tudo isso de uma vez para correção monetária.\n\n## Formato de erro\nTodos os erros seguem `{ \"error\": { \"code\", \"message\", \"hint?\", \"docUrl?\" } }`.\n\n## MCP\nAgentes de IA podem usar o servidor MCP (Streamable HTTP) em `POST /mcp`, com as mesmas credenciais. Discovery OAuth em `/.well-known/oauth-authorization-server`."},"servers":[{"url":"https://mcp.debit.com.br"},{"url":"https://a-api.debit.com.br/debitapi","description":"Produção"},{"url":"http://127.0.0.1:3340","description":"Local"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Sistema","description":"Healthcheck e metadados."},{"name":"Autenticação","description":"Login humano, refresh e logout (JWT)."},{"name":"Chaves de API","description":"Gerência de chaves dbt_live_/dbt_test_ (exige JWT)."},{"name":"Índices","description":"Catálogo de índices econômicos/judiciais."},{"name":"Cálculos","description":"Criar, preencher, rodar, listar e exportar cálculos salvos."},{"name":"Correção","description":"Correção monetária one-shot (atalho)."},{"name":"Extração","description":"Extração de documentos por IA."},{"name":"MCP","description":"Servidor Model Context Protocol."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Chave do site (UUID), chave dbt_live_… ou JWT","description":"Envie `Authorization: Bearer <credencial>`. Aceita a chave criada no site (painel → menu **API**, formato UUID — a mesma da API de atualização monetária, que lá vai no campo `apikey` do corpo), a chave desta API (`dbt_live_…`/`dbt_test_…`) ou um JWT de `/v1/auth/login`. Chave inexistente ou revogada → `401 INVALID_API_KEY`."},"oauth2":{"type":"oauth2","description":"OAuth 2.1 (Authorization Code + PKCE + Dynamic Client Registration) — \"Login com Debit\".","flows":{"authorizationCode":{"authorizationUrl":"https://a-api.debit.com.br/authorize","tokenUrl":"https://a-api.debit.com.br/token","scopes":{"index:read":"Listar índices","calc:read":"Ler cálculos e schemas","calc:write":"Criar e editar cálculos","calc:export":"Exportar PDF/HTML/Excel","extract:run":"Extrair documentos por IA","account:read":"Ler dados da conta"}}}}},"schemas":{"Error":{"type":"object","description":"Envelope de erro padrão.","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"FORBIDDEN_SCOPE"},"message":{"type":"string","example":"Escopo necessário: calc:write"},"hint":{"type":"string"},"docUrl":{"type":"string"}},"required":["code","message"]}}},"Index":{"type":"object","properties":{"slug":{"type":"string","example":"ipca_e"},"id":{"type":"integer","example":45},"name":{"type":"string","example":"IPCA-E"},"type":{"type":"string","enum":["perc","moeda"],"example":"perc","description":"perc = variação percentual; moeda = valores monetários."},"coverageStart":{"type":"string","format":"date","example":"1991-12-01"},"latestAvailable":{"type":"string","format":"date","example":"2026-06-01"},"mergeable":{"type":"boolean","description":"Pode ser mesclado com outro índice em períodos distintos."}}},"Tokens":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"integer","example":15},"nome":{"type":"string","example":"Marcelo"},"email":{"type":"string","example":"user@debit.com.br"}}},"accessToken":{"type":"string","description":"JWT (HS256), válido ~15 min."},"refreshToken":{"type":"string","description":"Token opaco rotativo; guarde com segurança."}}},"ApiKey":{"type":"object","properties":{"id":{"type":"integer","example":7},"name":{"type":"string","nullable":true,"example":"Integração n8n"},"key_prefix":{"type":"string","example":"dbt_live_a1b2"},"scopes":{"type":"array","items":{"type":"string"}},"allowed_tipos":{"type":"array","items":{"type":"string"},"nullable":true},"env":{"type":"string","enum":["live","test"]},"last_used_at":{"type":"string","format":"date-time","nullable":true},"revoked":{"type":"integer","enum":[0,1]},"created_at":{"type":"string","format":"date-time"}}},"CorrectResult":{"type":"object","properties":{"total":{"type":"number","example":14231.55},"correcaoMonetaria":{"type":"number"},"juros":{"type":"number"},"multa":{"type":"number"},"honorarios":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"01/03/2019"},"amount":{"type":"number","example":10000},"corrected":{"type":"number"},"total":{"type":"number"},"memoria":{"type":"string","description":"Memória de cálculo resumida."}}}},"saved":{"type":"boolean"},"calcId":{"type":"integer","description":"Presente quando save=true."},"hash":{"type":"string","description":"Presente quando save=true."}}},"FrontendKey":{"type":"object","properties":{"id":{"type":"integer","example":500},"name":{"type":"string","nullable":true,"example":"Minha api"},"key_prefix":{"type":"string","example":"b62d5a5f","description":"Primeiros 8 caracteres da chave."},"created":{"type":"string","example":"20260714","description":"Data de criação no formato AAAAMMDD (formato legado da tela do site)."},"scopes":{"type":"array","items":{"type":"string"}},"source":{"type":"string","enum":["frontend"],"example":"frontend"}}}}},"paths":{"/health":{"get":{"tags":["Sistema"],"summary":"Healthcheck","security":[],"responses":{"200":{"description":"Serviço no ar","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"integer","example":1},"service":{"type":"string"},"env":{"type":"string"}}}}}}}}},"/v1/auth/login":{"post":{"tags":["Autenticação"],"summary":"Login (e-mail/login + senha) → JWT + refresh token","description":"Autentica contra a conta principal (tabela `login`). Aceita `identifier` (e-mail ou login) e `senha`. Aliases aceitos: `email`/`login` e `password`.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["identifier","senha"],"properties":{"identifier":{"type":"string","description":"e-mail ou login","example":"mrm100"},"senha":{"type":"string","example":"••••••"}}},"example":{"identifier":"mrm100","senha":"minhasenha"}}}},"responses":{"200":{"description":"Tokens emitidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tokens"}}}},"400":{"description":"Faltou identifier/senha","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Credenciais inválidas ou acesso restrito (fase de testes)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/refresh":{"post":{"tags":["Autenticação"],"summary":"Rotaciona o refresh token e emite novo JWT","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["refreshToken"],"properties":{"refreshToken":{"type":"string"}}}}}},"responses":{"200":{"description":"Novos tokens","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tokens"}}}},"401":{"description":"Refresh inválido/expirado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/logout":{"post":{"tags":["Autenticação"],"summary":"Revoga um refresh token","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["refreshToken"],"properties":{"refreshToken":{"type":"string"}}}}}},"responses":{"200":{"description":"Revogado","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true}}}}}}}}},"/v1/keys":{"get":{"tags":["Chaves de API"],"summary":"Lista as chaves de API do usuário","description":"Exige **JWT** (login humano) — uma chave não lista/cria outra chave.\n\n`keys` traz as chaves desta API (`dbt_live_…`); `frontendKeys` traz as chaves criadas no site (painel → menu **API**), que também autenticam aqui mas são criadas e revogadas lá. De ambas só o prefixo é exibido — o valor completo aparece uma única vez, na criação.","responses":{"200":{"description":"Lista de chaves","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}},"frontendKeys":{"type":"array","description":"Chaves criadas no site (painel → menu API). Autenticam em todas as rotas com todos os escopos; gerenciadas no site.","items":{"$ref":"#/components/schemas/FrontendKey"}}}}}}},"401":{"description":"Não autenticado (JWT)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Chaves de API"],"summary":"Cria uma chave de API","description":"Exige **JWT**. A chave completa é retornada **uma única vez** — guarde-a. Sem `scopes`, a chave recebe todos os escopos.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"Integração n8n"},"scopes":{"type":"array","items":{"type":"string"},"example":["index:read","calc:read","calc:write"]},"allowedTipos":{"type":"array","items":{"type":"string"},"description":"Restringe a chave a certos tipos de cálculo.","example":["atualizacaoMonetaria"]},"env":{"type":"string","enum":["live","test"],"default":"live"}}}}}},"responses":{"201":{"description":"Chave criada","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"key":{"type":"string","example":"dbt_live_a1b2c3..."},"key_prefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"env":{"type":"string"},"warning":{"type":"string"}}}}}},"401":{"description":"Não autenticado (JWT)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/keys/{id}":{"delete":{"tags":["Chaves de API"],"summary":"Revoga uma chave","description":"Exige **JWT**.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Revogada","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"404":{"description":"Chave não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/indices":{"get":{"tags":["Índices"],"summary":"Lista os índices econômicos/judiciais disponíveis","description":"Escopo: `index:read`. Resultado em cache curto (10 min).","responses":{"200":{"description":"Lista de índices","content":{"application/json":{"schema":{"type":"object","properties":{"indices":{"type":"array","items":{"$ref":"#/components/schemas/Index"}}}}}}},"401":{"description":"Não autenticado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/indices/{slug}":{"get":{"tags":["Índices"],"summary":"Detalhe de um índice por slug ou id","description":"Escopo: `index:read`.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"example":"ipca_e"}],"responses":{"200":{"description":"Índice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Index"}}}},"404":{"description":"Índice não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/describe/{type}":{"get":{"tags":["Cálculos"],"summary":"Schema de campos de um tipo de cálculo","description":"Escopo: `calc:read`. Retorna os campos aceitos por aquele tipo (curado para `atualizacaoMonetaria`; derivado do motor para os demais), com exemplo.","parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string","enum":["atualizacaoMonetaria","calculosJudiciais","calculoTrabalhista","cartaoPonto","rmiPrevidenciaria","pensaoAlimenticia","saldoDevedor","tabelasFinanciamento","tabelasJudiciais","prevDifNRecebidas","prevCT"]},"example":"atualizacaoMonetaria"}],"responses":{"200":{"description":"Schema do tipo","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"label":{"type":"string"},"source":{"type":"string","enum":["curated","engine"]},"fields":{"type":"array","items":{"type":"object","properties":{"campo":{"type":"string"},"tipo":{"type":"string"},"required":{"type":"boolean"},"descricao":{"type":"string"}}}},"exemplo":{"type":"object"}}}}}},"404":{"description":"Tipo sem schema","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/correct":{"post":{"tags":["Correção"],"summary":"Correção monetária (one-shot; save:true persiste na conta)","description":"Atalho que cria, preenche e roda um cálculo `atualizacaoMonetaria` numa só chamada. Escopo: `calc:read` (ou `calc:write` se `save:true`). Com `save:false` (padrão) o cálculo não fica no dashboard.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["index","updateTo","items"],"properties":{"index":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"slug ou id do índice","example":"ipca_e"},"updateTo":{"type":"string","description":"Data-alvo DD/MM/AAAA","example":"01/06/2026"},"items":{"type":"array","items":{"type":"object","required":["date","amount"],"properties":{"date":{"type":"string","example":"01/03/2019"},"amount":{"type":"number","example":10000},"description":{"type":"string"},"custas":{"type":"boolean"}}}},"juros":{"type":"object","properties":{"percentual":{"type":"string","example":"1"},"from":{"type":"string","enum":["vencimento","citacao"]}}},"multa":{"type":"object","properties":{"percentual":{"type":"string","example":"2"}}},"honorarios":{"type":"object","properties":{"valor":{"type":"number"},"modo":{"type":"string","enum":["p","v"],"description":"p=percentual, v=valor fixo"}}},"selic":{"type":"boolean","description":"Usa SELIC (Lei 14.905/2024) no lugar de juros."},"save":{"type":"boolean","default":false},"name":{"type":"string"}}},"example":{"index":"ipca_e","updateTo":"01/06/2026","items":[{"date":"01/03/2019","amount":10000,"description":"Principal"}],"juros":{"percentual":"1"}}}}},"responses":{"200":{"description":"Resultado da correção","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CorrectResult"}}}},"400":{"description":"Parâmetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Escopo insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/calc":{"post":{"tags":["Cálculos"],"summary":"Cria um cálculo salvo","description":"Escopo: `calc:write`. Retorna `calcId` e `hash` — guarde o `hash`, ele é exigido em `PATCH`/`run`/`export`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","example":"atualizacaoMonetaria"},"name":{"type":"string"}}}}}},"responses":{"201":{"description":"Cálculo criado","content":{"application/json":{"schema":{"type":"object","properties":{"calcId":{"type":"integer"},"type":{"type":"string"},"hash":{"type":"string"}}}}}},"400":{"description":"Tipo inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Cálculos"],"summary":"Lista os cálculos do usuário","description":"Escopo: `calc:read`.","parameters":[{"name":"type","in":"query","schema":{"type":"string"},"description":"Filtra por tipo."},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"offset","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Lista","content":{"application/json":{"schema":{"type":"object","properties":{"calculations":{"type":"array","items":{"type":"object"}}}}}}}}}},"/v1/calc/{type}/{id}":{"get":{"tags":["Cálculos"],"summary":"Abre um cálculo","description":"Escopo: `calc:read`.","parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"hash","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Cálculo","content":{"application/json":{"schema":{"type":"object"}}}}}},"patch":{"tags":["Cálculos"],"summary":"Seta campos (batched)","description":"Escopo: `calc:write`. Exige `hash`. Veja os campos válidos em `GET /v1/describe/{type}`.","parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["hash","fields"],"properties":{"hash":{"type":"string"},"fields":{"type":"object","description":"Mapa campo→valor.","example":{"indexador":45,"dia_atualiza":"01/06/2026"}}}}}}},"responses":{"200":{"description":"Campos atualizados","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"calcId":{"type":"integer"},"updatedFields":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Falta hash","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/calc/{type}/{id}/run":{"post":{"tags":["Cálculos"],"summary":"Roda o cálculo (totais + memória)","description":"Escopo: `calc:read`. Exige `hash` (corpo ou query).","parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"hash":{"type":"string"}}}}}},"responses":{"200":{"description":"Resultado (totais + memória de cálculo)","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Falta hash","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/calc/{type}/{id}/export":{"get":{"tags":["Cálculos"],"summary":"Exporta PDF/HTML/Excel","description":"Escopo: `calc:export`. Retorna o arquivo binário com o `Content-Type` correspondente.","parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"format","in":"query","schema":{"type":"string","enum":["html","pdf","excel"],"default":"html"}},{"name":"hash","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Arquivo","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}},"text/html":{"schema":{"type":"string"}},"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}}}}},"/v1/extract":{"post":{"tags":["Extração"],"summary":"Extração de documento por IA","description":"Escopo: `extract:run`. Envie o arquivo como **multipart** (campo `file` ou `arq`) OU como `fileBase64` no JSON. `docType`: `cnis` | `sentenca` | `cartaoPonto` | `trabalhista`. Limite ~25 MB.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"docType":{"type":"string","enum":["cnis","sentenca","cartaoPonto","trabalhista"]}}}},"application/json":{"schema":{"type":"object","required":["fileBase64","docType"],"properties":{"fileBase64":{"type":"string"},"filename":{"type":"string"},"mimeType":{"type":"string"},"docType":{"type":"string","enum":["cnis","sentenca","cartaoPonto","trabalhista"]}}}}}},"responses":{"200":{"description":"Dados estruturados extraídos","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Sem arquivo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mcp":{"post":{"tags":["MCP"],"summary":"Servidor MCP (Streamable HTTP)","description":"Transporte stateless JSON-RPC 2.0. Auth: `Authorization: Bearer` (chave de API ou token OAuth). As 10 tools espelham os endpoints REST.","requestBody":{"content":{"application/json":{"schema":{"type":"object","description":"Envelope JSON-RPC 2.0."}}}},"responses":{"200":{"description":"Resposta JSON-RPC","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Sem Bearer válido (header WWW-Authenticate aponta a discovery)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}