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.

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"
    }
  }
}

Periodicidade das taxas

Cada taxa tem a sua periodicidade, informada de forma independente: interestRateBasis para a taxa de juros e cetBasis para o CET. Ambas aceitam monthly ou yearly e assumem monthly quando omitidas.

• monthly: a taxa vale ao mês e é gravada como veio.
• yearly: a taxa vale ao ano e é convertida para o equivalente mensal composto ((1 + taxa)^(1/12) − 1) antes de ser gravada. Uma taxa de 12.6825 ao ano é gravada como 1 ao mês.

O CET costuma ser divulgado ao ano; nesse caso envie "cetBasis": "yearly".

A parcela é calculada pela tabela Price sobre o saldo devedor, usando a maior entre a taxa de juros e o CET — assim os custos do CET ficam diluídos nas parcelas. Como o saldo devedor cai a cada parcela, o total de juros não corresponde à taxa aplicada sobre o valor inteiro em todos os meses: em 1200 com 1% ao mês em 12x, a parcela é 106,62, o total é 1.279,44 e os juros somam 79,44.

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)

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.