Asset Creation — Installment Contract

Endpoint to insert an Installment Contract asset into an assignment batch. Each asset represents a contract with a flow of installments — the whole contract is assigned to the fund in a single request, with all its installments.

Available on

Profile	Host	Required permission
Manager	`manager-api`	Write
Consultant	`consultant-api`	Batches
Assignor	`assignor-api`	Write

Base URL for each host: Environments (Hosts).

Where am I in the flow?

This is step 2 of the assignment flow. Before this, you must have created the batch. After inserting the assets, submit the required documents and close the insertion.

One asset, several installments

Unlike the Discounted Contract — where each installment is an independent asset — in the installment contract the asset is the contract, and the installments are its payment flow. The installments array must contain all the contract installments being assigned.

Attention

The contract external_id field identifies the asset within the batch and must not be confused with the batch external_id.

Request

ENDPOINT

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

METHOD

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

Body attributes

Field	Type	Required	Description
`asset_type`	string	required	Asset type. For an installment contract, provide `contract`.
`total_purchase_value`	number	required	Total purchase value of the asset — effectively how much the assignee will pay for the whole contract. Up to 2 decimal places.
`contract`	object	required	Contract data. See `contract` attributes.

Premiums and deductions do not apply

Do not send premiums or deductions for an installment contract: they are not recorded for this asset type. The acquisition value of the asset is the total_purchase_value provided.

`contract` attributes

Field	Type	Required	Description
`external_id`	string	required	Unique identification key of this asset in the partner's system. Maximum of 50 characters.
`originator_document_number`	string	required	CPF or CNPJ of the originator that enabled the operation, in the `000.000.000-00` or `00.000.000/0000-00` format. The originator must be registered with QI Tech with this document; otherwise, the insertion returns `TRC000019`.
`contract_number`	string	required	Contract number. Maximum of 50 characters. Sent exactly as provided, without normalization.
`borrower`	object	required	Data of the contract's drawee/debtor. See `borrower` attributes.
`interest_rate_type`	string	required	Contract interest type.
`installments`	array	required	List of the contract installments. It must have at least one installment. See `installments` attributes.
`issue_date`	string	optional	Contract issue date in the `YYYY-MM-DD` format.
`calendar_base`	string	optional	Day-count base of the contract. When omitted, `workdays` is assumed.
`pre_fixed`	object	conditional	Fixed-rate data. Required when `interest_rate_type` is `pre_fixed`. See `pre_fixed` attributes.
`post_fixed`	object	conditional	Floating-rate data. Required when `interest_rate_type` is `post_fixed`. See `post_fixed` attributes.
`contract_data`	object	optional	Free-form object for additional contract information. It is stored and returned in queries and webhooks, without affecting the calculations.

interest_rate_type enumerators:

Value	Description
`pre_fixed`	For fixed-rate contracts. Provide the `pre_fixed` object.
`post_fixed`	For floating-rate contracts. Provide the `post_fixed` object.

calendar_base enumerators:

Value	Description
`workdays`	Calculation base in business days (252).
`calendar_365`	Calculation base of 365 days.
`calendar_360`	Calculation base of 360 days.

`installments` attributes

Field	Type	Required	Description
`installment_number`	integer	required	Installment number, starting at 1. See the sequence rule below.
`maturity_date`	string	required	Installment maturity date in the `YYYY-MM-DD` format.
`face_value`	number	required	Installment face value — how much the drawee pays at maturity. Greater than zero and up to 8 decimal places.
`principal_value`	number	optional	Expected principal to be amortized on the maturity date. Up to 8 decimal places.
`external_id`	string	optional	Identification key of the installment in the partner's system. Maximum of 50 characters.

Installment sequence

With the installments ordered by maturity_date, the installment_number values must form the sequence 1, 2, 3, … with no repetitions and no gaps. Out-of-order numbering returns the TRC000174 error.

`pre_fixed` attributes

Field	Type	Required	Description
`calendar_base`	string	required	Day-count base used for the rate. Same enumerators as `calendar_base`.
`monthly_rate`	number	required	Monthly contract rate, as a decimal fraction between 0 and 1. For 1.5% per month, provide `0.015`. Up to 8 decimal places.

`post_fixed` attributes

Field	Type	Required	Description
`calendar_base`	string	required	Day-count base of the adjustment. Same enumerators as `calendar_base`.
`indexer`	string	required	Index that adjusts the contract.
`rate`	number	required	Rate applied on the indexer. For 100% of DI, provide `1`.
`lag`	object	required	Lag between the index date and the adjustment date. See `lag` attributes.

indexer enumerators:

Value	Description
`di`	DI rate, calculated by B3.
`selic`	Selic rate.
`ipca`	IPCA.

`lag` attributes

Field	Type	Required	Description
`reference`	string	required	Lag unit: `daily` (days) or `monthly` (months).
`amount`	number	required	Lag amount. To use the index from two months before, provide `2` with `reference` equal to `monthly`.

`borrower` attributes

Field	Type	Required	Description
`name`	string	required	Drawee name. Maximum of 255 characters.
`document_number`	string	required	Formatted CPF or CNPJ of the drawee.
`person_type`	string	required	Person type.
`email`	string	optional	Drawee e-mail. Maximum of 255 characters.
`address`	object	optional	Drawee address. See `address` attributes.
`phone`	object	optional	Drawee phone. See `phone` attributes.

person_type enumerators:

Value	Description
`natural_person`	Natural person. When provided, include the `natural_person` object inside `borrower`. See `natural_person` attributes.
`legal_person`	Legal entity. When provided, include the `legal_person` object inside `borrower`. See `legal_person` attributes.

`address` attributes

Field	Type	Required	Description
`postal_code`	string	required	ZIP code (CEP). 9 characters, in the `00000-000` format. Required whenever the `address` object is provided.
`street`	string	optional	Street. If you do not have all the information, send it compiled in this field. Maximum of 255 characters.
`number`	string	optional	Address number. Maximum of 40 characters.
`neighborhood`	string	optional	Neighborhood. Maximum of 255 characters.
`city`	string	optional	City. Maximum of 255 characters.
`uf`	string	optional	State abbreviation. 2 characters.
`complement`	string	optional	Complement. Maximum of 255 characters.
`country`	string	optional	Country in ISO 3166-1 alpha-3 format. 3 characters.

`phone` attributes

Field	Type	Required	Description
`area_code`	string	required	Area code (DDD). 2 digits.
`number`	string	required	Phone number. 8 or 9 digits.

`natural_person` attributes

Field	Type	Required	Description
`birthdate`	string	optional	Date of birth in the `YYYY-MM-DD` format.
`gender`	string	optional	Gender: `male` or `female`.
`mother_name`	string	optional	Mother's name. Maximum of 255 characters.

`legal_person` attributes

Field	Type	Required	Description
`foundation_date`	string	optional	Foundation date in the `YYYY-MM-DD` format.
`activity_code`	string	optional	Activity code (CNAE) in the `11.11-1-11` format.
`annual_revenues`	integer	optional	Annual revenue in cents.
`representatives`	array	optional	List of legal representatives.

Response

STATUS

201

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

Response attributes

Field	Type	Description
`asset_key`	string	Unique asset identifier generated by QI Tech (UUID).
`external_id`	string	The same external key provided in the `external_id` field of `contract`.
`status`	string	Initial asset status. It always returns `pending_eligibility`, indicating that the asset was inserted and is awaiting eligibility analysis.

Values calculated by QI Tech

When the asset is inserted, QI Tech calculates — and starts returning in queries and webhooks — the purchase internal rate of return (purchase_irr), the contract duration and the purchase_value of each installment — the share of total_purchase_value allocated to each maturity. These fields must not be sent in the request.

Errors

Status	Code	When it happens
400	`QIT000001`	The request body does not follow the expected format: missing required field, invalid type or format. The `description` points to the field.
404	`TRC000018`	There is no batch with that `assignment_external_id` in this assignment configuration.
400	`TRC000025`	The `asset_type` differs from the asset type of the assignment configuration.
400	`TRC000084`	The `contract` object was sent with an `asset_type` other than `contract` (for example, `financing_contract` or `debt_acknowledgment`, which are not assigned through this flow).
400	`TRC000174`	With the installments ordered by `maturity_date`, the `installment_number` values do not form the sequence `1, 2, 3, …`.
400	`TRC000022`	The batch no longer accepts assets: the insertion has already been closed. To add more, reopen the batch.
400	`TRC000009`	Invalid CPF or CNPJ in `originator_document_number` or in the `document_number` of a natural person drawee.
404	`TRC000019`	There is no originator registered with the `originator_document_number` provided. Check that the document is formatted exactly as in the registration. Despite the title (Originator bond not found), the error does not refer to the link with the configuration.
409	`TRC000054`	An asset with that `external_id` already exists in this batch.
400	`TRC1000xx`	The asset's financial validation refused the flow. Example: `TRC100014`, present value of the installments different from `total_purchase_value`.

The error body follows the format below:

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

In case of error, resend the request. A duplicate (TRC000054) means the resource already exists: query it instead of recreating it, through the asset query endpoint. More in Retry and duplicates.

Authentication, permission and host errors: see API Errors.

Next steps

After inserting the asset, the flow continues with:

Document submission — submit, with document_type equal to contract, the PDF of this asset's installment contract (the contract with the debtor, not the assignment contract). One file per asset.
Close asset insertion — signal that all assets have been inserted so the batch proceeds to the eligibility analysis.

To assign installment contracts in volume, without one request per asset, use File-Based Assignment.

Request​

Body attributes​

contract attributes​

installments attributes​

pre_fixed attributes​

post_fixed attributes​

lag attributes​

borrower attributes​

address attributes​

phone attributes​

natural_person attributes​

legal_person attributes​

Response​

Response attributes​

Errors​

Next steps​