Vendor Registration

Vendor registration is the prerequisite for creating expense contracts. The process is carried out by the integrating agent itself via API and goes through QI Tech analysis and approval before the vendor is activated on the platform.

Registration flow

Registering a vendor follows these steps:

1. Analysis creation — sending the vendor data (this page)
2. Document upload — attaching supporting documents
3. Submission for review — forwarding for QI Tech analysis
4. Replying to notes (if requested) — replying to the requests from the analysis team
5. Approval — the vendor is activated and the vendor_key becomes available for use in contracts

For details about the following steps, see:

• Document upload
• Submission for analysis
• Notes

---

Request

ENDPOINT

/vendor_registry/analysis

METHOD

POST

Request Body

{
    "vendor_document_number": "12.345.678/0001-90",
    "vendor_name": "AUDITORES EXEMPLO S.A.",
    "requires_invoice": true,
    "payment_method": "transfer",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_account": {
            "account_number": "123456",
            "account_branch": "0001",
            "account_digit": "0",
            "financial_institution_code": "341"
        }
    }
}

Body attributes

Field	Type	Required	Description
vendor_document_number	string	required	Vendor's CPF or CNPJ with punctuation. Minimum 14, maximum 18 characters.
vendor_name	string	required	Vendor's full name. Maximum of 255 characters.
requires_invoice	boolean	optional	Indicates whether the vendor requires an invoice for payment. Default: false.
payment_method	string	optional	Vendor's default payment method. Currently supports only transfer. Required when payment is provided.
payment	object	optional	Vendor's default bank details. See payment attributes. Required when payment_method is provided.

payment attributes

Field	Type	Required	Description
target	object	required	Payment beneficiary data.
target.name	string	required	Beneficiary name.
target.document_number	string	required	Beneficiary's CPF or CNPJ with punctuation.
target_account	object	optional	Destination bank account data (TED/DOC). Required when transfer_type is not provided or is wire_transfer.
target_account.account_number	string	required	Account number (1–20 digits, cannot be all zeros).
target_account.account_branch	string	required	Bank branch (exactly 4 digits, cannot be all zeros).
target_account.account_digit	string	required	Account check digit (1 digit).
target_account.financial_institution_code	string	required	Bank code (exactly 3 digits, cannot be all zeros).
target_account.financial_institution_ispb	string	optional	Bank ISPB (exactly 8 digits). When not provided, it is filled in automatically based on the financial_institution_code.
target_account.account_type	string	optional	Bank account type.
transfer_type	string	optional	Transfer type. Provide pix for payment via Pix. When omitted, the payment is made via TED/DOC.
target_pix_key	string	optional	Recipient's Pix key (max. 77 characters). Required when transfer_type is pix and target_account is not provided. The Pix key must belong to the CPF/CNPJ in target.document_number.

---

Response

STATUS

201

Response Body

{
    "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "status": "pending_submission",
    "requires_invoice": true,
    "manager": {
        "name": "EXEMPLO GESTORA LTDA",
        "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
        "document_number": "45.585.471/0001-47"
    },
    "vendor": {
        "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "name": "AUDITORES EXEMPLO S.A.",
        "document_number": "12.345.678/0001-90",
        "requires_invoice": true,
        "status": "pending_analysis"
    },
    "payment_method": "transfer",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_account": {
            "account_number": "123456",
            "account_branch": "0001",
            "account_digit": "0",
            "financial_institution_code": "341",
            "financial_institution_ispb": "60701190"
        }
    }
}

Response attributes

Field	Type	Description
analysis_key	string	Unique key of the analysis (UUID). Store this value for the next steps.
status	string	Initial status of the analysis. Always returns pending_submission.
requires_invoice	boolean	Indicates whether this analysis requires an invoice.
manager	object	Data of the authenticated manager.
manager.name	string	Manager name.
manager.manager_key	string	Unique key of the manager (UUID).
manager.document_number	string	Manager's CNPJ.
vendor	object	Vendor data.
vendor.vendor_key	string	Unique key of the vendor. Available after approval for use in contracts.
vendor.name	string	Vendor name.
vendor.document_number	string	Vendor's CPF or CNPJ.
vendor.requires_invoice	boolean	Indicates whether the vendor requires an invoice.
vendor.status	string	Vendor status: pending_analysis while the analysis is in progress.
payment_method	string	Payment method, when provided.
payment	object	Bank details, when provided.

---

Possible errors

STATUS

409

Vendor already active

An active vendor (status = active) already exists with the provided CNPJ/CPF. Use the vendor listing to obtain the vendor_key.

{
  "title": "Vendor already exists",
  "description": "Already exists an active vendor with the document number {vendor_document_number}.",
  "translation": "Já existe um fornecedor ativo com o cnpj {vendor_document_number}.",
  "code": "VRG000015"
}

STATUS

404

Manager not found

The manager_key of the authenticated agent does not correspond to any manager registered on the platform.

{
  "title": "Manager not found",
  "description": "Manager with the key {manager_key} was not found.",
  "translation": "O gestor com a chave {manager_key} não foi encontrado.",
  "code": "VRG000001"
}

STATUS

400

Invalid document number

The CPF or CNPJ provided in vendor_document_number is not valid.

{
  "title": "Invalid document number",
  "description": "The document number {vendor_document_number} is invalid.",
  "translation": "O documento {vendor_document_number} é inválido.",
  "code": "VRG000002"
}

---

Next steps

With the analysis created (status pending_submission), the next steps are:

1. Document upload — attach the articles of association and the representatives' documents.
2. Submission for analysis — forward the analysis for QI Tech review.