> ## 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 a revisão de contrato (revisional)

> Revisa um contrato de financiamento/empréstimo: recalcula a tabela de amortização (`price` ou `sac`) aplicando a taxa média de mercado, apura as diferenças (a pagar ou a receber) e, quando o resultado é a pagar (`type: "payable"`), monta o cronograma de refinanciamento. Informe os dados do contrato (valor, parcelas, taxas e datas), a taxa média (`average_interest`/`own_average_interest`) e as parcelas pagas (`paid_installments`). A resposta traz o cronograma recalculado (`schedule`), os totais e os valores apurados.

Os campos `contract_type` e `contract_price_index` referenciam índices do backend (`GET /api/calculadoras/indices-correcao`) e devem existir; caso contrário o cálculo falha.



## OpenAPI

````yaml /openapi/legado.json post /api/calculadoras/revisional
openapi: 3.0.0
info:
  title: Calculadoras Jusfy API
  description: >-
    Rotas sem versão (`/api/...`). Continuam funcionando, mas a versão atual

    da API é a v1 (`/api/v1`): para integrações novas, use a v1 e siga o [guia
    de
    migração](https://api.jusfy.dev/calculators/api/reference/fundamentos/migracao-do-legado).


    A política de versionamento e depreciação está na [política de
    versionamento](https://api.jusfy.dev/calculators/api/reference/fundamentos/migracao-do-legado#pol%C3%ADtica-de-versionamento).
  version: legacy
  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/calculadoras/revisional:
    post:
      tags:
        - Calculadoras
      summary: Calcula a revisão de contrato (revisional)
      description: >-
        Revisa um contrato de financiamento/empréstimo: recalcula a tabela de
        amortização (`price` ou `sac`) aplicando a taxa média de mercado, apura
        as diferenças (a pagar ou a receber) e, quando o resultado é a pagar
        (`type: "payable"`), monta o cronograma de refinanciamento. Informe os
        dados do contrato (valor, parcelas, taxas e datas), a taxa média
        (`average_interest`/`own_average_interest`) e as parcelas pagas
        (`paid_installments`). A resposta traz o cronograma recalculado
        (`schedule`), os totais e os valores apurados.


        Os campos `contract_type` e `contract_price_index` referenciam índices
        do backend (`GET /api/calculadoras/indices-correcao`) e devem existir;
        caso contrário o cálculo falha.
      operationId: CalculatorsController_revisional[0]
      parameters: []
      requestBody:
        required: true
        description: Payload da calculadora revisional.
        content:
          application/json:
            schema:
              type: object
              description: >-
                Payload da revisão de contrato. Informe os dados do contrato
                (valor, parcelas, taxas, datas e tipo), a taxa média de mercado
                e as parcelas pagas. A resposta traz a tabela de amortização
                recalculada, as diferenças apuradas (a pagar ou a receber), os
                totais e, quando aplicável, o cronograma de refinanciamento.


                Os campos `contract_type` e `contract_price_index` referenciam
                índices (`Index`) do backend (obtidos em `GET
                /api/calculadoras/indices-correcao`) e devem existir; caso
                contrário o cálculo falha.
              required:
                - amortization_system
                - average_interest
                - average_interest_periodicity
                - contract_another_taxes
                - contract_balance_index
                - contract_balance_period
                - contract_date
                - contract_goods
                - contract_installments
                - contract_iof
                - contract_service_tax
                - contract_type
                - contract_value
                - differences_has_interests
                - differences_interest_rate
                - first_installment_date
                - installment_amount
                - interest_rate
                - interest_rate_periodicity
                - own_average_interest
                - paid_installments
                - report_date
              properties:
                contract_number:
                  type: string
                  description: Número do contrato. Opcional (default `""`).
                amortization_system:
                  type: string
                  enum:
                    - price
                    - sac
                  description: >-
                    Sistema de amortização. Retornado em maiúsculo
                    (`PRICE`/`SAC`).
                average_interest:
                  type: number
                  description: >-
                    Taxa média de mercado informada (usada quando
                    `own_average_interest` é `true`).
                average_interest_periodicity:
                  type: string
                  description: 'Periodicidade da taxa média (ex.: `monthly`).'
                contract_another_taxes:
                  type: number
                  description: Outras taxas/tarifas do contrato.
                contract_balance_index:
                  type: string
                  description: >-
                    Índice de correção do saldo. String vazia (`""`) = sem
                    índice de saldo.
                contract_balance_period:
                  type: string
                  description: 'Periodicidade da correção do saldo (ex.: `Mensal`).'
                contract_date:
                  type: string
                  format: date
                  description: Data do contrato (`YYYY-MM-DD`).
                contract_goods:
                  type: number
                  description: Valor de bens/entrada.
                contract_installments:
                  type: number
                  description: Número de parcelas do contrato.
                contract_iof:
                  type: number
                  description: IOF do contrato.
                contract_price_index:
                  type: number
                  nullable: true
                  description: >-
                    Id do índice (`Index`) de correção das diferenças. Precisa
                    existir. Opcional/`null` quando não há correção.
                contract_service_tax:
                  type: number
                  description: Taxa de serviço do contrato.
                contract_type:
                  type: number
                  description: >-
                    Id do tipo de contrato (`Index`) do backend. Precisa
                    existir.
                contract_value:
                  type: number
                  description: Valor financiado do contrato.
                differences_has_interests:
                  type: boolean
                  description: Se as diferenças apuradas incidem juros.
                differences_interest_rate:
                  type: number
                  description: Taxa de juros aplicada às diferenças.
                first_installment_date:
                  type: string
                  format: date
                  description: Data da primeira parcela (`YYYY-MM-DD`).
                installment_amount:
                  type: number
                  description: Valor da parcela do contrato.
                interest_rate:
                  type: number
                  description: Taxa de juros do contrato.
                interest_rate_periodicity:
                  type: string
                  description: 'Periodicidade da taxa de juros do contrato (ex.: `monthly`).'
                own_average_interest:
                  type: boolean
                  description: >-
                    Se `true`, usa a `average_interest` informada; se `false`,
                    busca a taxa média Bacen no backend.
                paid_installments:
                  type: array
                  description: >-
                    Parcelas pagas. O cálculo considera apenas as com `paid:
                    true`.
                  items:
                    type: object
                    required:
                      - date
                      - amount
                      - paid
                    properties:
                      date:
                        type: string
                        format: date
                        description: Data do pagamento (`YYYY-MM-DD`).
                      amount:
                        type: number
                        description: Valor pago.
                      paid:
                        type: boolean
                        description: >-
                          Se a parcela foi paga (só as `true` entram no
                          cálculo).
                report_date:
                  type: string
                  format: date
                  description: Data-base do cálculo/relatório (`YYYY-MM-DD`).
            examples:
              revisional:
                summary: Revisão de contrato (tabela Price)
                value:
                  contract_number: VEIC-2021-0042
                  amortization_system: price
                  average_interest: 1.8
                  average_interest_periodicity: monthly
                  contract_another_taxes: 0
                  contract_balance_index: ''
                  contract_balance_period: Mensal
                  contract_date: '2021-01-10'
                  contract_goods: 0
                  contract_installments: 24
                  contract_iof: 0
                  contract_price_index: 6
                  contract_service_tax: 0
                  contract_type: 24
                  contract_value: 40000
                  differences_has_interests: false
                  differences_interest_rate: 1
                  first_installment_date: '2021-02-10'
                  installment_amount: 2100
                  interest_rate: 3
                  interest_rate_periodicity: monthly
                  own_average_interest: true
                  paid_installments:
                    - date: '2021-02-10'
                      amount: 2100
                      paid: true
                    - date: '2021-03-10'
                      amount: 2100
                      paid: true
                    - date: '2021-04-10'
                      amount: 2100
                      paid: true
                  report_date: '2023-01-10'
      responses:
        '200':
          description: >-
            Resultado da revisão, com cronograma recalculado, diferenças e
            totais.
          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/calculadoras/revisional
                  result:
                    odds: 25
                    type: payable
                    contract_number: VEIC-2021-0042
                    calculation_remaining_installments: 21
                    schedule:
                      - number: -1
                        interest: 0
                        amortization: null
                        installmentAmount: null
                        outstandingBalance: 40720
                        updatedBalance: 40720
                        due: '2020-12-10'
                        paymentDate: null
                        paidAmount: null
                        differenceAmount: null
                        differenceAdjustedAmount: null
                        adjusted: null
                        delayDays: null
                        interests: null
                        total: null
                      - number: 0
                        interest: 732.96
                        amortization: null
                        installmentAmount: null
                        updatedBalance: 40720
                        due: '2021-01-10'
                        outstandingBalance: 41452.96
                        paymentDate: null
                        paidAmount: null
                        differenceAmount: null
                        differenceAdjustedAmount: null
                        adjusted: null
                        delayDays: null
                        interests: null
                        total: null
                      - number: 1
                        interest: 746.15
                        amortization: 1396.17
                        installmentAmount: 2142.32
                        updatedBalance: 41452.96
                        due: '2021-02-10'
                        outstandingBalance: 40056.79
                        paymentDate: '2021-02-10'
                        paidAmount: 2100
                        differenceAmount: -42.32
                        differenceAdjustedAmount: -48.51
                        adjustedPercentage: 14.63
                        delayDays: 0
                        interests: 0
                        total: -48.51
                      - number: 24
                        interest: 37.88
                        amortization: 2104.44
                        installmentAmount: 2142.32
                        updatedBalance: 2104.54
                        due: '2023-01-10'
                        outstandingBalance: 0.1
                        paymentDate: null
                        paidAmount: null
                        differenceAmount: -2142.32
                        differenceAdjustedAmount: -2142.32
                        adjustedPercentage: 0
                        delayDays: 0
                        interests: 0
                        total: -2142.32
                    refinancing_schedule:
                      schedule:
                        - number: 0
                          interest: 0
                          amortization: null
                          installmentAmount: null
                          outstandingBalance: 37332.96
                          updatedBalance: 37332.96
                          due: '2021-04-10'
                        - number: 1
                          interest: 671.99
                          amortization: 1478.65
                          installmentAmount: 2150.64
                          updatedBalance: 37332.96
                          due: '2021-05-10'
                          outstandingBalance: 35854.31
                        - number: 21
                          interest: 38.03
                          amortization: 2112.61
                          installmentAmount: 2150.64
                          updatedBalance: 2112.61
                          due: '2023-01-10'
                          outstandingBalance: 0
                      summary:
                        firstInstallmentAmount: 2150.64
                      totalInstallments: 45163.44
                      totalInterests: 7830.48
                      totalAmortizations: 37332.96
                    contract_date: '2021-01-10'
                    first_installment_date: '2021-02-10'
                    differences_has_interests: false
                    differences_interest_rate: 1
                    total_amortizations: 41452.86
                    total_installments: 51415.68
                    total_interests: 10695.78
                    total_paid_amount: 6300
                    total_difference_amount: -45115.68
                    calculation_differences_total: -46777.67
                    calculation_adjusted_amounts: -46777.67
                    calculations_interests_total: 0
                    contract_another_taxes: 0
                    contract_service_tax: 0
                    contract_iof: 0
                    grace_period: 1
                    gracePeriodInDays: 0
                    amortization_system: PRICE
                    report_date: '2023-01-10'
                    adjustment_until: ' (correção até 10/2022)'
                    differences_index: true
                    differences_index_name: IPCA (GERAL)
                    refinancing_balance: 37188.61
                    differences_paid: -144.35
                    refinancing_amount: 37332.96
                    petition_filename: aquisicao-veiculos.docx
                    sector: ''
                    contract_type: Aquisição de veículos
                    contract_type_code_monthly: '25447'
                    contract_type_code_annually: '20728'
                    bacen_average_interest_monthly: 1.8
                    bacen_average_interest_annually: 23.87205315755283
                    bacen_interest_percentage_increase: 7.777777777777772
                    contract_amount: 40000
                    contract_goods: 40000
                    contract_installments: 24
                    contract_paid_installments: 3
                    contract_installment_amount: 2100
                    contract_amount_cost_effective: 50400
                    contract_interest_rate_monthly: 1.94
                    contract_interest_rate_annually: 25.931840613381894
                    calculation_receivable_amount: 37332.96
                    calculation_payable_amount: 37332.96
                    calculation_difference: 37332.96
                    calculation_installment_adjusted: 2142.32
                    calculation_refinancing_installments_amount: 2150.64
                    own_average_interest: true
        '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/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/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/calculadoras/trabalhista
                insufficient_scope:
                  summary: Sem o escopo do produto
                  value:
                    statusCode: 403
                    message: 'Missing scope: <escopo>'
                    code: insufficient_scope
                    requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65
                    timestamp: '2026-10-14T18:00:00.000Z'
                    path: /api/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/calculadoras/revisional
        '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/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/calculadoras/revisional
        '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/calculadoras/revisional
      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.