Vendor registration

A vendor is the individual or legal entity that provides a service to the fund and receives the payment of an expense: audit, custody, consulting, distribution and others. Before it can be used in a contract or an expense, the vendor must be approved in a QI Tech registration analysis.

This section documents the calls the manager and the consultant use to register the vendor through the API. Where a page says "manager", the same applies to the consultant, for the vendors it registered. In API fields, the manager or the consultant appears as the agent (agent).

An approved registration is valid for two years. To renew it, the manager opens a new analysis on the same vendor and resubmits what has changed.

Registration flow

Legend: blue boxes with a solid border are the manager's steps through the API; dashed gray boxes are QI Tech analysis steps; the green box is the approved vendor; the red ones are analyses closed without approval.

During the manual review, QI Tech may open annotations. Until the analysis reaches compliance, the manager can withdraw it from the queue to correct the registration.

1. Create the vendor

Create the vendor from its CPF or CNPJ and name. Creation immediately opens the first analysis in pending_submission. The response is the analysis: store analysis_key and the vendor key, which comes in vendor.vendor_key.

2. Fill in the registration data

Set the name, email and address. Without an email, the analysis cannot be submitted.

3. Declare the related parties (legal entity)

Declare partners, administrators, attorneys-in-fact and the parent company. A legal entity vendor needs at least one party with is_representative: true. An individual vendor skips this step: it has no related parties.

4. Upload the documents

Upload the documents of the vendor and of each related party. The main required ones:

• legal entity: articles of association or bylaws;
• individual and each representative: an identification document.

5. Register the bank account and the signer group

Register the account that receives the payments of the vendor's expenses and declare who signs expense contracts on behalf of the vendor. Neither is required to submit the analysis.

6. Submit for analysis

Submit the registration to QI Tech (status: sent_to_analysis). From then on, the registration is locked until the analysis ends.

7. Track the analysis

If the documents and the people pass the automated validations, QI Tech approves the registration on its own. Otherwise, an analyst reviews it (in_manual_analysis) and, if needed, compliance does too (in_compliance_analysis). During the manual review, the analyst may open annotations asking for a clarification or a document.

Analysis status

Status	Description	Applied by
pending_submission	Being filled in. The only analysis status in which data, parties and documents can be changed.	Initial status. The manager returns to it when withdrawing the analysis from the queue.
sent_to_analysis	Submitted. Automated validation of documents and people in progress.	Manager
in_manual_analysis	Under review by a QI Tech analyst.	Automatic or QI Tech
in_compliance_analysis	Under review by QI Tech compliance.	Automatic or QI Tech
approved	Approved. The vendor becomes active for two years.	Automatic or QI Tech
reproved	Rejected. reproval_reason gives the reason.	QI Tech
canceled	Canceled by the manager.	Manager

Transitions the manager performs:

pending_submission     ──→ sent_to_analysis     (submission for analysis)
sent_to_analysis       ──→ pending_submission   (withdrawal from the queue, to correct)
in_manual_analysis     ──→ pending_submission   (withdrawal from the queue, to correct)
any non-final status   ──→ canceled             (cancellation)

In in_compliance_analysis, the manager's only action is to cancel. approved, reproved and canceled are final.

Rejection reasons

reproval_reason	Origin	Effect
invalid_documents, missing_documents, incorrect_information, missing_information, additional_documents_required	QI Tech analyst	The vendor keeps its status. Open a new analysis, correct it and resubmit.
compliance_reproval	QI Tech compliance	Final: the vendor moves to inactive with block_reason: compliance_reproval and does not accept a new analysis.

reproval_details carries the details as free text.

Vendor status

Status	Description
pending_analysis	Never approved. There is an analysis in progress or one closed without approval.
active	Approved and within its validity period. Can be used in contracts and expenses.
expired	Two-year validity expired. Open a new analysis; on approval, it returns to active.
inactive	Rejected by compliance or blocked by QI Tech.

During a new analysis, an active or expired vendor keeps its status. Canceling the analysis or receiving a registration rejection does not change the vendor status either.

General rules

• Ownership. The vendor belongs to the manager or consultant that created it. For any other agent, the same vendor_key returns 404.
• Repeated CPF or CNPJ. Different agents can register the same CPF or CNPJ: each one has its own vendor, independent of the others. Creation only returns 409 (VRG000015) when you already see a vendor with that document number, including through a consultant's contract.
• Consultant's vendor in a contract. When a contract uses a consultant's vendor, the fund's manager can see it in queries but cannot change it: any change it attempts returns 403 (VRG000046).
• Consultant permission. On consultant-api, an active integration is enough: vendor registration does not depend on per-fund permissions. The consultant must be registered in the vendor service; otherwise, the API returns 404 (VRG000043).
• Registration lock. What can change depends on the analysis status:
  • pending_submission: the only status in which registration data, related parties and documents of the analysis change. Only what changes in this status is reviewed.
  • sent_to_analysis, in_manual_analysis or in_compliance_analysis: the analysis is with QI Tech and this data is locked (409, VRG000104 or VRG000072).
  • approved, reproved or canceled: the analysis registration data (409, VRG000010) and documents (409, VRG000072) no longer change. To change them, open a new analysis.
  • With no analysis in progress, a related party can be created, activated or deactivated, but it is only reviewed in the next analysis (see Related parties).
• Bank accounts and signer groups are not subject to this lock: they do not depend on the analysis status.
• One analysis at a time. Each vendor has at most one analysis in progress. A new one can only be opened when the previous one is approved, reproved (registration reason) or canceled.
• Dates and times. *_datetime and last_updated fields come in UTC, in the YYYY-MM-DD HH:MM:SS.ffffff format, without a time zone. Exception: in the response to a write, the value recorded by that same call comes with the +00:00 suffix. Dates come as YYYY-MM-DD.
• CPF and CNPJ. Accepted with or without punctuation and always returned with punctuation (123.456.789-09, 11.222.333/0001-81).
• Tracking. Vendor registration is not among the webhook systems configurable in the portal. Track it through the analysis retrieval or the status history. The analysis outcome is also sent by email to the registered addresses of every agent with access to the vendor: whoever created it and whoever sees it through a consultant's contract.

Errors

Errors that recur across calls on a vendor and the data linked to it:

Status	code	When it happens
403	VRG000046	You tried to change a vendor you can see but do not own. This happens to a manager that sees a consultant's vendor through a contract.
404	VRG000014	The vendor_key does not exist or the vendor is not visible to you. Also returned for an analysis_key of a vendor you cannot see.

Authentication, permission and host errors: see API Errors. The other vendor registration errors have the VRG prefix and are listed on each call's page.