Guides

Fluxo de Chamadas da API

Sequência recomendada de chamadas para operar uma operação de crédito, do simulador ao desembolso.

Sequência recomendada de chamadas para operar uma operação de crédito, da simulação inicial ao servicing e cobrança pós-desembolso.

Toda chamada abaixo pressupõe um token de acesso válido, obtido via POST /auth/token.

Etapa 1 — Simulação e originação

#PassoChamada
1Consultar produtos de crédito autorizados.GET /me/products
2Simular condições da operação (taxa, CET, IOF, cronograma de parcelas).POST /simulations
3Criar a operação de crédito vinculando o produto (productId), tomador, desembolso (banco ou Pix), primeiro vencimento opcional (firstPaymentDate) e TAC opcional.POST /credit-operations
4Enviar documentos do tomador (documento de identificação, comprovantes, selfie).POST /credit-operations/{externalContractId}/documents
5Consultar status atual da operação a qualquer momento.GET /credit-operations/{externalContractId}
📘

Simulação Stateless

A simulação (POST /simulations) é stateless: calcula taxas e parcelas sem reservar limite nem criar registros no banco de dados.

📘

Data do Primeiro Pagamento/Vencimento (firstPaymentDate / firstPayment)

Na criação da operação (POST /credit-operations), você pode enviar opcionalmente no corpo da requisição o campo firstPaymentDate (ou o alias firstPayment, ex.: "firstPaymentDate": "2026-11-15T00:00:00Z"):

  • O valor define a data de vencimento da 1ª parcela.
  • É utilizado para gerar o cronograma de parcelas (installments, onde cada parcela possui seu próprio dueDate), calcular a simulação com IOF e fixar o dia de vencimento mensal da operação (product.dueDayOfMonth).
  • As parcelas subsequentes seguem mensalmente a partir dessa data.
  • Se omitido, a operação segue a regra padrão de simulação (primeiro vencimento em 30 dias).
📘

Flexibilidade nos Dados de Desembolso (Conta Bancária ou Chave Pix)

Na criação da operação (POST /credit-operations), o objeto disbursement aceita dados bancários (bankCode, branchNumber, accountNumber, accountDigit, accountType) e/ou chave Pix (pixKey):

  • Se informar chave Pix (pixKey), os dados bancários podem ser nulos/omitidos.
  • Se informar dados bancários completos, pixKey pode ser nula/omitida.
  • Se ambos forem informados, ambos são registrados e propagados para a liquidação.

Etapa 2 — Aprovação, formalização e desembolso

A formalização do contrato pode ocorrer pelo fluxo eletrônico nativo do LaaS ou pelo fluxo de formalização externa do parceiro.

Opção A: Fluxo Eletrônico LaaS (Padrão)

#PassoChamada
6Aprovar a proposta de crédito (transição RECEIVED → APPROVED).POST /credit-operations/{externalContractId}/approve
7Gerar a minuta oficial do contrato (APPROVED → CONTRACT_GENERATED).POST /credit-operations/{externalContractId}/contract
8(Opcional) Baixar o PDF da minuta gerada para conferência.GET /credit-operations/{externalContractId}/contract
9Enviar a solicitação de assinatura eletrônica ao tomador (CONTRACT_GENERATED → CONTRACT_SIGNING_PENDING).POST /credit-operations/{externalContractId}/contract/sign
10Solicitar o desembolso após a assinatura concluída (CONTRACT_SIGNED → DISBURSEMENT_REQUESTED).POST /credit-operations/{externalContractId}/disbursement

Opção B: Fluxo Externo (Upload de Minuta e Assinatura por Fingerprint)

#PassoChamada
6Aprovar a proposta de crédito (RECEIVED → APPROVED).POST /credit-operations/{externalContractId}/approve
7Enviar o PDF do contrato gerado externamente (APPROVED → CONTRACT_GENERATED).POST /credit-operations/{externalContractId}/contract/upload
8Submeter o manifesto auditável de fingerprint com evidências de aceite dos signatários (CONTRACT_GENERATED → CONTRACT_SIGNED).POST /credit-operations/{externalContractId}/contract/fingerprint
9Solicitar o desembolso do crédito (CONTRACT_SIGNED → DISBURSEMENT_REQUESTED).POST /credit-operations/{externalContractId}/disbursement

Etapa 3 — Servicing e gestão de cobrança (Pós-Desembolso)

Após o desembolso liquidado com sucesso (DISBURSED), a operação entra no ciclo de servicing para gestão de parcelas, emissão de cobranças Pix e liquidações.

#PassoChamada
11Consultar cronograma de parcelas e meios de pagamento ativos da operação.GET /credit-operations/{externalContractId}/payment-plan
12Gerar cobrança Pix com código Copia e Cola (EMV) e QR Code em Base64.POST /credit-operations/{externalContractId}/billings
13Registrar amortização parcial ou pagamento de parcela individual.POST /credit-operations/{externalContractId}/installments/{installmentNumber}/payments
14Quitar integralmente uma parcela individual.POST /credit-operations/{externalContractId}/installments/{installmentNumber}/liquidate
15Realizar quitação antecipada integral de todo o contrato.POST /credit-operations/{externalContractId}/payment-plan/liquidate
⚠️

Atenção — Regra de Perda de Lastro em Liquidação Externa

A liquidação de parcelas originadas de fontes externas exige autorização explícita no produto (ServicingSettings.AllowExternalLiquidation == true). Caso o produto não permita, a API retornará 403 Forbidden.

Importante: Para liquidações externas, perde-se o lastro financeiro e transacional da operação na plataforma.

Observações Gerais

  • Idempotência: O campo externalContractId é a chave de idempotência do parceiro. Reenvios com os mesmos dados retornam a operação existente sem duplicidade.
  • Produto Obrigatório: Toda criação de operação exige um productId válido e autorizado para o parceiro.
  • Webhooks: Prefira assinar os webhooks em vez de efetuar polling nos endpoints de consulta. Veja o catálogo completo em Arquitetura de Webhooks.
  • Cancelamento: Antes do desembolso, a operação pode ser cancelada a qualquer instante via POST /credit-operations/{externalContractId}/cancel.

Updated 3 days ago

Did this page help you?