Issuances - Integralization

---

Integralization

Using the following endpoint, it is possible to initiate integralization on an issuance.

Request

ENDPOINT

/trade_security/fund_class/FUND_CLASS_KEY/integralization

METHOD

POST

Request Body

{
 "security_external_id": "a23c006c-befd-40e0-bc3d-fbd2dfbbea5d",
 "bookkeeper_document_number": "00.000.000/0000-00",
 "security_key": "272a394a-e3d0-4484-b00e-e18a4e22bb5e",
 "unit_price": 2.00,
 "number_of_units": 100.00,
 "external_id": "90b679c0-2674-4cad-917a-5c786b0bf992",
 "integralization_date": "2025-05-27",
 "pricing_type": "yield_curve",
 "payment": {
   "target_account": {
    "account_branch": "0001",
    "account_digit": "0",
    "account_number": "12345",
    "financial_institution_code": "329",
    "financial_institution_ispb": "32402502"
   }
  }
}

Definitions

Purchase Operation

Field	Type	Description	Required
security_external_id	string	External identifier of the asset	Yes*
bookkeeper_document_number	string	Bookkeeper's CNPJ number	Yes*
security_key	string	Internal asset key	Yes*
unit_price	number	Unit price in integralization	Yes
number_of_units	number	Number of units purchased	Yes
external_id	string	External identifier of the purchase operation	Yes
integralization_date	string	Integralization date	Yes
pricing_type	string	Pricing of the asset in the portfolio: yield_curve or mark_to_market.	Yes
payment	dict	Payment object for settlement	Yes

Important ( * )

The structured asset identification can be done in two ways:

1. By providing the security_key field (internal key); or
2. By providing both the security_external_id and bookkeeper_document_number fields.

At least one of the identification methods must be present in the payload. If both are present, the internal key takes priority.

Payment

Field	Type	Description	Required
target_account	object	Bank account object for settlement	Yes

Bank account

Field	Type	Description	Required
account_branch	string	Bank account branch	Yes
account_digit	string	Account verification digit	Yes
account_number	string	Bank account number	Yes
financial_institution_code	string	Financial institution code	Yes
financial_institution_ispb	string	Financial institution ISPB code	No

Response

STATUS

201

Response Body

{
 "integralization_key": "1568b67b-088e-43be-938b-0f817b805f7a",
 "external_id": "90b679c0-2674-4cad-917a-5c786b0bf992",
 "status": "pending_administrator_approval"
}

Errors

Status	Code	When it happens
400	QIT000001	Invalid request body: the field that failed is in description.

Authentication, permission and host errors: see API errors.