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.