Contratos

Endpoints para criação, envio, aceite e atualização de contratos.

Ciclo de vida: DRAFT → PENDING_ACCEPTANCE (após envio) → ACCEPTED (após aceite do tomador) → ACTIVE → COMPLETED / CANCELLED.

O envio ao tomador é um passo só: não existe aprovação separada do credor. O status LENDER_APPROVED é legado — contratos que ficaram nele continuam podendo ser enviados.

ACTIVE nunca é atribuído por chamada de API. O serviço reavalia a ativação no aceite e a cada 5 minutos, e só promove o contrato quando o lock da garantia está ACTIVE e a CCB está assinada.

O aceite do tomador tambem e um passo da jornada de credito: veja POST /simulation/v1/contracts/from-lender/{contractId} em Jornada do tomador abaixo.

O tomador é identificado pelo documento e não precisa ter conta na plataforma para o contrato existir: basta estar pré-cadastrado (veja Pré-cadastro do tomador abaixo). A conta nasce quando o próprio tomador conclui o onboarding — e é ela que permite o accept.

A criação suporta upload opcional do arquivo CCB via multipart/form-data. Valores monetários e percentuais são retornados como string decimal (ex.: "100000", "2.5").

{
  "name": "Contrato BTC 2026/05",
  "description": "Empréstimo lastreado em cripto com colateral de 150%",
  "totalLoanValue": 100000,
  "outstandingBalance": 100000,
  "interestRate": 2.5,
  "cet": 3.1,
  "installmentsCount": 12,
  "startDate": "2026-05-15",
  "endDate": "2027-05-15",
  "collateralPercentage": 150,
  "fiatCurrency": "BRL",
  "acceptedTokens": [
    { "tokenSymbol": "USDC", "network": "ETHEREUM" },
    { "tokenSymbol": "USDT", "network": "POLYGON" }
  ],
  "borrower": {
    "document": "12345678901"
  }
}

{
  "message": "Contract created successfully",
  "data": {
    "id": 123,
    "name": "Contrato BTC 2026/05",
    "description": "Empréstimo lastreado em cripto com colateral de 150%",
    "collateralPercentage": "150",
    "totalLoanValue": "100000",
    "outstandingBalance": "100000",
    "interestRate": "2.5",
    "cet": "3.1",
    "installmentsCount": 12,
    "startDate": "2026-05-15T00:00:00.000Z",
    "endDate": "2027-05-15T00:00:00.000Z",
    "lenderDocument": "11222333000181",
    "borrowerDocument": "12345678901",
    "status": "DRAFT",
    "createdAt": "2026-05-13T18:00:00.000Z",
    "updatedAt": "2026-05-13T18:00:00.000Z",
    "deletedAt": null,
    "acceptedTokens": [
      {
        "id": 1,
        "contractId": 123,
        "tokenSymbol": "USDC",
        "network": "ETHEREUM",
        "createdAt": "2026-05-13T18:00:00.000Z",
        "deletedAt": null
      },
      {
        "id": 2,
        "contractId": 123,
        "tokenSymbol": "USDT",
        "network": "POLYGON",
        "createdAt": "2026-05-13T18:00:00.000Z",
        "deletedAt": null
      }
    ],
    "documents": [
      {
        "id": "0d3a2c1e-9f4b-4c8a-b7d6-5e4f3a2b1c0d",
        "contractId": 123,
        "originalName": "ccb.pdf",
        "mimeType": "application/pdf",
        "createdAt": "2026-05-13T18:00:00.000Z",
        "deletedAt": null
      }
    ],
    "guarantee": {
      "id": 77,
      "contractId": 123,
      "fiatCurrency": "BRL",
      "requiredFiatAmount": "150000",
      "depositedFiatAmount": "0",
      "status": "PENDING",
      "createdAt": "2026-05-13T18:00:00.000Z",
      "updatedAt": "2026-05-13T18:00:00.000Z",
      "deletedAt": null
    },
    "borrower": {
      "name": "João da Silva",
      "email": "joao@exemplo.com",
      "phone": "11999998888"
    }
  }
}

Campos do contrato

O objeto borrower da resposta é resolvido a partir do cadastro do tomador (nome, e-mail e telefone do perfil PF ou PJ).

Parâmetros de query (listagem)

Parâmetro de query

Pré-cadastro do tomador

Quando o borrower-lookup retorna found: false, o credor pré-cadastra o tomador antes de criar o contrato. O pré-cadastro não cria credencial: sem usuário no provedor de identidade, sem token de ativação e sem e-mail. Ele registra o cliente e o caso de onboarding, para que a jornada do tomador já comece com os dados preenchidos.

Troca de documento depois do pré-cadastro

O tomador pode corrigir o próprio documento durante o onboarding, com duas condições: o e-mail da sessão precisa ser o mesmo que o credor informou no pré-cadastro, e não pode existir caso de compliance aprovado nem para o documento antigo nem para o novo. Fora disso a alteração é recusada com 409.

Jornada do tomador

Contrato criado pelo credor nao nasce com jornada de credito (cotacao + rascunho). No primeiro acesso do tomador ela e materializada a partir dos numeros do proprio contrato — nada e recalculado por politica, porque as condicoes foram acordadas com o credor. Dai em diante o contrato segue os mesmos passos de uma simulacao: aceite, identificacao, garantia e CCB.

Aceite e avanco de etapa

O aceite continua sendo POST /contracts/v1/{id}/accept. Depois dele, o avanco de etapa da jornada e feito por POST /simulation/v1/contracts/{simulationId}/stage.

Enquanto o contrato do credor nao estiver aceito, o avanco de etapa e recusado com 409 contract_not_accepted — a regra vive no backend, entao vale igual para tela e API.

Numeros fiscais na jornada do credor

Na cotacao criada a partir do contrato do credor, iofAmount fica em zero e o CET so e preenchido quando o credor informou o campo cet. Nenhum numero fiscal e inferido.

Efeitos colaterais

• Criação: publica o evento de webhook collateral.created para o tomador (ver Guia de Webhooks).
• Atualização do saldo devedor: dispara recálculo assíncrono do LTV da garantia; conforme o resultado, os webhooks collateral.ltv_alert ou collateral.liquidated podem ser emitidos.
• Envio / aceite: geram e ativam a sessão de assinatura do documento de garantia; o andamento aparece em signings[].signingDocument.