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. The auto-signature enablement phase (Phase 2) depends on new development on QI Tech's side. 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

Auto-signature is configured only after the issuer registration is approved. The adoption agreement that authorizes it is signed inside the first issuance package. From the second issuance onward, issuer-side signing is fully automatic. Phase 2 is therefore a one-time gate per issuer, not a per-operation step.

---

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 is the new capability that makes the automated flow possible. It runs once per issuer, after the issuer registration has been approved, and results in a QI Tech private certificate scoped exclusively to the NC documents of this integration.

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, with facial-recognition biometrics, by the representative registered in CED0006.

When it is signed. The agreement is bundled into the first issuance package. The first operation therefore still carries a human signing step; from the second operation onward, issuer-side signing is fully automatic.

Code	Step	Description	Documentation Link	Prerequisites	Status
ASG0001*	Check auto-signature eligibility	Read the issuer's signature_configuration block to confirm the issuer is approved and eligible for auto-signature enablement	Documentation Link (pending publication)	CED0011 or CED1003	🆕
ASG0002*	Request auto-signature enablement	Request enablement for an approved issuer, indicating the signer group and the representative who will sign the adoption agreement. Returns an auto_signature_key in pending_agreement status	Documentation Link (pending publication)	ASG0001, CED0006	🆕
ASG0003*	Retrieve adoption agreement signature link	Retrieve the link through which the representative signs the adoption agreement with facial recognition. In the first issuance this link is delivered as part of the operation's signature package	Documentation Link (pending publication)	ASG0002	🆕
ASG0004*	Webhook — adoption agreement signed	Receive the webhook confirming that the adoption agreement was signed and validated	Documentation Link (pending publication)	CAB0003, ASG0003	🆕
ASG0005	Private certificate issuance	QI Tech creates the private certificate and releases it in CertifiQI, scoped to this issuer's NC documents. Manual today (one-off per issuer, executed by QI Tech); API automation is on the roadmap and does not block go-live	—	ASG0004	⚙️ 🆕
ASG0006*	Query auto-signature status	Query the enablement by auto_signature_key or by issuer_key and confirm the transition to active. No NC may rely on automatic signing before this status is reached	Documentation Link (pending publication)	ASG0002	🆕
ASG0007*	Webhook — auto-signature active	Receive the webhook signalling that the certificate is available and the issuer is enabled for automatic signing	Documentation Link (pending publication)	CAB0003, ASG0005	🆕
ASG0008	Retrieve signed adoption agreement	Retrieve the signed adoption agreement document for the integrator's own records and audit trail	Documentation Link (pending publication)	ASG0004	🆕
ASG0009	Revoke auto-signature	Revoke the enablement and the associated certificate — required when the representative changes, when the signer group is amended, or at the issuer's request. After revocation, issuances revert to the manual signature flow until Phase 2 is repeated	Documentation Link (pending publication)	ASG0006	🆕

5.1 Enablement status machine

Status	Meaning	Signing behaviour of a new NC
not_requested	Issuer approved but never submitted for enablement	Manual signature (QI SIGN)
pending_agreement	Enablement requested; adoption agreement not yet signed	Manual signature — the agreement travels in this operation's package
pending_certificate	Agreement signed; certificate being issued by QI Tech	Manual signature — hold new issuances until active
active	Certificate released in CertifiQI	Automatic
revoked	Enablement revoked	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 active, and the QI SIGN fallback (COM0015 / COM0016) in every other status. An integration that assumes active will break on the first issuance for every new issuer.

---

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	✅

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

Code	Step	Description	Documentation Link	Prerequisites	Status
COM0020*	Automatic approval	With auto-signature active 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	✅

7.3 Signing — manual fallback (QI SIGN)

Required for the first issuance of each issuer — which carries the adoption agreement — and for any issuer whose enablement status is not active.

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.

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*	Initiate third-party payment	Trigger the payment from the issuer's settlement account to the supplier via the BaaS API. Estimated 4 weeks of development	Documentation Link (pending publication)	PAY0002	🆕
PAY0004*	Query payment status	Query the status of a payment by its unique key	Documentation Link (to be confirmed)	PAY0003	🆕
PAY0005*	Webhook — payment settled	Receive the webhook confirming that the supplier has been paid	Documentation Link (to be confirmed)	CAB0003, PAY0003	🆕

Phase 1 scope

One NC per payment. Disbursement splitting — one note funding several supplier payments — is not supported in this phase and is targeted for phase 2 of the project. The integrator must model its requests accordingly: one operation, one beneficiary.

---

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 — enables the Phase 2 request
Adoption agreement signed	2	Certificate issuance begins
Auto-signature active	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: Pix/QR code or boleto. Pix/QR is straightforward; boleto requires significantly more development	Client + QI Tech	Sizes the Phase 6 development
3	Third-party payment from the settlement account — estimated 4 weeks of development	QI Tech	Blocks Phase 6
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) and of the automatic approval/signing behaviour (COM0020–COM0022)	QI Tech	Blocks Phase 2 homologation
6	Disbursement splitting confirmed as phase 2 scope	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

---

12. Error mapping

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

Auto-signature-specific errors — attempting issuance while enablement is not active, a revoked certificate, 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 ASG endpoints are published.