> ## Documentation Index > Fetch the complete documentation index at: https://docs.jusfy.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Calcula o plano de pagamento no superendividamento > Monta um plano de pagamento das dívidas do devedor conforme a Lei do Superendividamento, respeitando o mínimo existencial. Informe as dívidas (`debts`), o prazo e a carência do plano, o sistema de amortização (`price` ou `sac`), a taxa de juros e o mínimo existencial (`minimum_living_income`). A resposta traz o resumo do plano (`summary`), o rateio das parcelas por credor (`installments_by_creditor`) e o cronograma consolidado (`amortization_schedule`). ## OpenAPI ````yaml /openapi/v1.json post /api/v1/calculadoras/superendividamento openapi: 3.0.0 info: title: Calculadoras Jusfy API description: >- API pública das calculadoras jurídicas Jusfy. Envie um payload de cálculo e receba o resultado já processado pelo motor de cálculo da Jusfy. ## Autenticação Todas as rotas exigem uma **API key** enviada no header `x-api-key`: ```http x-api-key: sua_api_key ``` Sem a key, ou com uma key inativa/inválida, a requisição é recusada com `401`/`403`. As keys são provisionadas pela equipe Jusfy. Cada key tem uma lista de **escopos**, um por produto (cada calculadora, cada consulta, o JusScore), e só acessa as rotas dos produtos liberados para ela. Chamar um produto fora da lista responde `403` com `code: insufficient_scope` e o escopo que faltou na `message` (ex.: `Missing scope: consultas.cnh:execute`). Os produtos são liberados pela equipe Jusfy; produto novo não é liberado automaticamente para quem já integra. A consulta do próprio consumo (`GET /api/v1/consumo`) não exige escopo: qualquer key de cliente ativo a acessa. ## Formato das respostas Nas **calculadoras**, o sucesso devolve o **resultado do cálculo** diretamente no corpo, sem envelope. Nas **consultas**, no JusScore e no consumo, o sucesso vem num envelope padronizado, com os dados em `result`: ```json { "statusCode": 200, "message": "Consulta concluída com sucesso", "timestamp": "2026-07-28T18:00:00.000Z", "path": "/api/v1/consultas/cnh", "result": {} } ``` Toda chamada é registrada para fins de auditoria. ## Consultas assíncronas Duas consultas — o **rastreamento veicular** e o **buscador** **processual** — não respondem na mesma requisição: o fornecedor delas é assíncrono e pode levar minutos. As duas usam um contrato de protocolo: 1. o `POST` devolve **`202`** com um `id` e, se você informar um `url_retorno`, um `signingSecret` (exibido **uma única vez**); 2. o resultado chega por **webhook** assinado e/ou pelo `GET` do protocolo, que responde `200` em todos os estados — inclusive quando a consulta falha, com o desfecho no campo `status`. A consulta é **cobrada no disparo**, não na entrega. Consultar o protocolo é gratuito. O resultado fica disponível por 30 dias. No **buscador processual** o resultado pode chegar a megabytes, então o webhook e o `GET` do protocolo levam apenas o **resumo**; os processos vêm por `GET /api/v1/consultas/buscador-processual/{id}/processos`, paginado. Guardamos no máximo 1.000 por consulta, e quando `truncated` é `true` eles são uma **amostra arbitrária** — a ordem do fornecedor não é cronológica. O contrato completo, com a verificação da assinatura do webhook, está no `README.md` do projeto. ## Erros Todo erro tem o mesmo formato, com um `code` estável que o seu código pode tratar. A `message` é o texto para gente: pode mudar de redação sem aviso, então não decida por ela. ```json { "statusCode": 404, "message": "CNH não encontrada para o documento informado.", "code": "no_data_found", "requestId": "9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65", "timestamp": "2026-06-22T18:00:00.000Z", "path": "/api/v1/consultas/cnh" } ``` `requestId` identifica a chamada nos nossos registros. Toda resposta, de sucesso ou de erro, também o traz no header `X-Request-Id`. Se você enviar um `X-Request-Id` próprio (até 128 caracteres: letras, dígitos e `.`, `_`, `:`, `-`), ele é reaproveitado; senão geramos um. **Informe o `requestId` ao falar com o suporte** sobre uma chamada específica. Nos erros de validação desta API (`400` de corpo ou parâmetro), `message` é a **lista** de problemas (campo + motivo); nos demais, uma string. | Status | `code` | Quando | O que fazer | | ------ | ------ | ------ | ----------- | | `400` | `invalid_request` | Corpo, parâmetro ou JSON inválido. | Corrigir a requisição; a `message` diz o campo. | | `401` | `invalid_api_key` | API key ausente ou que não pertence a nenhum cliente. | Conferir o header `x-api-key`. | | `403` | `inactive_client` | A key é de um cliente que não está ativo (inativo ou ainda pendente). | Falar com a equipe Jusfy. | | `403` | `insufficient_scope` | A key não tem o escopo do produto chamado; a `message` traz o escopo. | Pedir a liberação do produto à equipe Jusfy. | | `404` | `route_not_found` | A rota não existe. | Conferir método e path. | | `404` | `resource_not_found` | O protocolo ou id pedido não existe, ou é de outro cliente (os dois respondem igual). | Conferir o id. | | `404` | `no_data_found` | A consulta rodou e o documento não tem dado. **É cobrada.** | Tratar como resultado vazio; repetir não muda o resultado. | | `409` | `report_not_ready` | O PDF do relatório pedido ainda está em geração, ou a geração falhou. | Consultar o relatório e baixar quando estiver `done`; em `error`, pedir de novo. | | `413` | `payload_too_large` | Corpo da requisição acima do limite. | Reduzir o corpo. | | `422` | `payload_rejected` | O motor de cálculo ou o fornecedor recusou o payload; a `message` diz o motivo. | Corrigir o payload. | | `429` | `rate_limit_exceeded` | Limite de requisições por minuto do produto excedido (ver abaixo). | Esperar o `Retry-After`. | | `429` | `too_many_pending_queries` | Consultas assíncronas demais em processamento para o cliente. | Esperar o `Retry-After`: é uma estimativa, porque a vaga abre quando uma consulta em voo termina. | | `500` | `internal_error` | Erro inesperado nesta API. | Repetir depois; se persistir, falar com a equipe Jusfy. | | `502` | `upstream_error` | O motor de cálculo ou o fornecedor falhou. | Ver a orientação de cada rota: nem sempre repetir resolve. | | `503` | `upstream_unavailable` | O fornecedor (ex.: o órgão consultado) está fora do ar; a consulta não rodou. | Repetir depois de um intervalo. | | `504` | `upstream_timeout` | O motor de cálculo ou o fornecedor não respondeu a tempo. | Repetir depois de um intervalo. | Códigos novos podem surgir para condições que hoje não são tratadas (ver "Versionamento e depreciação"): trate um `code` desconhecido pelo status. Um `code` existente nunca muda de significado na mesma versão. Nas consultas assíncronas e no relatório PDF da completa há ainda `202` (aceito e em processamento). ### Limite de requisições Cada cliente tem um limite de requisições por minuto **em cada produto** (calculadora, consulta ou JusScore); os produtos não dividem o limite entre si. A consulta do consumo tem um contador próprio, que também não divide o limite com nenhum produto. Toda resposta informa o estado do limite nos headers: | Header | Significado | | ------ | ----------- | | `X-RateLimit-Limit` | Requisições permitidas por minuto neste produto. | | `X-RateLimit-Remaining` | Quantas ainda cabem na janela atual. | | `X-RateLimit-Reset` | Segundos até a janela atual acabar. | Acima do limite a resposta é `429` com o header `Retry-After` (segundos até poder tentar de novo). A requisição recusada não é processada nem cobrada. ## Versionamento e depreciação A versão vai no path (`/api/v1/...`). `info.version` deste documento segue semver: MAJOR é a versão do path, MINOR é mudança compatível e PATCH é só documentação. **Mudanças compatíveis** entram na versão atual, como MINOR, sem aviso prévio. Sua integração deve tolerá-las: - campo novo na resposta; - campo opcional novo no request; - rota nova; - valor novo de enum **na resposta**, quando o campo estiver documentado como extensível; - código de erro novo para uma condição que antes não era tratada. **Mudanças incompatíveis** só entram numa versão nova de path: - remover ou renomear path, campo ou valor de enum; - tornar obrigatório um campo opcional; - mudar o tipo ou o formato de um campo; - mudar o significado de um status code; - mudar o formato do envelope ou do erro; - mudar a assinatura ou o corpo de um webhook. Quando uma versão é depreciada, você recebe **três sinais**: 1. os headers `Deprecation`, `Sunset` (quando houver data de desligamento) e `Link` (`rel="deprecation"`, apontando para o guia de migração) em toda resposta da versão; 2. as operações marcadas como `deprecated` no contrato da versão; 3. comunicação direta aos clientes que ainda chamam a versão. **Prazo mínimo** entre a depreciação e o desligamento: _pendente: produto_. **Comunicação**: quem avisa o cliente e por qual canal: _pendente: produto_. Uma versão só é desligada quando as duas condições valem: o prazo de aviso venceu **e** todo cliente que ainda a chama foi contatado. Desligada, as rotas dela respondem **`410 Gone`**, no formato de erro padrão, com `message` apontando para o guia de migração. ## Changelog Toda mudança de `info.version` ganha uma entrada no [changelog](https://docs.jusfy.com.br/changelog). ## Migração do legado Payloads e respostas são os mesmos nas duas versões. O passo a passo está no [guia de migração](https://docs.jusfy.com.br/fundamentos/migracao-do-legado). version: 1.1.0 contact: {} servers: - url: https://api.jusfy.dev/calculators security: [] tags: - name: Calculadoras description: >- Execução das calculadoras jurídicas e consulta dos índices de correção. Cada cálculo recebe um payload, retorna o resultado processado e exige API key no header `x-api-key`. - name: Consultas description: >- Consultas de dados (veículos, condutores e documentos). Cada consulta recebe o documento, retorna os dados encontrados e exige API key no header `x-api-key`. A maioria responde na mesma requisição; o **rastreamento veicular** e o **buscador processual** são assíncronos — devolvem `202` com um protocolo e entregam o resultado por webhook e/ou pelo `GET` do protocolo. - name: JusScore description: >- Consulta de processos judiciais por CPF/CNPJ, com score de risco consolidado e a lista detalhada dos processos. É assíncrona: o POST inicia a consulta e o GET devolve o resultado quando pronto. Exige API key no header `x-api-key`. - name: Consumo description: >- Consumo da própria API key: quantas chamadas cada produto recebeu num período, separando as cobradas das não cobradas. Não exige escopo; exige API key no header `x-api-key`. - name: Health description: >- Verificações de disponibilidade do serviço (liveness e readiness). Rotas abertas, sem autenticação. paths: /api/v1/calculadoras/superendividamento: post: tags: - Calculadoras summary: Calcula o plano de pagamento no superendividamento description: >- Monta um plano de pagamento das dívidas do devedor conforme a Lei do Superendividamento, respeitando o mínimo existencial. Informe as dívidas (`debts`), o prazo e a carência do plano, o sistema de amortização (`price` ou `sac`), a taxa de juros e o mínimo existencial (`minimum_living_income`). A resposta traz o resumo do plano (`summary`), o rateio das parcelas por credor (`installments_by_creditor`) e o cronograma consolidado (`amortization_schedule`). operationId: CalculatorsController_superendividamento[1]_v1 parameters: [] requestBody: required: true description: Payload da calculadora de superendividamento. content: application/json: schema: type: object description: >- Payload do cálculo de superendividamento. Informe as dívidas a renegociar, os parâmetros do plano (prazo, carência, juros e sistema de amortização) e o mínimo existencial; a resposta traz o resumo do plano, o rateio das parcelas por credor e o cronograma consolidado de amortização. required: - planning_start_date - number_of_months - grace_period - debts - amortization_type - interest_rate - minimum_living_income properties: name: type: string description: Nome do cálculo. Opcional; não afeta o resultado. planning_start_date: type: string format: date description: Data de início do planejamento (`YYYY-MM-DD`). number_of_months: type: number description: Quantidade de meses do plano (inteiro positivo). grace_period: type: number description: Período de carência, em dias (`0..180`). debts: type: array description: Dívidas a renegociar. Deve conter **pelo menos um** item. items: type: object description: Dívida a renegociar no plano. required: - item_id - creditor - amount properties: item_id: type: number description: Identificador da dívida (inteiro `>= 0`). creditor: type: string description: Nome do credor (mínimo 1 caractere). description: type: string description: Descrição da dívida. Opcional. amount: type: number description: Valor total da dívida (positivo). amount_installment: type: number description: >- Valor da parcela atual da dívida, se houver. Opcional (`>= 0`). amortization_type: type: string enum: - price - sac description: Sistema de amortização aplicado ao plano. interest_rate: type: number description: Juros mensal (%) aplicado ao plano (`>= 0`). minimum_living_income: type: object description: >- Parâmetros do mínimo existencial usados para limitar o valor da parcela. required: - total_income - percentage_minimum_living properties: total_income: type: number description: Renda total do devedor (positivo). percentage_minimum_living: type: number description: >- Percentual da renda reservado ao mínimo existencial (positivo). total_installment_value: type: number description: >- Valor total já comprometido com parcelas. Opcional (`>= 0`). percentage_installment_value: type: number description: >- Percentual da renda já comprometido com parcelas. Opcional (`>= 0`). examples: superendividamento: summary: Plano de pagamento (tabela Price) value: name: Plano de superendividamento - exemplo planning_start_date: '2024-09-20' number_of_months: 10 grace_period: 0 amortization_type: price interest_rate: 10 debts: - item_id: 1 creditor: Credor A description: Cartão de crédito amount: 3000 - item_id: 2 creditor: Credor B description: Empréstimo pessoal amount: 2000 minimum_living_income: total_income: 5000 percentage_minimum_living: 50 responses: '200': description: Resultado do plano, com resumo, rateio por credor e cronograma. content: application/json: schema: type: object example: statusCode: 200 message: Cálculo concluído com sucesso timestamp: '2026-06-22T18:00:00.000Z' path: /api/v1/calculadoras/superendividamento result: summary: outstanding_balance: 5000 total_interest_paid: 3137.29 total_paid: 8137.3 grace_period: 0 interest_rate: 10 number_of_months: 10 installment_fixed_value: 813.73 outstanding_balance_remaining: 0 plan_status: possible installments_by_creditor: - name: Credor A description: Cartão de crédito payment_amount: 488.24 outstanding_balance: 3000 total_interest_paid: 1882.38 total_paid: 4882.4 outstanding_balance_remaining: 0 installments: - number: 0 due_date: '2024-08-20' amortization: 0 interest: 0 payment_amount: 0 outstanding_balance: 3000 monthly_interest_rate: 0.1 - number: 1 due_date: '2024-09-20' amortization: 188.24 interest: 300 payment_amount: 488.24 outstanding_balance: 2811.76 monthly_interest_rate: 0.1 - number: 2 due_date: '2024-10-20' amortization: 207.06 interest: 281.18 payment_amount: 488.24 outstanding_balance: 2604.7 monthly_interest_rate: 0.1 - number: 3 due_date: '2024-11-20' amortization: 227.77 interest: 260.47 payment_amount: 488.24 outstanding_balance: 2376.94 monthly_interest_rate: 0.1 - number: 4 due_date: '2024-12-20' amortization: 250.54 interest: 237.7 payment_amount: 488.24 outstanding_balance: 2126.39 monthly_interest_rate: 0.1 - number: 5 due_date: '2025-01-20' amortization: 275.6 interest: 212.64 payment_amount: 488.24 outstanding_balance: 1850.8 monthly_interest_rate: 0.1 - number: 6 due_date: '2025-02-20' amortization: 303.16 interest: 185.08 payment_amount: 488.24 outstanding_balance: 1547.65 monthly_interest_rate: 0.1 - number: 7 due_date: '2025-03-20' amortization: 333.47 interest: 154.76 payment_amount: 488.24 outstanding_balance: 1214.17 monthly_interest_rate: 0.1 - number: 8 due_date: '2025-04-20' amortization: 366.82 interest: 121.42 payment_amount: 488.24 outstanding_balance: 847.35 monthly_interest_rate: 0.1 - number: 9 due_date: '2025-05-20' amortization: 403.5 interest: 84.74 payment_amount: 488.24 outstanding_balance: 443.85 monthly_interest_rate: 0.1 - number: 10 due_date: '2025-06-20' amortization: 443.85 interest: 44.39 payment_amount: 488.24 outstanding_balance: 0 monthly_interest_rate: 0.1 - name: Credor B description: Empréstimo pessoal payment_amount: 325.49 outstanding_balance: 2000 total_interest_paid: 1254.91 total_paid: 3254.9 outstanding_balance_remaining: 0 installments: - number: 0 due_date: '2024-08-20' amortization: 0 interest: 0 payment_amount: 0 outstanding_balance: 2000 monthly_interest_rate: 0.1 - number: 1 due_date: '2024-09-20' amortization: 125.49 interest: 200 payment_amount: 325.49 outstanding_balance: 1874.51 monthly_interest_rate: 0.1 - number: 2 due_date: '2024-10-20' amortization: 138.04 interest: 187.45 payment_amount: 325.49 outstanding_balance: 1736.47 monthly_interest_rate: 0.1 - number: 3 due_date: '2024-11-20' amortization: 151.84 interest: 173.65 payment_amount: 325.49 outstanding_balance: 1584.62 monthly_interest_rate: 0.1 - number: 4 due_date: '2024-12-20' amortization: 167.03 interest: 158.46 payment_amount: 325.49 outstanding_balance: 1417.6 monthly_interest_rate: 0.1 - number: 5 due_date: '2025-01-20' amortization: 183.73 interest: 141.76 payment_amount: 325.49 outstanding_balance: 1233.87 monthly_interest_rate: 0.1 - number: 6 due_date: '2025-02-20' amortization: 202.1 interest: 123.39 payment_amount: 325.49 outstanding_balance: 1031.76 monthly_interest_rate: 0.1 - number: 7 due_date: '2025-03-20' amortization: 222.32 interest: 103.18 payment_amount: 325.49 outstanding_balance: 809.45 monthly_interest_rate: 0.1 - number: 8 due_date: '2025-04-20' amortization: 244.55 interest: 80.94 payment_amount: 325.49 outstanding_balance: 564.9 monthly_interest_rate: 0.1 - number: 9 due_date: '2025-05-20' amortization: 269 interest: 56.49 payment_amount: 325.49 outstanding_balance: 295.9 monthly_interest_rate: 0.1 - number: 10 due_date: '2025-06-20' amortization: 295.9 interest: 29.59 payment_amount: 325.49 outstanding_balance: 0 monthly_interest_rate: 0.1 amortization_schedule: total_interest_paid: 3137.29 total_paid: 8137.3 installments: - number: 0 due_date: '2024-08-20' payment_amount: 0 interest: 0 amortization: 0 outstanding_balance: 5000 monthly_interest_rate: 0.1 - number: 1 due_date: '2024-09-20' payment_amount: 813.73 interest: 500 amortization: 313.73 outstanding_balance: 4686.27 monthly_interest_rate: 0.1 - number: 2 due_date: '2024-10-20' payment_amount: 813.73 interest: 468.63 amortization: 345.1 outstanding_balance: 4341.17 monthly_interest_rate: 0.1 - number: 3 due_date: '2024-11-20' payment_amount: 813.73 interest: 434.12 amortization: 379.61 outstanding_balance: 3961.56 monthly_interest_rate: 0.1 - number: 4 due_date: '2024-12-20' payment_amount: 813.73 interest: 396.16 amortization: 417.57 outstanding_balance: 3543.99 monthly_interest_rate: 0.1 - number: 5 due_date: '2025-01-20' payment_amount: 813.73 interest: 354.4 amortization: 459.33 outstanding_balance: 3084.67 monthly_interest_rate: 0.1 - number: 6 due_date: '2025-02-20' payment_amount: 813.73 interest: 308.47 amortization: 505.26 outstanding_balance: 2579.41 monthly_interest_rate: 0.1 - number: 7 due_date: '2025-03-20' payment_amount: 813.73 interest: 257.94 amortization: 555.79 outstanding_balance: 2023.62 monthly_interest_rate: 0.1 - number: 8 due_date: '2025-04-20' payment_amount: 813.73 interest: 202.36 amortization: 611.37 outstanding_balance: 1412.25 monthly_interest_rate: 0.1 - number: 9 due_date: '2025-05-20' payment_amount: 813.73 interest: 141.23 amortization: 672.5 outstanding_balance: 739.75 monthly_interest_rate: 0.1 - number: 10 due_date: '2025-06-20' payment_amount: 813.73 interest: 73.98 amortization: 739.75 outstanding_balance: 0 monthly_interest_rate: 0.1 '401': description: >- API key ausente ou que não pertence a nenhum cliente (`code: invalid_api_key`). A `message` diz qual dos dois. content: application/json: examples: missing: summary: Key ausente value: statusCode: 401 message: Missing API key code: invalid_api_key requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-10-14T18:00:00.000Z' path: /api/v1/calculadoras/trabalhista invalid: summary: Key inválida value: statusCode: 401 message: Invalid API key code: invalid_api_key requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-10-14T18:00:00.000Z' path: /api/v1/calculadoras/trabalhista '403': description: >- Acesso negado. Dois motivos, distinguidos pelo `code`: o cliente não está ativo (`inactive_client`), ou a API key não tem o escopo deste produto (`insufficient_scope`, com o escopo na `message`). A liberação de produtos é feita pela equipe Jusfy. content: application/json: examples: inactive_client: summary: Cliente não ativo value: statusCode: 403 message: Client is not active code: inactive_client requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-10-14T18:00:00.000Z' path: /api/v1/calculadoras/trabalhista insufficient_scope: summary: Sem o escopo do produto value: statusCode: 403 message: 'Missing scope: ' code: insufficient_scope requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-10-14T18:00:00.000Z' path: /api/v1/calculadoras/trabalhista '422': description: Payload inválido. `message` indica o campo e o motivo. content: application/json: schema: example: statusCode: 422 code: payload_rejected message: 'Expected number, received null (property: fine)' requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-06-22T18:00:00.000Z' path: /api/v1/calculadoras/superendividamento '429': description: >- Limite de requisições por minuto do cliente neste produto excedido. `Retry-After` diz em quantos segundos a janela vira. Toda resposta traz `X-RateLimit-Limit`, `X-RateLimit-Remaining` e `X-RateLimit-Reset`. content: application/json: schema: example: statusCode: 429 code: rate_limit_exceeded message: >- Rate limit exceeded for calculadoras.trabalhista:execute: 60 requests per minute. Retry in 42s. requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-06-22T18:00:00.000Z' path: /api/v1/calculadoras/trabalhista '502': description: Erro no motor de cálculo da Jusfy. content: application/json: schema: example: statusCode: 502 code: upstream_error message: Calculation backend error requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-06-22T18:00:00.000Z' path: /api/v1/calculadoras/superendividamento '504': description: Tempo limite ao falar com o motor de cálculo. content: application/json: schema: example: statusCode: 504 code: upstream_timeout message: Calculation backend timed out requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-06-22T18:00:00.000Z' path: /api/v1/calculadoras/superendividamento security: - api-key: [] components: securitySchemes: api-key: type: apiKey in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.