Asset Creation — CCB

Endpoint to insert a CCB (Cédula de Crédito Bancário — Bank Credit Note) asset into an assignment batch. Each asset represents a credit operation that will be assigned to the fund. The same contract applies to structured_cci.

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.

Attention

The external_id field of the credit operation 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": "ccb",
    "total_purchase_value": 1351.66,
    "premiums": [
      {
        "premium_type": "spread",
        "total_value": 13.38
      }
    ],
    "credit_operation": {
      "contract": {
        "number": "0008309052/NBF",
        "disbursement_date": "2023-07-06",
        "issue_date": "2023-07-06",
        "signature_date": "2023-07-06",
        "issue_value": 1338.28
      },
      "amortization_type": "sac",
      "borrower": {
        "name": "Empresa Exemplo Ltda",
        "document_number": "11.222.333/0001-81",
        "person_type": "legal_person",
        "email": "financeiro@empresaexemplo.com.br",
        "address": {
          "street": "Pátio de Teixeira",
          "number": "1",
          "neighborhood": "Estrela do Oriente",
          "city": "Rondônia",
          "postal_code": "01012-030",
          "uf": "RO",
          "country": "BRA"
        },
        "phone": {
          "area_code": "11",
          "number": "936360268"
        },
        "legal_person": {
          "activity_code": "11.11-1-11"
        }
      },
      "delay": {
        "fine": {
          "fine_type": "percentage",
          "percentage_value": 0.0
        },
        "interest": {
          "method": "compound",
          "pre_fixed": {
            "monthly_rate": 0.0,
            "calendar_base": "calendar_360"
          }
        }
      },
      "principal_value": 1338.28,
      "interest_rate_type": "pre_fixed",
      "external_id": "ccf6f331-d55f-46c0-a32f-fb909884dbb2",
      "originator_document_number": "22.333.444/0001-81",
      "pre_fixed": {
        "calendar_base": "calendar_365",
        "monthly_rate": 0.018
      },
      "installments": [
        {
          "maturity_date": "2023-10-01",
          "installment_number": 1,
          "face_value": 689.33
        },
        {
          "maturity_date": "2024-10-01",
          "installment_number": 2,
          "face_value": 482.53
        },
        {
          "maturity_date": "2025-10-01",
          "installment_number": 3,
          "face_value": 300.36
        },
        {
          "maturity_date": "2026-10-01",
          "installment_number": 4,
          "face_value": 162.77
        },
        {
          "maturity_date": "2027-10-01",
          "installment_number": 5,
          "face_value": 81.39
        },
        {
          "maturity_date": "2028-10-01",
          "installment_number": 6,
          "face_value": 40.69
        }
      ],
      "modality_code": "0202",
      "consignee": {
        "consignee_type": "inss",
        "name": "Consignee name",
        "document_number": "33.444.555/0001-81"
      },
      "collaterals": [
        {
          "collateral_type": "social_security",
          "benefit_number": "0000000000",
          "benefit_type": "benefit_type",
          "status": "reserved"
        }
      ]
    }
}

Body attributes

Field	Type	Required	Description
asset_type	string	required	Asset type. For CCB, provide ccb.
total_purchase_value	number	required	Total purchase value of the asset — effectively how much the assignee will pay. Up to 2 decimal places.
premiums	array	optional	List of premiums involved in the sale. See premiums attributes.
deductions	array	optional	List of discounts involved in the sale. See deductions attributes.
credit_operation	object	required	Credit operation data. See credit_operation attributes.

Premiums and discounts are part of the value check

At insertion, QI Tech calculates the present value of the installments and compares it with the asset purchase value: total_purchase_value − sum of premiums + sum of deductions. Small differences are automatically recorded as an adjustment (math_adjustment); above that, the insertion returns TRC100014.

premiums attributes

Field	Type	Required	Description
premium_type	string	required	Premium type: spread, math_adjustment, banker_fee, transaction_fee or originator_fee.
total_value	number	required	Total premium value. Minimum 0.01. Up to 2 decimal places.

deductions attributes

Field	Type	Required	Description
deduction_type	string	required	Discount type: bad_debt_discount or math_adjustment.
total_value	number	required	Total discount value. Minimum 0.01. Up to 2 decimal places.

credit_operation 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	Formatted CPF or CNPJ (000.000.000-00 or 00.000.000/0000-00) of the originator that enabled the operation. It must be registered with QI Tech; otherwise, it returns TRC000019.
principal_value	number	required	Total outstanding principal of the operation. Up to 8 decimal places.
contract	object	required	Contract data. See contract attributes.
borrower	object	required	Drawee/debtor data. See borrower attributes.
amortization_type	string	required	Amortization type used in the calculation.
interest_rate_type	string	required	Interest type of the operation.
pre_fixed	object	conditional	Calculation data for the fixed-rate part. Required when interest_rate_type is pre_fixed. See pre_fixed attributes.
post_fixed	object	conditional	Calculation data for the floating-rate part. Required when interest_rate_type is post_fixed. See post_fixed attributes.
installments	array	required	List of the operation installments. See installments attributes.
delay	object	required	Late fine and interest data. See delay attributes.
modality_code	string	optional	4-digit code that specifies the category or type of financial operation associated with the asset. When omitted, the one in the assignment configuration applies.
b3_code	string	optional	Asset code at B3. Up to 50 characters. Only accepted when the assignment configuration uses registry_transfer, deferred_registry or external_registry registration; in the others, it returns TRC000188.
b3_self_code	string	optional	Asset's own code at B3. Up to 50 characters. Same rule as b3_code.
consignee	object	optional	Consignee entity data. See consignee attributes.
collaterals	array	optional	List of collaterals associated with the operation. See collaterals attributes.

amortization_type enumerators:

Value	Description
sac	SAC amortization.
price	Price amortization.
price_days	Price amortization with interest calculated by calendar days.

interest_rate_type enumerators:

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

contract attributes

Field	Type	Required	Description
number	string	required	Contract number. Maximum of 50 characters.
disbursement_date	string	required	Disbursement date in the YYYY-MM-DD format.
issue_date	string	required	Issue date in the YYYY-MM-DD format.
signature_date	string	optional	Contract signature date in the YYYY-MM-DD format.
issue_value	number	required	Contract issue value. Up to 2 decimal places.

borrower attributes

Field	Type	Required	Description
name	string	required	Drawee name. Maximum of 255 characters.
document_number	string	required	Drawee CPF or CNPJ.
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. The CPF in document_number has its check digit verified. 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
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, in uppercase (e.g., SP).
complement	string	optional	Complement. Maximum of 255 characters.
postal_code	string	required	ZIP code (CEP) in the 00000-000 format. Required whenever the address object is provided.
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.
international_dial_code	string	optional	International dialing code (DDI). Up to 3 characters.

natural_person attributes

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

gender enumerators:

Value	Description
male	Male.
female	Female.

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. See representatives attributes.

representatives attributes

Field	Type	Required	Description
name	string	required	Representative name. Maximum of 255 characters.
document_number	string	required	Representative CPF or CNPJ.
email	string	required	Representative e-mail. Maximum of 255 characters.
phone	object	required	Phone. Same structure as phone attributes.
address	object	required	Address. Same structure as address attributes.
person_type	string	optional	Person type (natural_person or legal_person).
representative_type	string	optional	Representative type. Maximum of 50 characters.

pre_fixed attributes

Field	Type	Required	Description
calendar_base	string	required	Calculation base used.
monthly_rate	number	required	Monthly contract rate, as a decimal fraction between 0 and 1. For 1%, provide 0.01. Up to 8 decimal places.
nominal_monthly_rate	number	optional	Nominal monthly contract rate, in the same format as monthly_rate.

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.

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 operation: di, selic or ipca.
rate	number	required	Rate applied on the indexer. For 100% of DI, provide 1.
lag	object	required	Index lag: reference (daily or monthly) and amount (quantity). To use the index from two months before, provide {"reference": "monthly", "amount": 2}.

installments attributes

Field	Type	Required	Description
maturity_date	string	required	Installment maturity date in the YYYY-MM-DD format.
installment_number	integer	required	Installment number.
face_value	number	required	Installment face value. 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	Installment identifier in your system.

delay attributes

Field	Type	Required	Description
fine	object	required	Late fine data. See fine attributes. With no fine, send fine_type percentage with percentage_value 0.
interest	object	required	Late interest data. See interest attributes. With no late interest, send monthly_rate 0.

fine attributes

Field	Type	Required	Description
fine_type	string	required	Fine type.
percentage_value	number	conditional	Fine value when fine_type is percentage. From 0 to 1, representing 0% to 100%. Up to 2 decimal places.
amount	number	conditional	Fixed fine value when fine_type is fixed. Up to 2 decimal places.

fine_type enumerators:

Value	Description
percentage	Percentage fine on the installment value.
fixed	Fixed fine value.

interest attributes

Field	Type	Required	Description
method	string	required	Late interest method.
pre_fixed	object	required	Late interest rate: calendar_base and monthly_rate or daily_rate. Does not accept nominal_monthly_rate. See late interest pre_fixed attributes.

method enumerators:

Value	Description
compound	Compound late interest.
simple	Simple late interest.
pre_fixed	Fixed-rate late interest.

consignee attributes

Field	Type	Required	Description
name	string	optional	Consignee entity name. Maximum of 255 characters.
document_number	string	required	Consignee entity CPF or CNPJ.
consignee_type	string	required	Consignee type.

consignee_type enumerators:

Value	Description
public	Public consignee.
private	Private consignee.
inss	INSS consignee.

collaterals attributes

Field	Type	Required	Description
collateral_type	string	required	Collateral type.

How to build collaterals

collaterals is a list and each item represents one collateral. The collateral_type determines which fields that item accepts — the fields of one type are not accepted in another. Any property outside the set of the given type is refused with QIT000001.

collateral_type enumerators:

Value	Description
fgts	FGTS collateral. Include the fields of FGTS collateral attributes.
social_security	INSS collateral. Include the fields of INSS collateral attributes.
home_equity	Real estate collateral. Include the fields of Real estate collateral attributes.
vehicle	Vehicle collateral. Include the fields of Vehicle collateral attributes.

FGTS collateral attributes

Field	Type	Required	Description
protocol_number	string	required	Protocol number.
status	string	required	Collateral status.

INSS collateral attributes

Field	Type	Required	Description
benefit_number	string	required	Benefit number.
benefit_type	string	required	Benefit type.
status	string	required	Collateral status.

Real estate collateral attributes

Field	Type	Required	Description
enterprise_name	string	required	Development name.
registration_number	string	required	Property registration number.
enterprise_document_number	string	optional	CPF or CNPJ associated with the development.
collateral_properties	array	required	List of the property's units. See collateral_properties attributes.

collateral_properties attributes

Field	Type	Required	Description
address	object	required	Property address. Same structure as address attributes.
total_collateral_value	number	required	Property value. Up to 8 decimal places.

Vehicle collateral attributes

Field	Type	Required	Description
vehicle_loan_value	number	optional	Financed value of the vehicle. Cannot be negative.
vehicle_total_market_value	number	optional	Total market value of the vehicle. Cannot be negative.
vehicle_identification	object	required	Vehicle identification. See vehicle_identification attributes.

Vehicle collateral example

{
  "collateral_type": "vehicle",
  "vehicle_loan_value": 30000.00,
  "vehicle_total_market_value": 55000.00,
  "vehicle_identification": {
    "brand": "Toyota",
    "model": "Corolla XEi 2.0",
    "manufacturing_year": 2022,
    "chassis_number": "9BRBLWHEXK0123456",
    "license_plate": "ABC1D23",
    "renavam": "12345678901"
  }
}

vehicle_identification attributes

Field	Type	Required	Description
brand	string	optional	Vehicle brand.
model	string	required	Vehicle model.
manufacturing_year	integer	required	Vehicle manufacturing year. Minimum 1900.
chassis_number	string	required	Vehicle chassis number.
license_plate	string	optional	Vehicle license plate.
renavam	string	optional	Vehicle RENAVAM code.

Response

STATUS

201

Response Body

{
    "asset_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "external_id": "ccf6f331-d55f-46c0-a32f-fb909884dbb2",
    "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 credit_operation.
status	string	Initial asset status. It always returns pending_eligibility, indicating that the asset was inserted and is awaiting eligibility analysis.

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.
404	TRC000015	The asset_type does not exist.
400	TRC000025	The asset_type differs from the asset type of the assignment configuration.
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. Despite the title (Originator bond not found), the error does not refer to the link with the configuration.
400	TRC000188	b3_code or b3_self_code sent in a configuration whose registration type does not accept them.
409	TRC000054	An asset with that external_id already exists in this batch.
400	TRC100014	The present value of the installment flow does not match the purchase value (total_purchase_value, premiums and discounts).
400	TRC100004 / TRC100005	Installments without sequential numbering or out of ascending maturity order.
400	TRC100009	issue_value lower than the operation principal.
409	TRC100017	The fund cannot buy overdue assets.

The TRC1000xx codes come from the asset's financial validation, performed at insertion. The error body follows the format below:

{
  "title": "Already Exist This External Id",
  "description": "Already exist an asset with this External Id and asset_key->41d6ff41-1dac-4df7-9e50-d15210ec57f3",
  "translation": "Ja existe um ativo com esse External Id e asset_key->41d6ff41-1dac-4df7-9e50-d15210ec57f3",
  "code": "TRC000054"
}

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:

1. Document submission — submit the required documentation for each asset approved in eligibility.
2. Close asset insertion — signal that all assets have been inserted so the batch proceeds to the eligibility analysis.