Inserção de contrato no lote

Insere um contrato num lote de contratos estruturados. Cada chamada leva um contrato com todas as parcelas. O contrato é precificado na hora pela carteira do fundo: se o preço não fecha com as parcelas, a chamada é recusada e nada é gravado.

Disponível em

Perfil	Host	Permissão exigida
Gestora	`manager-api`	Escrita
Consultoria	`consultant-api`	Operar contratos
Cedente	`assignor-api`	Escrita

URL base de cada host: Ambientes (Hosts).

Onde estou no fluxo?

Este é o 2º passo. Antes, crie o lote. Depois de inserir todos os contratos, encerre a inserção.

Request

ENDPOINT

/trade_contract/fund_class/{fund_class_key}/assignment/{assignment_key}/contract

MÉTODO

POST

O tipo do contrato vem do lote: o body é o mesmo para os três tipos, e cada tipo tem regras próprias, descritas depois dos atributos.

Request Body — contrato de financiamento
{
    "external_id": "FIN-2026-000147-01",
    "contract_number": "CF-000147",
    "total_value": 100000.00,
    "purchase_order_value": 95000.00,
    "has_assignor_coobligation": true,
    "borrower_document_number": "11.444.777/0001-61",
    "borrower_name": "Comercial Exemplo Ltda",
    "issue_date": "2026-11-09",
    "originator_document_number": "11.222.333/0001-81",
    "interest_rate_type": "pre_fixed",
    "pre_fixed": {
        "monthly_rate": 0.015,
        "calendar_base": "workdays"
    },
    "installments": [
        { "external_id": "FIN-2026-000147-01-1", "installment_number": 1, "face_value": 26000.00, "maturity_date": "2026-12-10" },
        { "external_id": "FIN-2026-000147-01-2", "installment_number": 2, "face_value": 26000.00, "maturity_date": "2027-01-11" },
        { "external_id": "FIN-2026-000147-01-3", "installment_number": 3, "face_value": 26000.00, "maturity_date": "2027-02-10" },
        { "external_id": "FIN-2026-000147-01-4", "installment_number": 4, "face_value": 26000.00, "maturity_date": "2027-03-10" }
    ],
    "contract_data": {
        "purchase_order_number": "PC-88213"
    }
}

Atributos do body

Campo	Tipo	Obrigatoriedade	Descrição
`external_id`	string	obrigatório	Identificador do contrato no seu sistema, 1 a 50 caracteres. Único entre os contratos do cedente (`TRC000047`).
`contract_number`	string	opcional	Número do contrato, até 50 caracteres. Aparece nos documentos e na carteira.
`total_value`	number	obrigatório	Valor do contrato, maior que zero. É também o preço pago pelo fundo, quando `purchase_order_value` não é enviado.
`purchase_order_value`	number	opcional	Preço que o fundo paga pelo contrato, quando diferente de `total_value`. No contrato de financiamento, o valor do pedido de compra financiado.
`expense_value`	number	opcional	Despesa da operação, maior ou igual a zero. Usada na confissão de dívida.
`has_assignor_coobligation`	boolean	opcional	Se o cedente responde solidariamente pelo pagamento. Padrão `false`.
`borrower_document_number`	string	obrigatório	CPF ou CNPJ do devedor, 11 a 18 caracteres.
`borrower_name`	string	opcional	Nome do devedor, até 255 caracteres. Aparece nos documentos.
`issue_date`	string	opcional	Data de emissão do contrato, em `YYYY-MM-DD`.
`originator_document_number`	string	obrigatório	CPF ou CNPJ do originador, cadastrado (`TRC000058`).
`interest_rate_type`	string	obrigatório	`pre_fixed` ou `post_fixed`. Envie o objeto de mesmo nome.
`pre_fixed`	object	condicional	Taxa prefixada. Veja Atributos de `pre_fixed`.
`post_fixed`	object	condicional	Taxa pós-fixada. Veja Atributos de `post_fixed`.
`installments`	array	obrigatório	Parcelas do contrato, ao menos uma. Veja Atributos de `installments`.
`substituted_assets`	array	condicional	Ativos que a confissão de dívida substitui. Obrigatório na confissão. Veja Confissão de dívida.
`contract_data`	object	opcional	Dados livres do contrato, guardados com ele na carteira e disponíveis para os modelos de documento da configuração.

Campos fora desta lista são recusados com QIT000001.

Atributos de `pre_fixed`

Campo	Tipo	Obrigatoriedade	Descrição
`monthly_rate`	number	obrigatório	Taxa mensal em decimal, de 0 a 1: `0.015` é 1,5% ao mês.
`calendar_base`	string	obrigatório	Base de dias: `workdays` (dias úteis), `calendar_360` ou `calendar_365`.
`accrual_calendar_base`	string	opcional	Base de dias do acúmulo, quando diferente da `calendar_base`. Mesmos valores.

Atributos de `post_fixed`

Campo	Tipo	Obrigatoriedade	Descrição
`indexer`	string	obrigatório	Indexador: `di`, `selic` ou `ipca`.
`rate`	number	obrigatório	Taxa sobre o indexador, maior ou igual a zero.
`calendar_base`	string	obrigatório	`workdays`, `calendar_360` ou `calendar_365`.
`lag`	object	obrigatório	Defasagem do indexador: `reference` (`monthly` ou `daily`) e `amount` (número de períodos, maior ou igual a zero).

Atributos de `installments`

Campo	Tipo	Obrigatoriedade	Descrição
`installment_number`	integer	obrigatório	Número da parcela, a partir de 1.
`face_value`	number	obrigatório	Valor da parcela, maior que zero.
`maturity_date`	string	obrigatório	Vencimento da parcela, em `YYYY-MM-DD`.
`external_id`	string	opcional	Identificador da parcela no seu sistema. Não pode repetir dentro do contrato (`TRC000047`).
`principal_value`	number	opcional	Parte de principal da parcela, maior ou igual a zero.

Regras por tipo

Contrato de financiamento

O lote foi criado com disbursement: é esse valor que o cedente recebe depois da assinatura.
purchase_order_value não pode ser maior que total_value. A regra é conferida quando os documentos são gerados ou enviados (TRC000018), não na inserção.
O lastro costuma ser o contrato de financiamento e o pedido de compra; os documentos exigidos vêm da configuração.

Confissão de dívida

A confissão substitui ativos do mesmo devedor que o fundo já tem. Cada ativo substituído é liquidado quando a confissão entra na carteira, e a confissão passa a ser o ativo do fundo.

Request Body — confissão de dívida
{
    "external_id": "CONF-2026-000032-01",
    "contract_number": "CD-000032",
    "total_value": 30000.00,
    "expense_value": 500.00,
    "borrower_document_number": "11.444.777/0001-61",
    "borrower_name": "Comercial Exemplo Ltda",
    "issue_date": "2026-11-09",
    "originator_document_number": "11.222.333/0001-81",
    "interest_rate_type": "pre_fixed",
    "pre_fixed": {
        "monthly_rate": 0.02,
        "calendar_base": "workdays"
    },
    "installments": [
        { "installment_number": 1, "face_value": 10600.00, "maturity_date": "2026-12-10" },
        { "installment_number": 2, "face_value": 10600.00, "maturity_date": "2027-01-11" },
        { "installment_number": 3, "face_value": 10600.00, "maturity_date": "2027-02-10" }
    ],
    "substituted_assets": [
        {
            "asset_external_id": "CCB-2025-000881",
            "asset_key": "5e2d7c1a-3b4f-4a6e-9c8d-7f1e2a3b4c5d",
            "asset_type": "ccb",
            "settlement_value": 18000.00
        },
        {
            "asset_external_id": "DUP-2026-004410",
            "asset_key": "c1b2a3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
            "asset_type": "duplicata_mercantil",
            "settlement_value": 12500.00
        }
    ]
}

Ao menos um ativo substituído por contrato (TRC000010).
A conta fecha: a soma dos settlement_value é igual a total_value mais expense_value (TRC000035). No exemplo, 18.000 + 12.500 = 30.000 + 500.
Mesmo devedor: cada ativo substituído é do mesmo borrower_document_number da confissão (TRC000068).
Ativo vivo e do cedente: cada ativo precisa estar ativo na carteira do fundo, cedido pelo cedente do lote (TRC000053). Busque asset_key e asset_external_id em Ativos que a confissão pode substituir.
Uma vez por lote: o mesmo ativo não pode estar em dois contratos do lote (TRC000051).
Sem dinheiro novo: o lote não tem desembolso. Na entrada da confissão na carteira, cada ativo substituído é liquidado pelo settlement_value, descontada a parte proporcional da despesa, e a confissão recebe a provisão para perdas definida na configuração.

Atributos de `substituted_assets`

Campo	Tipo	Obrigatoriedade	Descrição
`asset_external_id`	string	obrigatório	`external_id` do ativo substituído na carteira, até 50 caracteres.
`asset_key`	string	obrigatório	Chave do ativo substituído (UUID).
`asset_type`	string	obrigatório	Tipo do ativo substituído: `duplicata_mercantil`, `duplicata_servicos`, `ccb`, `contract`, `financing_contract` ou `debt_acknowledgment`.
`settlement_value`	number	obrigatório	Valor pelo qual o ativo é liquidado, maior ou igual a zero.
`substituted_asset_data`	object	opcional	Dados livres do ativo substituído, para os documentos.

Contrato

Sem regras além das comuns. Se o lote foi criado com disbursement, o cedente recebe esse valor depois da assinatura, como no contrato de financiamento.

Response

STATUS

201

Response Body
{
    "contract_key": "e7d6c5b4-a3f2-4e1d-9c0b-8a7f6e5d4c3b",
    "external_id": "FIN-2026-000147-01",
    "status": "pending_wallet_inclusion"
}

Campo	Tipo	Descrição
`contract_key`	string	Chave do contrato (UUID).
`external_id`	string	O `external_id` enviado.
`status`	string	`pending_wallet_inclusion`: o contrato foi aceito e entra na carteira quando o lote chegar ao fim do fluxo.

O preço por parcela, a taxa de aquisição e o prazo calculados aparecem na consulta do lote.

Erros

Status	Código	Quando acontece
400	`QIT000001`	O body não segue o formato: campo obrigatório ausente, tipo ou tamanho inválido, ou campo não aceito.
404	`TRC000011`	Não existe lote com essa `assignment_key` neste fundo.
409	`TRC000070`	O lote não aceita mais contratos: a inserção já foi encerrada.
409	`TRC000047`	Já existe um contrato com esse `external_id` para o cedente, ou duas parcelas com o mesmo `external_id`.
400	`TRC000022`	CPF ou CNPJ inválido no devedor ou no originador.
404	`TRC000058`	O originador não está cadastrado.
422	`TRC000045`	A carteira recusou o contrato na precificação. A `description` traz o motivo.
409	`TRC000044`	O preço calculado pela carteira para as parcelas não fecha com `purchase_order_value` (ou `total_value`).
400	`TRC000010`	Confissão de dívida sem `substituted_assets`.
400	`TRC000035`	Confissão: a soma dos `settlement_value` é diferente de `total_value` mais `expense_value`.
400	`TRC000051`	Confissão: o mesmo ativo substituído aparece em dois contratos do lote.
409	`TRC000053`	Confissão: o ativo substituído não está ativo na carteira para este cedente.
400	`TRC000068`	Confissão: o ativo substituído é de outro devedor.
403	`QIT000004` / `QIT000005` / `QIT000008`	A integração não tem acesso a este lote.

Em caso de erro de rede, reenvie com o mesmo external_id: um TRC000047 indica que o contrato já entrou, e ele aparece na consulta do lote.

Request​

Atributos do body​

Atributos de pre_fixed​

Atributos de post_fixed​

Atributos de installments​

Regras por tipo​

Contrato de financiamento​

Confissão de dívida​

Atributos de substituted_assets​

Contrato​

Response​

Erros​