Asset Creation — CCB

Endpoint to insert a CCB (Bank Credit Note) asset into an assignment batch. Each asset represents a credit operation that will be assigned to the fund.

Where am I in the flow?

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

Attention

The external_id field of the credit operation must be unique for each asset and must not be confused with the external_id of the batch.

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": "QI CTVM",
        "document_number": "19.845.976/0001-93",
        "person_type": "legal_person",
        "email": "qidtvm@qitech.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": "75.723.105/0001-78",
      "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
        }
      ],
      "modality_code": "0202",
      "consignee": {
        "consignee_type": "inss",
        "name": "Consignee name",
        "document_number": "11.620.231/3105-71"
      },
      "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, use ccb.
total_purchase_value	number	required	Total asset purchase value — the effective amount the assignee will pay. Up to 2 decimal places.
premiums	array	optional	List of premiums involved in the sale. Informational only — not used in calculations.
credit_operation	object	required	Credit operation data. See credit_operation attributes.

premiums attributes

Field	Type	Required	Description
premium_type	string	required	Premium type.
total_value	number	required	Total premium value. Up to 2 decimal places.

premium_type enumerators:

Value	Description
spread	Spread linked to origination and credit issuance.

credit_operation attributes

Field	Type	Required	Description
external_id	string	required	Unique identifier for this asset in the partner's system. Maximum 50 characters.
originator_document_number	string	required	Formatted CPF or CNPJ of the originator/consultant who facilitated the operation.
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	Borrower/debtor data. See borrower attributes.
amortization_type	string	required	Amortization type used in calculation.
interest_rate_type	string	required	Operation interest rate type.
pre_fixed	object	required	Pre-fixed rate calculation data. See pre_fixed attributes.
installments	array	required	List of operation installments. See installments attributes.
delay	object	optional	Late fine and interest data. See delay attributes.
modality_code	string	optional	4-digit code specifying the category or type of financial operation associated with the asset.
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 type.
price	Price amortization type.

interest_rate_type enumerators:

Value	Description
pre_fixed	For pre-fixed rate operations.
post_fixed	For post-fixed rate operations.

contract attributes

Field	Type	Required	Description
number	string	required	Contract number. Maximum 50 characters.
disbursement_date	string	required	Disbursement date in YYYY-MM-DD format.
issue_date	string	required	Issue date in YYYY-MM-DD format.
signature_date	string	optional	Contract signature date in 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	Borrower name. Maximum 255 characters.
document_number	string	required	Borrower CPF or CNPJ.
person_type	string	required	Person type.
email	string	optional	Borrower email. Maximum 255 characters.
address	object	required	Borrower address. See address attributes.
phone	object	optional	Borrower phone. See phone attributes.

person_type enumerators:

Value	Description
natural_person	Individual. When set, include the natural_person object inside borrower. See natural_person attributes.
legal_person	Legal entity. When set, include the legal_person object inside borrower. See legal_person attributes.

address attributes

Field	Type	Required	Description
street	string	required	Street address. If not all details are available, send the compiled information in this field. Maximum 255 characters.
number	string	optional	Address number. Maximum 40 characters.
neighborhood	string	optional	Neighborhood. Maximum 255 characters.
city	string	optional	City. Maximum 255 characters.
uf	string	optional	State abbreviation. 2 characters.
complement	string	optional	Complement. Maximum 255 characters.
postal_code	string	required	Postal code (CEP). 9 characters (with hyphen).
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. Up to 9 digits.

natural_person attributes

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

gender enumerators:

Value	Description
male	Male.
female	Female.

legal_person attributes

Field	Type	Required	Description
foundation_date	string	optional	Foundation date in YYYY-MM-DD format.
activity_code	string	required	Activity code in 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 255 characters.
document_number	string	required	Representative CPF or CNPJ.
email	string	optional	Representative email. Maximum 255 characters.
phone	object	optional	Phone. Same structure as phone attributes.
address	object	optional	Address. Same structure as address attributes.
person_type	string	required	Person type (natural_person or legal_person).
representative_type	string	optional	Representative type. Maximum 50 characters.

pre_fixed attributes

Field	Type	Required	Description
calendar_base	string	required	Calculation base used.
monthly_rate	number	required	Monthly contract rate. For 1%, provide 0.01. Up to 8 decimal places.

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
maturity_date	string	required	Installment maturity date in YYYY-MM-DD format.
installment_number	integer	required	Installment number.
face_value	number	optional	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.

delay attributes

Field	Type	Required	Description
fine	object	optional	Late fine data. See fine attributes.
interest	object	optional	Late interest data. See interest attributes.

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 amount when fine_type is fixed. Up to 2 decimal places.

fine_type enumerators:

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

interest attributes

Field	Type	Required	Description
method	string	required	Late interest method.
pre_fixed	object	required	Pre-fixed rate data. Same structure as pre_fixed attributes.

method enumerators:

Value	Description
compound	Compound late interest.
simple	Simple late interest.

consignee attributes

Field	Type	Required	Description
name	string	required	Consignee entity name. Maximum 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 (Social Security) consignee.

collaterals attributes

Field	Type	Required	Description
collateral_type	string	required	Collateral type.

collateral_type enumerators:

Value	Description
fgts	FGTS (severance fund) collateral. Include FGTS collateral attributes.
social_security	INSS (social security) collateral. Include INSS collateral attributes.
home_equity	Real estate collateral. Include real estate 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	Enterprise name.
registration_number	string	required	Property registration number.
enterprise_document_number	string	optional	CPF or CNPJ associated with the enterprise.
collateral_properties	array	required	List of property attributes. 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.

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. Always returns pending_eligibility, indicating the asset was inserted and awaits eligibility analysis.

Possible errors

STATUS

404

Batch not found

The assignment_external_id provided in the URL does not match any existing batch in this assignment configuration. Verify that the identifier is correct.

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

STATUS

404

Asset type does not exist

The value provided in the asset_type field is not a valid type. Verify that the type is correct (e.g., ccb, duplicata_mercantil, discounted_contract).

{
  "title": "Asset type does not exist",
  "description": "Asset type 'invalid_asset_type' does not exist",
  "translation": "Tipo do ativo 'invalid_asset_type' nao existe",
  "code": "TRC000015"
}

STATUS

400

Asset type incompatible with batch

The batch was configured to receive a different asset type than the one provided. Each assignment configuration accepts only one specific asset type. Verify the assignment configuration being used.

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

STATUS

400

Batch closed for insertion

The batch has already been closed for new asset insertion. After closure, no more assets can be added. If needed, reopen the batch before inserting new assets.

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

STATUS

400

Invalid document number

One of the document numbers provided (CPF or CNPJ) is invalid. Verify the document_number, originator_document_number, and other document fields in the request body.

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

Duplicate external_id

An asset with the provided external_id already exists. Each asset must have a unique identifier. Generate a new external_id and try again.

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

Next steps

After inserting the asset, the flow continues with:

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