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.

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 os documentos exigidos 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 deve ser único para cada ativo 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": "53.020.654/0001-43",
        "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": "Jove de Souza",
            "document_number": "593.607.530-33",
            "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

Os campos premiums e deductions não são utilizados em cessão de contrato parcelado. O valor de aquisição do ativo é sempre 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 formatado do originador/consultor que viabilizou a operação. Precisa estar cadastrado e vinculado à configuração de cessão.
`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.

Possíveis erros

STATUS

400

Parcelas fora de sequência

Ordenando as parcelas pela data de vencimento, os installment_number não formam a sequência 1, 2, 3, …. Verifique se há número repetido, salto na numeração ou parcela com vencimento fora da ordem.

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

STATUS

400

Tipo de ativo incompatível com o lote

O lote foi configurado para receber um tipo de ativo diferente do informado. Cada configuração de cessão aceita apenas um tipo de ativo específico. Verifique a configuração de cessão utilizada.

{
  "title": "Invalid asset type configuration",
  "description": "This assignment can not receive this asset type: contract",
  "translation": "Esse lote não pode receber esse tipo de ativo: contract",
  "code": "TRC000025"
}

STATUS

400

Payload incompatível com o tipo de ativo

O objeto contract só é aceito para o tipo de ativo contract. Outros tipos de contrato — como financing_contract e debt_acknowledgment — não são cedidos por este fluxo.

{
  "title": "Invalid assignment date.",
  "description": "The provided asset_type does not match the specific information passed.",
  "translation": "o asset_type fornecido não coincide com as informações especificas passadas",
  "code": "TRC000084"
}

STATUS

404

Lote não encontrado

O assignment_external_id informado na URL não corresponde a nenhum lote existente nesta configuração de cessão. Verifique se o identificador está correto.

{
  "title": "Assignment not found",
  "description": "Assignment not found",
  "translation": "Lote não encontrado",
  "code": "TRC000018"
}

STATUS

400

Lote fechado para inserção

O lote já foi encerrado para inserção de novos ativos. Após o encerramento, não é possível adicionar mais ativos. Caso precise, reabra o lote antes de inserir novos ativos.

{
  "title": "Assignment is closed",
  "description": "Assignment is closed to insert new assets",
  "translation": "Lote esta fechado para inserir novos ativos",
  "code": "TRC000022"
}

STATUS

400

Número de documento inválido

Um dos números de documento informados (CPF ou CNPJ) é inválido. Verifique os campos originator_document_number e borrower.document_number.

{
  "title": "Invalid Document number",
  "description": "Given '000.000.000-00' document number is invalid.",
  "translation": "O numero de document '000.000.000-00' fornecido não é valido.",
  "code": "TRC000009"
}

STATUS

400

External ID duplicado

Já existe um ativo cadastrado com o external_id informado. Cada ativo deve ter um identificador único. Gere um novo external_id e tente novamente.

{
  "title": "Already Exist This External Id",
  "description": "Already exist an asset with this External Id",
  "translation": "Ja existe um ativo com esse External Id",
  "code": "TRC000054"
}

Próximos passos

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

Envio dos documentos — envie o contrato assinado, com document_type igual a contract.
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​

Possíveis erros​

Próximos passos​

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

Possíveis erros

Próximos passos