Consulta de lotes de contratos

Os contratos estruturados não enviam webhooks: o andamento de um lote é acompanhado por estas consultas. A consulta do lote traz tudo o que você precisa para saber o que falta: o status, o histórico, os documentos esperados e os que já existem, e as pendências abertas.

Disponível em

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

URL base de cada host: Ambientes (Hosts).

Consulta do lote

ENDPOINT

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

MÉTODO

GET

Response Body — 200

{
    "assignment_key": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "external_id": "FIN-2026-000147",
    "asset_type": "financing_contract",
    "operation_type": "financing_contract",
    "status": "pending_asset_documents",
    "contract_configuration_key": "4b0a7d0e-2f4c-4f7b-9a43-6f1c2f0f5c11",
    "assignment_number": "147/2026",
    "purchase_date": "2026-11-09",
    "assignment_total_value": 100000.00,
    "assignment_irr": 0.0152,
    "average_duration": 62,
    "disbursement": {
        "amount": 95000.00,
        "account": {
            "account_key": "a3f4b5c6-d7e8-4f90-a1b2-c3d4e5f6a7b8",
            "account_branch": "0001",
            "account_number": "123456",
            "account_digit": "7",
            "financial_institution_code": "341"
        }
    },
    "payment_type": "pix",
    "assignor": {
        "document_number": "11.222.333/0001-81",
        "name": "Cedente Exemplo Ltda"
    },
    "fund_class": {
        "fund_class_key": "d1c7c5a2-8a55-4bb8-9d0a-3f2a8e1c9b77",
        "name": "FIDC Exemplo",
        "document_number": "11.444.777/0001-61"
    },
    "signature_dispatched": false,
    "created_at": "2026-11-09T10:12:31",
    "contracts": [
        {
            "contract_key": "e7d6c5b4-a3f2-4e1d-9c0b-8a7f6e5d4c3b",
            "external_id": "FIN-2026-000147-01",
            "asset_type": "financing_contract",
            "status": "pending_wallet_inclusion",
            "contract_number": "CF-000147",
            "total_value": 100000.00,
            "purchase_order_value": 95000.00,
            "originator_document_number": "11.222.333/0001-81",
            "borrower_document_number": "11.444.777/0001-61",
            "borrower_name": "Comercial Exemplo Ltda",
            "issue_date": "2026-11-09",
            "asset_key": null,
            "installments": [
                { "installment_number": 1, "face_value": 26000.00, "maturity_date": "2026-12-10" }
            ],
            "substituted_assets": []
        }
    ],
    "expected_documents": [
        { "document_type": "financing_contract", "validation_type": "internal_signature", "name": "Contrato de financiamento", "per_contract": true, "source": "generated" },
        { "document_type": "purchase_order", "validation_type": "external_upload", "name": "Pedido de compra", "per_contract": true, "source": "upload" }
    ],
    "documents": [
        {
            "document_key": "3c2b1a09-8f7e-4d6c-b5a4-938271605f4e",
            "document_type": "purchase_order",
            "status": "pending_validation",
            "validation_type": "external_upload",
            "contract_key": "e7d6c5b4-a3f2-4e1d-9c0b-8a7f6e5d4c3b",
            "asset_documents_key": "b8a7c6d5-e4f3-4a2b-9c1d-0e8f7a6b5c4d",
            "created_at": "2026-11-09T10:20:02"
        }
    ],
    "signature_groups": [],
    "annotations": [],
    "status_events": [
        { "status": "pending_assets_insertion", "event_datetime": "2026-11-09T10:12:31", "denial_reason": null },
        { "status": "pending_documents", "event_datetime": "2026-11-09T10:15:07", "denial_reason": null },
        { "status": "pending_asset_documents", "event_datetime": "2026-11-09T10:18:44", "denial_reason": null }
    ]
}

Campo	Tipo	Descrição
`status`	string	Status atual. Veja Status do lote.
`assignment_total_value`	number	Soma dos contratos do lote.
`assignment_irr`	number	Taxa de aquisição do lote, calculada no encerramento da inserção.
`average_duration`	number	Prazo médio do lote, em dias, calculado no encerramento.
`disbursement`	object	Valor e conta do desembolso ao cedente, quando houver.
`signature_dispatched`	boolean	Se a assinatura já foi disparada.
`contracts`	array	Contratos do lote. O `asset_key` é preenchido quando o contrato entra na carteira.
`expected_documents`	array	Documentos que a configuração exige. Veja O que a configuração exige.
`documents`	array	Documentos que já existem no lote, com o status de cada um.
`signature_groups`	array	Para cada documento a assinar, os papéis que assinam (`required_roles`).
`annotations`	array	Pendências da análise, com `status` `opened` ou `answered`, a mensagem e a resposta.
`status_events`	array	Histórico de status. Em `rejected`, `denial_reason` diz o motivo: `risk_analysis`, `manual`, `asset_documents`, `signature`, `cnab_inconsistency` ou `wallet_inclusion`.

Listagem de lotes

Lista os lotes do fundo.

ENDPOINT

/trade_contract/fund_class/{fund_class_key}/assignment

MÉTODO

GET

Parâmetro	Tipo	Padrão	Descrição
`status`	string	—	Um ou mais status, separados por vírgula: `pending_signature,pending_annotation`.
`operation_type`	string	—	`financing_contract`, `debt_acknowledgment` ou `contract`.
`external_id`	string	—	`external_id` do lote.
`page`	integer	`0`	Página, a partir de 0.
`limit`	integer	`50`	Itens por página, até 200.

Response Body — 200
{
    "data": [
        {
            "assignment_key": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
            "external_id": "FIN-2026-000147",
            "asset_type": "financing_contract",
            "status": "pending_asset_documents",
            "assignment_total_value": 100000.00
        }
    ],
    "page": 0,
    "limit": 50,
    "is_last_page": true
}

Cada item segue o formato da consulta do lote.

A gestora também lista os lotes de todos os seus fundos, com o filtro adicional fund_class_key (repetível):

ENDPOINT

/trade_contract/assignment

MÉTODO

GET

Resumo dos lotes

Quantidade e valor dos lotes por status, no fundo. Útil para saber quantos lotes esperam uma ação sua.

ENDPOINT

/trade_contract/fund_class/{fund_class_key}/assignment_summary

MÉTODO

GET

Response Body — 200
{
    "data": [
        { "status": "pending_annotation", "count": 1, "total_value": 30000.00 },
        { "status": "active", "count": 12, "total_value": 1250000.00 }
    ],
    "total_count": 13,
    "total_value": 1280000.00,
    "awaiting_signature_dispatch": 0
}

awaiting_signature_dispatch conta os lotes aprovados cuja assinatura ainda não foi disparada. A gestora tem o mesmo resumo para todos os fundos em /trade_contract/assignment_summary.

Erros

Status	Código	Quando acontece
400	`QIT000010`	Parâmetro de consulta inválido.
404	`TRC000001`	Não existe fundo com essa `fund_class_key`.
404	`TRC000011`	Não existe lote com essa `assignment_key` neste fundo.
403	`QIT000004` / `QIT000005` / `QIT000008`	A integração não tem acesso a este fundo ou lote.

Consulta do lote​

Listagem de lotes​

Resumo dos lotes​

Erros​

Consulta do lote

Listagem de lotes

Resumo dos lotes

Erros