Commercial Notes (NC) Bookkeeping Integration Guide with Auto-Signature

This guide describes all the resources and functionalities that need to be tested by the integration partner in QI Tech's Sandbox environment, before going into production environment for commercial notes (NC) issuance.

This is a personalized version of QI Tech's standard NC integration guide, adapted for the fully automated issuance flow: once the issuer is registered, approved and enabled for auto-signature, every subsequent issuance runs end to end via API with no manual signing step.

Attention

All tests must be mandatorily performed in QI Tech's Sandbox environment. Operations performed in Sandbox environment are fictional financial operations, serving only for API functionality testing.

1. Scope and phasing

The flow is split into six phases. Phases 0 through 4 rely on capabilities already available in the API, including auto-signature enablement (Phase 2), which is now published. Phase 6 is split in two: the funding transfer to the WL settlement account (6.1) uses BaaS endpoints that already exist and can be homologated today; the third-party disbursement to the supplier (6.2) depends on new development.

Legend	Meaning
✅	Available today — can be homologated in Sandbox immediately
🆕	New development — endpoint contract to be published; homologation starts once released
⚙️	Executed by QI Tech (no integrator action, but the integrator must observe the resulting status)
`*`	Mandatory step for homologation sign-off

Sequencing premise

The enablement can only be requested once the issuer registration is approved — and it can, and should, be completed before the first issuance. The adoption agreement is signed in its own envelope, with its own link, independent of any operation: there is no need to create an NC to enable it, and there is no mandatory "first manual issuance". Phase 2 is therefore a one-time gate per issuer, not a per-operation step — completed before the first issuance, every operation for that issuer is signed automatically, including the first.

2. End-to-end flow

3. Phase 0 — Registration and API authentication

Code	Step	Description	Documentation Link	Prerequisites	Status
CAB0001*	Public key exchange	Perform public key exchange with the platform operations team (suporte-dcm@qitech.com.br)	Documentation Link	—	✅
CAB0002*	Call authentication test	After receiving the API key, complete the call authentication tests	Documentation Link Documentation Link	CAB0001	✅
CAB0003*	Webhook configuration	Configure the URL for QI Tech webhook sending	Documentation Link Documentation Link Documentation Link	CAB0001, CAB0002	✅

Attention

Webhook configuration is mandatory in this flow, not optional. Because analysis, approval and signing are automatic, the integrator has no manual checkpoint — webhooks are the only way to observe the operation advancing without polling.

4. Phase 1 — Issuer homologation

Attention

If the client has already performed the integration with QI Tech assignor registrations, it's possible to reuse these registrations, considerably simplifying the homologation in the system.

4.1 Phase 1A — Issuer registered in the QI Tech assignor system

Code	Step	Description	Documentation Link	Prerequisites	Status
CED1001*	Reuse assignor registration	Reuse an existing assignor registration by CNPJ	Documentation Link	CAB0002	✅
CED1002*	List registered issuers	List registered issuers, filtering by CNPJ or name	Documentation Link	CED1001	✅
CED1003*	Issuer details	Retrieve the details of a registered issuer by `issuer_key`	Documentation Link	CED1001	✅

4.2 Phase 1B — Issuer registered through the system

Code	Step	Description	Documentation Link	Prerequisites	Status
CED0001*	Basic issuer registration	Create the issuer with its basic registration data	Documentation Link	CAB0002	✅
CED0002*	Upload / remove issuer documents	Attach and remove documents associated with a registered issuer	Documentation Link Documentation Link	CED0001	✅
CED0003*	Register / remove issuer representatives	Add and remove representatives associated with a registered issuer	Documentation Link Documentation Link	CED0001	✅
CED0004*	Upload / remove representative documents	Attach and remove documents associated with a representative of a registered issuer	Documentation Link Documentation Link	CED0001, CED0003	✅
CED0005*	Register / remove issuer bank account	Add and remove a bank account associated with a registered issuer	Documentation Link Documentation Link	CED0001	✅
CED0006*	Register / remove issuer signer groups	Add and remove signer groups associated with a registered issuer	Documentation Link Documentation Link	CED0001, CED0003	✅
CED0007*	Register / remove issuer contact information	Add and remove contact information associated with a registered issuer	Documentation Link Documentation Link	CED0001	✅
CED0008*	Submit issuer for analysis	Move the issuer to analysis status, sending it into the validation process	Documentation Link	CED0001 → CED0007	✅
CED0009*	Amend issuer registration	Reopen the issuer for editing	Documentation Link	CED0001 → CED0007	✅
CED0010*	List registered issuers	List registered issuers, filtering by CNPJ or name	Documentation Link	CED0001	✅
CED0011*	Issuer details	Retrieve the details of a registered issuer by `issuer_key`	Documentation Link	CED0001	✅

Gate to Phase 2

The signer group registered in CED0006 defines which representative will sign on the issuer's behalf. That same representative is the person who signs the auto-signature adoption agreement in Phase 2 and whose authority the private certificate represents. Register it correctly before submitting the issuer for analysis — a change afterwards requires re-running Phase 2.

5. Phase 2 — Auto-signature enablement ✅

This phase runs once per issuer, right after the issuer registration has been approved, and results in a QI Tech private certificate scoped exclusively to the NC documents of this integration.

The integrator requests the enablement, with a POST that is only accepted once the issuer registration is approved. There is no automatic creation. The client must be enabled for auto-signature — a configuration performed by QI Tech that includes the adoption agreement template.

The request already opens the envelope. Generating the agreement and creating the envelope happen inside the call itself, which responds in pending_signature with the envelope_key — the signature links can be retrieved right after, with no need to wait for a webhook.

What the adoption agreement authorizes. It grants QI Tech a limited mandate to issue and hold an internal private certificate, released in CertifiQI, to be used solely for signing the documents of this NC flow on the issuer's behalf — never for any other document, product or counterparty. It is signed once by the signer group registered on the issuer — each signer gets their own signature link.

When it is signed. The agreement has its own envelope and its own signature link, generated at enablement and independent of any operation. It can be signed as soon as the issuer is approved, before the first issuance — the recommended path, because it brings the issuer to its first operation with auto-signature already active. If Phase 2 has not been completed by the time the operation is created, that operation simply follows the manual QI SIGN fallback, like any issuer in a status other than enabled.

Code	Step	Description	Documentation Link	Prerequisites	Status
ASG0001*	Client enabled for auto-signature	QI Tech enables the client and configures the adoption agreement template. Without it, no issuer of that client gets an auto-signature	Documentation Link	—	⚙️
ASG0002*	Request the enablement	`POST /issuer_management/issuer/{issuer_key}/auto_signature` for an approved issuer. The same call generates the adoption agreement and opens the envelope: it returns the `issuer_auto_signature_key` and the `envelope_key` already in `pending_signature`. Rejected with `ISS0000032` if the issuer is not approved	Documentation Link	ASG0001, CED0011 or CED1003	✅
ASG0003	Webhook — agreement sent for signature	Receive the `issuer_management.auto_signature_status_change` webhook with status `pending_signature`. It confirms what the ASG0002 response already returned, and notifies the tenant's other consumers	Documentation Link	CAB0003, ASG0002	✅
ASG0004*	Retrieve the signature links	`GET .../auto_signature/signers` returns one link per signer, with each signer's individual status. Direct each of the issuer's signers to their own link. The links are independent of any operation — they can be used before the first issuance	Documentation Link	ASG0002	✅
ASG0005*	Webhook — auto-signature enabled	Receive the webhook with status `enabled`, confirming the agreement was signed and the issuer is enabled for automatic signing	Documentation Link	CAB0003, ASG0004	✅
ASG0006*	Query auto-signature status	Query the enablement by `issuer_key` and confirm the transition to `enabled`, along with the event history. No NC may rely on automatic signing before this status is reached	Documentation Link	ASG0002	✅
ASG0007	Private certificate issuance	QI Tech creates the private certificate and releases it in CertifiQI, scoped to this issuer's NC documents. It is manual today (once per issuer, executed by QI Tech); automation is on the roadmap and does not block go-live	—	ASG0005	⚙️
ASG0008	Cancel the auto-signature	Cancel the enablement — required when the signer group changes or at the issuer's request. Requested from QI Tech; there is no public endpoint. After cancellation, issuances revert to the manual flow until a new enablement is requested	—	ASG0006	⚙️

Automatic cancellation

The auto-signature is cancelled automatically when the issuer leaves the approved status — that is, when it moves to reproved, expired or canceled. The enablement has to be redone after the registration is approved again.

5.1 Enablement status machine

Status	Meaning	Signing behaviour of a new NC
no auto-signature	Enablement never requested, or client not enabled	Manual signature (QI SIGN)
`pending_term_generation`	Enablement requested; adoption agreement not yet generated	Manual signature
`pending_signature`	Agreement generated and sent for signature; signer links available	Manual signature — the agreement is signed through its own links, outside the operation
`enabled`	Agreement signed; issuer enabled for automatic signing	Automatic
`reproved`	Agreement envelope rejected, cancelled or expired	Manual signature (QI SIGN)
`canceled`	Enablement cancelled	Manual signature (QI SIGN)

Homologation requirement

The integrator must demonstrate, in Sandbox, that its system reads the enablement status before creating an operation and routes correctly in both directions: automatic signing when enabled, and the QI SIGN fallback (COM0015 / COM0016) in every other status. An integration that assumes enabled will break for every issuer whose Phase 2 has not been completed.

6. Phase 3 — Investor homologation

Attention

If the client operates with fixed funds, those can be registered during setup, which simplifies the integration considerably. For this flow the fixed-fund path is the expected configuration.

6.1 Investors registered during setup — recommended path

Code	Step	Description	Documentation Link	Prerequisites	Status
INV1001*	List registered investors	List registered funds, filtering by CNPJ or name	Documentation Link	CAB0002	✅
INV1002*	Investor details	Retrieve the details of a registered investor by `investor_key`	Documentation Link	CAB0002	✅

6.2 Investors registered through the system — only if fixed funds are not used

Code	Step	Description	Documentation Link	Prerequisites	Status
INV0001*	Basic investor registration	Create the investor with its basic registration data	Documentation Link	CAB0002	✅
INV0002*	Upload / remove investor documents	Attach and remove documents associated with a registered investor	Documentation Link Documentation Link	INV0001	✅
INV0003*	Register / remove investor representatives	Add and remove representatives associated with a registered investor	Documentation Link Documentation Link	INV0001	✅
INV0004*	Upload / remove representative documents	Attach and remove documents associated with a representative of a registered investor	Documentation Link Documentation Link	INV0001, INV0003	✅
INV0005*	Register / remove investor bank account	Add and remove a bank account associated with a registered investor	Documentation Link Documentation Link	INV0001	✅
INV0006*	Register / remove investor signer groups	Add and remove signer groups associated with a registered investor	Documentation Link Documentation Link	INV0001	✅
INV0007*	Register / remove investor contact information	Add and remove contact information associated with a registered investor	Documentation Link Documentation Link	INV0001	✅
INV0008*	Submit investor for analysis	Move the investor to analysis status, sending it into the validation process	Documentation Link	INV0001 → INV0007	✅
INV0009*	Amend investor registration	Reopen the investor for editing	Documentation Link	INV0001 → INV0007	✅
INV0010*	List registered investors	List registered funds, filtering by CNPJ or name	Documentation Link	INV0001	✅
INV0011*	Investor details	Retrieve the details of a registered investor by `investor_key`	Documentation Link	INV0001	✅

7. Phase 4 — NC issuance

Once issuers and investors are registered, commercial notes can be issued. Issuance via API is the core premise of this integration: the screen-based flow does not work at the intended volume.

7.1 Operation creation

Code	Step	Description	Documentation Link	Prerequisites	Status
COM0001*	Simulate financial conditions	Simulate the financial conditions and payment schedule of an operation	Documentation Link	CAB0002	✅
COM0002*	Create NC operation	Create a new commercial note operation from the financial and investor data	Documentation Link	COM0001, CED0011/CED1003, INV1002	✅
COM0003*	Register / remove related parties	Add and remove parties related to an operation	Documentation Link	COM0002	✅
COM0004*	Upload / remove related-party representative documents	Attach and remove documents associated with representatives of related parties	Documentation Link	COM0002, COM0003	✅
COM0005*	Register / remove related-party signer groups	Add and remove signer groups associated with representatives of related parties	Documentation Link	COM0002, COM0003	✅
COM0006	Preview constitutive term	Generate a draft of the Constitutive Term for a given operation from a predefined template	Documentation Link	COM0002	✅
COM0007*	Change constitutive term template	Change the Constitutive Term template used by a given operation	Documentation Link	COM0002	✅
COM0008*	Upload documents	Upload documents associated with an operation. The returned `document_key` can be used, for example, in the collateral system	Documentation Link	COM0002	✅
COM0009*	Register collateral	Add collateral associated with an operation	Documentation Link	COM0002, COM0008	✅
COM0010*	Register / remove related parties of a contract or collateral	Add and remove parties related to a specific contract or collateral of the operation	Documentation Link	COM0002, COM0003	✅
COM0011*	Submit operation for analysis	Move the operation to "under analysis", sending it into the compliance validation process	Documentation Link	COM0002 → COM0009	✅
COM0012*	Submit signed approval minutes	Submit externally signed approval minutes for SA or COP issuers, as a base64 payload analysed and approved	Documentation Link	COM0002	✅
COM0013*	Query operations by filter	Query commercial note operations using optional filters	Documentation Link	COM0002 → COM0009	✅
COM0014*	Query operation by key	Query the full details of a specific operation using its unique key	Documentation Link	COM0002 → COM0009	✅
COM0024*	Declare the third-party beneficiary at creation	Send `third_party_disbursement` in the operation creation body, stating that the released amount will be paid to a supplier instead of the issuer's settlement account. Requires prior enablement	Documentation Link	COM0002	⚙️ 🆕
COM0025*	Change the third-party beneficiary	Replace the third-party disbursement instruction of an operation still in `in_filling` — switching between TED, bank slip and Pix, or correcting the beneficiary data	Documentation Link	COM0002	⚙️ 🆕

Third-party disbursement — feature available on request 🆕

The feature is not enabled by default; request the enablement from QI Tech before integrating. Without it, operation creation is refused with COM000062 and nothing is persisted.

Three mutually exclusive tracks:

TED — payment_method: "ted" with target_account.
Bank slip — payment_method: "bank_slip" with a 47-digit digitable_line, whose last 10 digits (in cents) must be exactly the operation's released_amount.
Pix 🆕 — payment_method: "pix" with pix_key and pix_key_type (cpf, cnpj, phone, email or evp). The key travels unformatted for CPF and CNPJ.

On TED and bank slip the beneficiary is identified by the payment data itself. Because a Pix key does not say who is being paid, the Pix track also requires the beneficiary object 🆕 — the full qualification of the third party, with the same fields as a related party, used to record the payment in the corporate minute. That object is also accepted, optionally, on TED and bank slip.

The beneficiary travels with the operation and is signed together with it. The payment is executed automatically at disbursement — there is no payment endpoint to call (see §9.2).

7.2 Signing — automatic path (issuer with `enabled` auto-signature) 🆕

Code	Step	Description	Documentation Link	Prerequisites	Status
COM0020*	Automatic approval	With auto-signature in `enabled` and the operating terms pre-approved, the operation transitions from analysis to approved without manual intervention. The integrator observes the transition via webhook	Documentation Link (pending publication)	COM0011, ASG0006	⚙️ 🆕
COM0021*	Automatic signing of the constitutive term	QI Tech signs the Constitutive Term on the issuer's behalf using the private certificate released in CertifiQI. No signature link is generated for the issuer	Documentation Link (pending publication)	COM0020	⚙️ 🆕
COM0022*	Webhook — operation signed	Receive the webhook confirming that all signatures of the operation have been completed	Documentation Link	CAB0003, COM0021	🆕
COM0023*	Retrieve signed documents	Retrieve the signed documents of the operation by its unique key, including the signature evidence report	Documentation Link	COM0022	✅
COM0026*	Client acceptance log upload	Attach to the operation, as a base64 payload, the PDF holding the end client's acceptance evidence. Optional upload, accepted only in `in_filling` and only when the issuer has auto signature in `enabled`	Documentation Link	COM0002, ASG0006	⚙️ 🆕

Acceptance log — the evidence of the client's consent 🆕

On the automatic path no signature link is generated for the end client, so their consent is not recorded by the signature envelope. The acceptance log is where that evidence goes: a PDF holding the record of the acceptance, attached to the operation while it is in in_filling.

The upload is optional — issuance does not depend on it and nothing is blocked in its absence. The document is kept as evidence: it does not go into the signature envelope, does not go into the signed documents bundle (COM0023) and does not change the automatic approval (COM0020). The operation starts exposing acceptance_log_document_key on the retrieval by key.

An issuer without auto signature in enabled is refused with COM000077. A new upload replaces the current document; there is no deletion endpoint.

7.3 Signing — manual fallback (QI SIGN)

Required for any issuer whose enablement status is not enabled, including an issuer whose Phase 2 has not been completed yet. There is no mandatory "first manual issuance": if auto-signature is already active when the operation is created, the first issuance is automatic too.

Code	Step	Description	Documentation Link	Prerequisites	Status
COM0015*	Query QI SIGN signature links	Query all signature links of a specific operation via QI SIGN, using its unique key	Documentation Link	COM0002 → COM0009	✅
COM0016*	Query signed contract links	Query all signed documents of a specific operation via QI SIGN, using its unique key	Documentation Link	COM0002 → COM0009	✅

8. Phase 5 — Subscription and settlement

With the operation signed, the subscription bulletin is generated automatically and made available for the investor to sign. Where the investor is also enabled for auto-signature, this step requires no human interaction either.

Code	Step	Description	Documentation Link	Prerequisites	Status
INT0001*	Query settlement process by key	Query the details of a settlement (integralização) process using its unique key	Documentation Link	COM0022	✅
INT0002*	Query subscription	Query an ongoing subscription	Documentation Link	INT0001	✅
INT0003	Register subscription	Register an investor's intention to subscribe a specific number of quotas — useful when a subscription date must be shifted	Documentation Link	INT0001, INT0002	✅
INT0004	Cancel subscription	Cancel a subscription — useful when a subscription date must be shifted	Documentation Link	INT0001, INT0002	✅
INT0005*	Webhook — subscription bulletin signed	Receive the webhook confirming that the subscription bulletin has been signed. This is the trigger the client system uses to command the funding transfer in Phase 6.1 (TFI0002)	Documentation Link	CAB0003, INT0002	🆕

9. Phase 6 — Funding and disbursement 🆕

Phase 6 has two legs. The first (6.1) is triggered by the integrator's own system when it receives the subscription bulletin signature webhook, and moves the funds into the WL settlement account. The second (6.2) pays the supplier out of that account.

9.1 Leg 1 — Transfer to the WL settlement account 🆕

Trigger. The subscription bulletin signed webhook (INT0005) is the event that authorizes the funding transfer. On receiving it, the client system commands a payment in the BaaS API sending a transfer to the WL's settlement (liquidation) account. QI Tech does not initiate this transfer — it is an integrator-side action, and the webhook is its only trigger. Nothing in this leg may be fired before INT0005 arrives: a transfer commanded against an unsigned bulletin has no backing operation.

Because both the origin and the destination are QI Contas, this is an internal transfer (QI Conta → QI Conta), which settles in real time and does not depend on Pix or TED rails.

Code	Step	Description	Documentation Link	Prerequisites	Status
TFI0001*	Query the WL settlement account	Retrieve the WL settlement (liquidation) account that will receive the funds, including its identifiers and balance	Documentation Link	CAB0002	✅
TFI0002*	Command the internal transfer	On receiving INT0005, command the transfer from the origin QI Conta to the WL settlement account. The request must carry the operation's unique key so the credit can be reconciled back to the NC	Documentation Link	INT0005, TFI0001	✅
TFI0003*	Query the transfer	Query the commanded transfer and confirm it settled into the WL settlement account	Documentation Link	TFI0002	✅
TFI0004*	Webhook — transaction settled	Receive the account movement webhook confirming the credit in the WL settlement account. This is the trigger for leg 6.2	Documentation Link	CAB0003, TFI0002	✅
TFI0005	Transfer receipt	Request the transfer receipt for the integrator's own records and audit trail	Documentation Link	TFI0002	✅

Idempotency

The webhook may be delivered more than once. The integrator must key the transfer on the operation so that a redelivered INT0005 does not command a second transfer for the same NC. Reconciliation between the operation key and the credited transaction is the integrator's responsibility.

TFI0002 — Command the internal transfer

ENDPOINT

/account/ACCOUNT_KEY/ted

METHOD

POST

ACCOUNT_KEY is the origin QI Conta being debited. target_account is the WL settlement account — for the internal path its ispb is QI Tech's own (32402502), which is what makes the transfer settle account-to-account instead of going out over the TED rail.

Request Body

{
  "request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
  "target_account": {
    "account_branch": "0001",
    "account_number": "2359934",
    "account_digit": "2",
    "owner_document_number": "09080702000105",
    "owner_name": "WL Settlement Account",
    "ispb": "32402502",
    "account_type": "checking_account"
  },
  "transaction_amount": 150000.00
}

request_control_key is the idempotency key

Derive it deterministically from the NC operation key rather than generating a fresh UUID per attempt. A redelivered INT0005 that produces the same request_control_key is rejected as a duplicate instead of double-paying the settlement account.

Response Body — 201

{
  "request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
  "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "created_at": "2021-10-22T20:30:23.459Z",
  "ted_status": "sent",
  "transaction_amount": 150000.00,
  "fee_amount": 0.0,
  "transaction_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec"
}

TFI0004 — Webhook confirming the credit

The credit in the WL settlement account arrives as an account_transaction webhook with a positive data.amount and source_sub_type = internal_funds_transfer. Match data.transaction_key against the transaction_key returned by TFI0002 to close the loop back to the NC operation.

WEBHOOK_TYPE

account_transaction

Webhook Body

{
    "key": "<ACCOUNT-KEY>",
    "data": {
        "amount": 150000.00,
        "origin": {
            "name": "Origin Account",
            "branch": "0001",
            "document": "32402502000135",
            "account_key": "5d068423-6094-49e4-b15b-7740038295a8",
            "account_digit": "5",
            "account_number": "00002"
        },
        "timestamp": "2022-09-02T21:36:33.446120",
        "destination": {
            "name": "WL Settlement Account",
            "branch": "0001",
            "document": "09080702000105",
            "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
            "account_digit": "2",
            "account_number": "2359934"
        },
        "reference_key": "983b4a28-7de6-4e71-97ef-60fb50c7b013",
        "reference_type": "movement_request",
        "account_balance": 150000.00,
        "source_sub_type": "internal_funds_transfer",
        "transaction_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec",
        "source_sub_type_str": "Transferência Interna"
    },
    "datetime": "2022-09-02T21:36:33.446120",
    "webhook_type": "account_transaction"
}

Do not map webhooks restrictively

Additional fields may be added to QI Tech webhook payloads at any time. Parse defensively — an integration that rejects unknown fields will break on a future release.

9.2 Leg 2 — Disbursement to the supplier 🆕

The issuer's settlement account is opened by QI Tech free of charge at issuance and is referenced in the NC signature package. Paying the supplier from the issuer's own settlement account preserves the commercial relationship: the supplier sees the payment arriving from its own client.

The payment is not an integrator call. The beneficiary is declared on the operation itself (third_party_disbursement, see COM0024/COM0025 in §7.1), signed together with the Constitutive Term, and the disbursement is executed automatically by QI Tech once the funds settle. The integrator follows it by webhook — there is no "initiate payment" endpoint to call on this track.

Code	Step	Description	Documentation Link	Prerequisites	Status
PAY0001*	Query the issuer settlement account	Retrieve the settlement account opened for the issuer at issuance, including its identifiers and balance	Documentation Link (to be confirmed)	COM0022	🆕
PAY0002*	Confirm funds available	Confirm that the funds transferred in leg 6.1 have settled into the settlement account	Documentation Link	TFI0004	✅
PAY0003*	Automatic disbursement to the beneficiary	With `third_party_disbursement` declared on the operation, QI Tech pays the supplier out of the issuer's settlement account, by TED, bank slip or Pix, with no integrator action	Documentation Link	PAY0002, COM0024	⚙️ 🆕
PAY0004*	Query payment status	Query the disbursement status by the transaction key in the settlement account	Documentation Link	PAY0003	🆕
PAY0005*	Webhook — payment settled	Receive the webhook confirming that the supplier has been paid	Documentation Link (to be confirmed)	CAB0003, PAY0003	🆕

Available tracks

Track	`payment_method`	Field	Routing
TED	`ted`	`target_account`	By the `financial_institution_ispb`
Bank slip	`bank_slip`	`digitable_line` (47 digits)	By the digitable line itself
Pix	`pix`	`pix_key` + `pix_key_type`	By the key, over the Pix arrangement

On the Pix track the beneficiary object is mandatory — the key alone does not identify the payee. QR code is not a supported track and is not planned.

Bank slip — the amount must match the released amount

The bank slip amount is read from the last 10 digits of the digitable line, in cents, and must be equal to the operation's financial.released_amount. Any difference is refused with COM000061.

Because the calculated released_amount differs from the amount requested in financial due to fees, the practical path is: create the operation, read the released_amount from the response, and only then attach a bank slip for that exact amount. Do not change the amount of a real digitable line — that invalidates its check digits and the bank slip stops being payable.

Phase 1 scope

One NC per payment. The bank slip must cover the full released amount: payment splitting — one note funding several payments, or part to the supplier and part to the issuer — is not supported in this phase and is targeted for phase 2. The integrator must model its requests accordingly: one operation, one beneficiary, the full amount.

10. Webhook summary

Because the flow removes every manual checkpoint, these are the events the integrator must consume to follow an operation end to end.

Event	Phase	What it unlocks
Issuer status changed	1	Approval gate — unlocks the Phase 2 enablement request
Auto-signature in `pending_signature`	2	Envelope opened during the request — confirms the signature links are available
Auto-signature in `enabled`	2	All subsequent issuances may run automatically
Operation status changed	4	Visibility over analysis → approved
Operation signed	4	Subscription bulletin generation
Subscription bulletin signed	5	Trigger for the funding transfer to the WL settlement account (TFI0002)
Account transaction (`internal_funds_transfer`)	6.1	Funds confirmed in the WL settlement account — releases the supplier disbursement
Payment settled	6.2	Closes the cycle

11. Open points to be closed before go-live

#	Open point	Owner	Impact
1	Confirm the NC operating terms — number of instalments, payment methods and contract template. The auto-signature must cover every operating mode the client uses; anything outside the pre-approved set falls back to manual signing	Client	Blocks the definition of the auto-signature scope
2	~~Define the supplier payment method~~ Partly resolved 🆕 — TED and bank slip are implemented and available on request. Pix by key is also implemented and available on request, requiring the `beneficiary` object; QR code is neither supported nor planned	Client	No longer blocks Phase 6
3	~~Third-party payment — estimated 4 weeks of development~~ Resolved 🆕 — delivered through a different path than expected: the beneficiary is declared on the operation and the disbursement is automatic, with no payment endpoint. Only the documentation publication and the enablement remain pending	QI Tech	Unblocked
4	Certificate creation via API — manual today (one-off per issuer, executed by QI Tech); timeline under assessment. Does not block go-live	QI Tech	Affects onboarding scalability, not the first operations
5	~~Publication of the Phase 2 endpoint contracts (ASG)~~ Resolved — Phase 2 is documented in Issuer auto-signature. Only the automatic approval/signing behaviour (COM0020–COM0022) is still pending	QI Tech	Blocks the automatic Phase 4 homologation
6	Payment splitting confirmed as phase 2 scope — confirmed by the implementation 🆕: the bank slip must equal the full released amount, so one operation pays exactly one beneficiary	Client + QI Tech	Defines the phase 1 boundary
7	Confirm which QI Conta is debited as the origin of the leg 6.1 transfer, and whether the WL settlement account is the same account referenced in the NC signature package or a separate one	Client + QI Tech	Fixes the `ACCOUNT_KEY` and `target_account` of TFI0002
8	Enable third-party disbursement for the client before go-live — it is not enabled by default, and without it operation creation is refused with `COM000062` 🆕	QI Tech	Blocks the client's use of the feature
9	Publish the `third_party_disbursement` object page and add `COM000061`, `COM000062` and `COM000063` to the error catalog 🆕	QI Tech	Blocks the homologation of the third-party disbursement track
10	Publish the Pix by key track in the documentation — the `beneficiary` object, the `pix_key_type` values, and code `COM000071` in the error catalog 🆕	QI Tech	Blocks the homologation of the Pix track

12. Error mapping

Errors originating from the issuer, investor and commercial note APIs are catalogued in the Error Catalog.

The enablement request is rejected with ISS0000032 when the issuer is not approved, ISS0000033 when the client is not enabled, and ISS0000029 when an active enablement already exists. The query returns ISS0000028 when the issuer has no active enablement — which is also the case after a reproved or canceled. The remaining auto-signature-specific errors — attempting issuance while enablement is not enabled, an operating term outside the approved scope, or a mismatch between the signer group and the certificate holder — will be added to the same catalog when the automatic signing behaviour (COM0020–COM0022) is published.

1. Scope and phasing​

2. End-to-end flow​

3. Phase 0 — Registration and API authentication​

4. Phase 1 — Issuer homologation​

4.1 Phase 1A — Issuer registered in the QI Tech assignor system​

4.2 Phase 1B — Issuer registered through the system​

5. Phase 2 — Auto-signature enablement ✅​

5.1 Enablement status machine​

6. Phase 3 — Investor homologation​

6.1 Investors registered during setup — recommended path​

6.2 Investors registered through the system — only if fixed funds are not used​

7. Phase 4 — NC issuance​

7.1 Operation creation​

7.2 Signing — automatic path (issuer with enabled auto-signature) 🆕​

7.3 Signing — manual fallback (QI SIGN)​

8. Phase 5 — Subscription and settlement​

9. Phase 6 — Funding and disbursement 🆕​

9.1 Leg 1 — Transfer to the WL settlement account 🆕​

TFI0002 — Command the internal transfer​

TFI0004 — Webhook confirming the credit​

9.2 Leg 2 — Disbursement to the supplier 🆕​

Available tracks​

10. Webhook summary​

11. Open points to be closed before go-live​

12. Error mapping​

1. Scope and phasing

2. End-to-end flow

3. Phase 0 — Registration and API authentication

4. Phase 1 — Issuer homologation

4.1 Phase 1A — Issuer registered in the QI Tech assignor system

4.2 Phase 1B — Issuer registered through the system

5. Phase 2 — Auto-signature enablement ✅

5.1 Enablement status machine

6. Phase 3 — Investor homologation

6.1 Investors registered during setup — recommended path

6.2 Investors registered through the system — only if fixed funds are not used

7. Phase 4 — NC issuance

7.1 Operation creation

7.2 Signing — automatic path (issuer with `enabled` auto-signature) 🆕

7.3 Signing — manual fallback (QI SIGN)

8. Phase 5 — Subscription and settlement

9. Phase 6 — Funding and disbursement 🆕

9.1 Leg 1 — Transfer to the WL settlement account 🆕

TFI0002 — Command the internal transfer

TFI0004 — Webhook confirming the credit

9.2 Leg 2 — Disbursement to the supplier 🆕

Available tracks

10. Webhook summary

11. Open points to be closed before go-live

12. Error mapping