Skip to main content

Credit Rights Assignment Manual

This manual describes the step-by-step process of assigning credit rights to the funds administered by QI DTVM, the business rules of the product and the points to watch for a faster integration. The contract of each call (fields, responses and errors) is on the reference page linked in each step.

Prerequisites​

  1. An assignment contract in place and the corresponding product activated — see Assignor Onboarding.
  2. Access through the manager, the consultant or the assignor of the contract. What each profile can call is in the Available on block of each reference page.
  3. The assignee fund key (fund_class_key) and the assignment configuration key (assignment_configuration_key), which make up the path of every call:
/trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}

The fund's assignment configurations can be queried in Assignment Configuration Listing.

State flow​

The assignment pipeline has two entities with related state machines: the batch (assignment) and the assets (asset) within it.

Assignment batch status flow, from pending_assets_insertion to completed, with the exits to denied and discarded

Batch — blue = status with webhook · dashed = status without webhook · green = assignment completed · red = denial or discard.

Asset status flow, from pending_eligibility to completed, with the exits to denied, registry_denied and discarded

Asset — blue = intermediate status · green = asset added to the portfolio · red = denial or discard.

The full list of statuses is in Batch status enumerators and Asset status enumerators.

Integration summary​

  1. Batch creation.
  2. Asset insertion.
  3. Document upload.
  4. Insertion closing.
  5. Asset and batch eligibility (automatic, with webhooks).
  6. Consultant and/or manager approval, when the configuration requires it.
  7. Assignment Term signature, payment and portfolio inclusion (automatic, with webhooks).

1. Batch creation​

The batch is created with POST .../assignment — see Assignment Batch Creation. It only requires an identifier generated in your system, the external_id, used in the other calls and in the webhooks.

The batch external_id is unique across the whole platform: a second creation with the same value is refused. On error, resend the request: if the batch already exists, query it.

2. Asset insertion​

Each asset is inserted with POST .../assignment/{assignment_external_id}/asset, one request per asset. The body depends on the asset type: CCB, duplicata, CT-e, discounted contract and installment contract. You can also assign the whole batch by file.

Asset value and purchase value​

To understand the value validation, use this notation:

  • [A] — asset purchase value (total_purchase_value, at the root of the object): how much the fund pays for the asset;
  • [B] — sum of the premiums (total_value of each item in premiums);
  • [C] — sum of the discounts (total_value of each item in deductions);
  • [D] — asset value, calculated as [D] = [A] − [B] + [C].

The asset value [D] is checked against the informed installment flow. Discrepancies are refused at insertion, with the codes listed in the Errors section of each asset type's page.

Rules that apply to all types​

  • Configuration asset type. Each assignment configuration accepts a single asset type; it is not possible to mix, for example, CCBs and duplicatas in the same batch.
  • Open batch. Assets can only be added while the batch is in pending_assets_insertion.
  • Asset external_id. It is unique within the batch: a second asset with the same external_id in the same batch is refused. On error, resend the request.
  • Originator. The originator_document_number must belong to an originator already registered with QI Tech, with the same formatting as the registration; otherwise, the insertion returns TRC000019.

Credit operations​

Credit operations (CCB) have an outstanding principal and an interest rate. Installments must come in ascending order of maturity (maturity_date) and with sequential installment_number. Depending on the interest type, provide the fixed-rate and/or floating-rate object. The details are in CCB Insertion.

3. Document upload​

The documents of each asset are sent with POST .../asset/{asset_external_id}/document, one per request, in Base64 — see Asset Document Insertion. The upload can be done right after the asset is inserted, without waiting for the pending_documentation webhook.

The required documents depend on the product and are in the required_documents and after_assignment_required_documents fields of the assignment configuration. The asset only reaches pre_approved when all required documents have been uploaded and validated.

4. Insertion closing​

When you no longer want to insert assets, close insertion with PUT .../assignment/{assignment_external_id} and assignment_status = completed_assets_insertion — see Close Asset Insertion.

There is no need to wait for the webhook of every asset. The batch only moves on to eligibility when all assets have completed their analysis.

5. Asset and batch eligibility​

Each asset is analyzed against the fund's eligibility rules and the result arrives by asset webhook, identified by the asset external_id. If approved, the asset continues through the pipeline; if denied, it goes to denied and is not part of the batch.

With all assets analyzed, the batch as a whole goes through eligibility: even with all assets approved, the batch may put the fund out of compliance. The result arrives by batch webhook, identified by the batch external_id. If denied, the batch goes to denied.

6. Approval​

If the assignment configuration requires manual approval, the batch stays in pending_consultant_approval and/or pending_manager_approval until the decision, made with PUT .../assignment/{assignment_external_id} — see Batch Approval — or in the Manager Portal. To remove assets before approving, see Removing Assets from the Batch.

With automatic approval, the batch proceeds without any action.

7. Assignment Term, payment and portfolio inclusion​

After approval, the assets are registered and formalized, and the Assignment Term is generated and sent for signature (pending_assignment_term_signature) — retrieve it in Assignment Documents.

Once the term is signed, the assignor is paid (pending_payment) into the batch's disbursement account. The amount is the sum of the total_purchase_value of the assets not denied. Once the payment is confirmed, the assets are added to the portfolio (pending_assets_wallet_inclusion) and, at the end, the batch becomes completed: from then on all assets are in the fund's inventory.

Substitution batches​

In batches created under a repurchase configuration, also insert the assets the assignor will repurchase, with POST .../assignment/{assignment_external_id}/repurchased_asset — see Asset Insertion for Repurchase. The value of the repurchased assets is deducted from the payment.