Criação de Ativo — Contrato Parcelado

Endpoint para inserir um ativo do tipo Contrato Parcelado em um lote de cessão. Cada ativo representa um contrato com um fluxo de parcelas — o contrato inteiro é cedido ao fundo em uma única requisição, com todas as suas parcelas.

Disponível em

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

URL base de cada host: Ambientes (Hosts).

Onde estou no fluxo?

Este é o 2º passo do fluxo de cessão. Antes, você deve ter criado o lote. Após inserir os ativos, envie o lastro exigido de cada um e encerre a inserção.

Um ativo, várias parcelas

Diferente do Contrato Descontado — em que cada parcela é um ativo independente — no contrato parcelado o ativo é o contrato, e as parcelas são o fluxo de pagamentos dele. O array installments precisa conter todas as parcelas do contrato que estão sendo cedidas.

Atenção

O campo external_id do contrato identifica o ativo dentro do lote e não deve ser confundido com o external_id do lote.

Request

ENDPOINT

/trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset

MÉTODO

POST

Request Body
{
    "asset_type": "contract",
    "total_purchase_value": 900.00,
    "contract": {
        "external_id": "80187a08-ea7d-44b2-b65c-131f1318e904",
        "originator_document_number": "22.333.444/0001-81",
        "contract_number": "1144927986/XXX",
        "issue_date": "2026-11-01",
        "interest_rate_type": "pre_fixed",
        "calendar_base": "calendar_365",
        "pre_fixed": {
            "calendar_base": "calendar_365",
            "monthly_rate": 0.015
        },
        "borrower": {
            "name": "José de Souza",
            "document_number": "969.698.790-03",
            "person_type": "natural_person",
            "email": "jose.souza@yopmail.com",
            "address": {
                "street": "Rua Gilberto Sabino",
                "number": "215",
                "neighborhood": "Pinheiros",
                "city": "São Paulo",
                "postal_code": "05245-020",
                "uf": "SP",
                "country": "BRA"
            },
            "phone": {
                "area_code": "11",
                "number": "26260447"
            },
            "natural_person": {
                "birthdate": "1999-01-01",
                "gender": "male",
                "mother_name": "Maria de Souza"
            }
        },
        "installments": [
            {
                "installment_number": 1,
                "maturity_date": "2026-12-25",
                "face_value": 500.46,
                "principal_value": 450.00,
                "external_id": "parcela-1"
            },
            {
                "installment_number": 2,
                "maturity_date": "2027-01-25",
                "face_value": 500.46,
                "principal_value": 450.00,
                "external_id": "parcela-2"
            }
        ],
        "contract_data": {
            "cost_center": "SP-01"
        }
    }
}

Atributos do body

Campo	Tipo	Obrigatoriedade	Descrição
`asset_type`	string	obrigatório	Tipo do ativo. Para contrato parcelado, informar `contract`.
`total_purchase_value`	number	obrigatório	Valor total da compra do ativo — efetivamente quanto o cessionário vai pagar pelo contrato inteiro. Até 2 casas decimais.
`contract`	object	obrigatório	Dados do contrato. Veja Atributos de `contract`.

Ágios e deduções não se aplicam

Não envie premiums nem deductions em contrato parcelado: eles não são registrados para este tipo de ativo. O valor de aquisição do ativo é o total_purchase_value informado.

Atributos de `contract`

Campo	Tipo	Obrigatoriedade	Descrição
`external_id`	string	obrigatório	Chave única de identificação deste ativo no sistema do parceiro. Máximo de 50 caracteres.
`originator_document_number`	string	obrigatório	CPF ou CNPJ do originador que viabilizou a operação, no formato `000.000.000-00` ou `00.000.000/0000-00`. O originador precisa estar cadastrado na QI Tech com esse documento; caso contrário, a inserção devolve `TRC000019`.
`contract_number`	string	obrigatório	Número do contrato. Máximo de 50 caracteres. Enviado exatamente como informado, sem normalização.
`borrower`	object	obrigatório	Dados do sacado/devedor do contrato. Veja Atributos de `borrower`.
`interest_rate_type`	string	obrigatório	Tipo de juros do contrato.
`installments`	array	obrigatório	Lista das parcelas do contrato. Precisa ter ao menos uma parcela. Veja Atributos de `installments`.
`issue_date`	string	opcional	Data de emissão do contrato no formato `YYYY-MM-DD`.
`calendar_base`	string	opcional	Base de contagem de dias do contrato. Quando omitido, é assumido `workdays`.
`pre_fixed`	object	condicional	Dados da parte pré-fixada. Obrigatório quando `interest_rate_type` for `pre_fixed`. Veja Atributos de `pre_fixed`.
`post_fixed`	object	condicional	Dados da parte pós-fixada. Obrigatório quando `interest_rate_type` for `post_fixed`. Veja Atributos de `post_fixed`.
`contract_data`	object	opcional	Objeto livre para informações adicionais do contrato. É armazenado e devolvido nas consultas e webhooks, sem interferir nos cálculos.

Enumeradores de interest_rate_type:

Valor	Descrição
`pre_fixed`	Para contratos pré-fixados. Informe o objeto `pre_fixed`.
`post_fixed`	Para contratos pós-fixados. Informe o objeto `post_fixed`.

Enumeradores de calendar_base:

Valor	Descrição
`workdays`	Base de cálculo em dias úteis (252).
`calendar_365`	Base de cálculo em 365 dias.
`calendar_360`	Base de cálculo em 360 dias.

Atributos de `installments`

Campo	Tipo	Obrigatoriedade	Descrição
`installment_number`	integer	obrigatório	Número da parcela, começando em 1. Veja a regra de sequência abaixo.
`maturity_date`	string	obrigatório	Data de vencimento da parcela no formato `YYYY-MM-DD`.
`face_value`	number	obrigatório	Valor de face da parcela — quanto o sacado paga no vencimento. Maior que zero e até 8 casas decimais.
`principal_value`	number	opcional	Principal esperado a ser amortizado na data de vencimento. Até 8 casas decimais.
`external_id`	string	opcional	Chave de identificação da parcela no sistema do parceiro. Máximo de 50 caracteres.

Sequência das parcelas

Ordenando as parcelas pela maturity_date, os installment_number precisam formar a sequência 1, 2, 3, … sem repetições e sem saltos. Uma numeração fora de ordem devolve o erro TRC000174.

Atributos de `pre_fixed`

Campo	Tipo	Obrigatoriedade	Descrição
`calendar_base`	string	obrigatório	Base de contagem de dias utilizada na taxa. Mesmos enumeradores de `calendar_base`.
`monthly_rate`	number	obrigatório	Taxa mensal do contrato, em fração decimal entre 0 e 1. Para 1,5% ao mês, informar `0.015`. Até 8 casas decimais.

Atributos de `post_fixed`

Campo	Tipo	Obrigatoriedade	Descrição
`calendar_base`	string	obrigatório	Base de contagem de dias da correção. Mesmos enumeradores de `calendar_base`.
`indexer`	string	obrigatório	Índice que corrige o contrato.
`rate`	number	obrigatório	Taxa aplicada sobre o indexador. Para 100% do DI, informar `1`.
`lag`	object	obrigatório	Defasagem entre a data do índice e a data da correção. Veja Atributos de `lag`.

Enumeradores de indexer:

Valor	Descrição
`di`	Taxa DI, apurada pela B3.
`selic`	Taxa Selic.
`ipca`	IPCA.

Atributos de `lag`

Campo	Tipo	Obrigatoriedade	Descrição
`reference`	string	obrigatório	Unidade da defasagem: `daily` (dias) ou `monthly` (meses).
`amount`	number	obrigatório	Quantidade de defasagem. Para usar o índice de dois meses antes, informar `2` com `reference` igual a `monthly`.

Atributos de `borrower`

Campo	Tipo	Obrigatoriedade	Descrição
`name`	string	obrigatório	Nome do sacado. Máximo de 255 caracteres.
`document_number`	string	obrigatório	CPF ou CNPJ formatado do sacado.
`person_type`	string	obrigatório	Tipo de pessoa.
`email`	string	opcional	E-mail do sacado. Máximo de 255 caracteres.
`address`	object	opcional	Endereço do sacado. Veja Atributos de `address`.
`phone`	object	opcional	Telefone do sacado. Veja Atributos de `phone`.

Enumeradores de person_type:

Valor	Descrição
`natural_person`	Pessoa Física. Quando informado, inclua o objeto `natural_person` dentro de `borrower`. Veja Atributos de `natural_person`.
`legal_person`	Pessoa Jurídica. Quando informado, inclua o objeto `legal_person` dentro de `borrower`. Veja Atributos de `legal_person`.

Atributos de `address`

Campo	Tipo	Obrigatoriedade	Descrição
`postal_code`	string	obrigatório	CEP. 9 caracteres, no formato `00000-000`. Obrigatório sempre que o objeto `address` for informado.
`street`	string	opcional	Logradouro. Caso não tenha todas as informações, enviar o compilado neste campo. Máximo de 255 caracteres.
`number`	string	opcional	Número do endereço. Máximo de 40 caracteres.
`neighborhood`	string	opcional	Bairro. Máximo de 255 caracteres.
`city`	string	opcional	Cidade. Máximo de 255 caracteres.
`uf`	string	opcional	Sigla do estado. 2 caracteres.
`complement`	string	opcional	Complemento. Máximo de 255 caracteres.
`country`	string	opcional	País no formato ISO 3166-1 alpha-3. 3 caracteres.

Atributos de `phone`

Campo	Tipo	Obrigatoriedade	Descrição
`area_code`	string	obrigatório	Código de área (DDD). 2 dígitos.
`number`	string	obrigatório	Número de telefone. 8 ou 9 dígitos.

Atributos de `natural_person`

Campo	Tipo	Obrigatoriedade	Descrição
`birthdate`	string	opcional	Data de nascimento no formato `YYYY-MM-DD`.
`gender`	string	opcional	Gênero: `male` ou `female`.
`mother_name`	string	opcional	Nome da mãe. Máximo de 255 caracteres.

Atributos de `legal_person`

Campo	Tipo	Obrigatoriedade	Descrição
`foundation_date`	string	opcional	Data de fundação no formato `YYYY-MM-DD`.
`activity_code`	string	opcional	Código de atividade (CNAE) no formato `11.11-1-11`.
`annual_revenues`	integer	opcional	Receita anual em centavos.
`representatives`	array	opcional	Lista de representantes legais.

Response

STATUS

201

Response Body
{
    "asset_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "external_id": "80187a08-ea7d-44b2-b65c-131f1318e904",
    "status": "pending_eligibility"
}

Atributos da resposta

Campo	Tipo	Descrição
`asset_key`	string	Identificador único do ativo gerado pela QI Tech (UUID).
`external_id`	string	A mesma chave externa fornecida no campo `external_id` do `contract`.
`status`	string	Status inicial do ativo. Sempre retorna `pending_eligibility`, indicando que o ativo foi inserido e aguarda análise de elegibilidade.

Valores calculados pela QI Tech

Na inserção do ativo, a QI Tech calcula e passa a devolver nas consultas e nos webhooks a taxa interna de retorno da compra (purchase_irr), a duration do contrato e o purchase_value de cada parcela — a fatia do total_purchase_value alocada a cada vencimento. Esses campos não devem ser enviados no request.

Erros

Status	Código	Quando acontece
400	`QIT000001`	O request body não segue o formato esperado: campo obrigatório ausente, tipo ou formato inválido. A `description` aponta o campo.
404	`TRC000018`	Não existe lote com esse `assignment_external_id` nesta configuração de cessão.
400	`TRC000025`	O `asset_type` é diferente do tipo de ativo da configuração de cessão.
400	`TRC000084`	O objeto `contract` foi enviado com um `asset_type` diferente de `contract` (por exemplo, `financing_contract` ou `debt_acknowledgment`, que não são cedidos por este fluxo).
400	`TRC000174`	Ordenando as parcelas por `maturity_date`, os `installment_number` não formam a sequência `1, 2, 3, …`.
400	`TRC000022`	O lote não aceita mais ativos: a inserção já foi encerrada. Para incluir mais, reabra o lote.
400	`TRC000009`	CPF ou CNPJ inválido em `originator_document_number` ou no `document_number` de um sacado pessoa física.
404	`TRC000019`	Não há originador cadastrado com o `originator_document_number` informado. Confira se o documento está formatado exatamente como no cadastro. Apesar do título (Originator bond not found), o erro não se refere ao vínculo com a configuração.
409	`TRC000054`	Já existe um ativo com esse `external_id` neste lote.
400	`TRC1000xx`	A validação financeira do ativo recusou o fluxo. Exemplo: `TRC100014`, valor presente das parcelas diferente do `total_purchase_value`.

O corpo de erro segue o formato abaixo:

{
  "title": "Contract must have an installment number sequence",
  "description": "Contract 80187a08-ea7d-44b2-b65c-131f1318e904 must have installment numbers as a sequence starting at 1 ordered by maturity date",
  "translation": "O contrato 80187a08-ea7d-44b2-b65c-131f1318e904 deve ter os numeros das parcelas em sequencia iniciando em 1 e ordenados pela data de vencimento",
  "code": "TRC000174"
}

Em caso de erro, reenvie a requisição. Duplicidade (TRC000054) significa que o recurso já existe: consulte-o em vez de recriar, pelo endpoint de consulta de ativo. Mais em Reenvio e duplicidade.

Erros de autenticação, permissão e host: veja Erros da API.

Próximos passos

Após inserir o ativo, o fluxo continua com:

Envio do lastro — envie, com document_type igual a contract, o PDF do contrato parcelado deste ativo (o contrato com o devedor, não o contrato de cessão). Um arquivo por ativo.
Encerramento da inserção — sinalize que todos os ativos foram inseridos para que o lote siga para a análise de elegibilidade.

Para ceder contratos parcelados em volume, sem uma requisição por ativo, use a Cessão por Arquivo.

Request​

Atributos do body​

Atributos de contract​

Atributos de installments​

Atributos de pre_fixed​

Atributos de post_fixed​

Atributos de lag​

Atributos de borrower​

Atributos de address​

Atributos de phone​

Atributos de natural_person​

Atributos de legal_person​

Response​

Atributos da resposta​

Erros​

Próximos passos​