Cadastro de Fornecedor

O cadastro de fornecedores é o pré-requisito para a criação de contratos de despesa. O processo é realizado pelo próprio agente integrador via API e passa por análise e aprovação da QI Tech antes de o fornecedor ser ativado na plataforma.

Fluxo de cadastro

O cadastro de um fornecedor segue as seguintes etapas:

1. Criação da análise — envio dos dados do fornecedor (esta página)
2. Upload de documentos — anexar documentos comprobatórios
3. Submissão para revisão — encaminhar para análise da QI Tech
4. Resposta a anotações (se solicitado) — responder às solicitações da equipe de análise
5. Aprovação — o fornecedor é ativado e a vendor_key fica disponível para uso em contratos

Para detalhes sobre as etapas seguintes, consulte:

• Upload de documentos
• Submissão para análise
• Anotações

---

Request

ENDPOINT

/vendor_registry/analysis

MÉTODO

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"
        }
    }
}

Atributos do body

Campo	Tipo	Obrigatoriedade	Descrição
vendor_document_number	string	obrigatório	CPF ou CNPJ do fornecedor com pontuação. Mínimo 14, máximo 18 caracteres.
vendor_name	string	obrigatório	Nome completo do fornecedor. Máximo de 255 caracteres.
requires_invoice	boolean	opcional	Indica se o fornecedor exige nota fiscal para pagamento. Padrão: false.
payment_method	string	opcional	Método de pagamento padrão do fornecedor. Atualmente suporta apenas transfer. Obrigatório quando payment é informado.
payment	object	opcional	Dados bancários padrão do fornecedor. Ver Atributos de payment. Obrigatório quando payment_method é informado.

Atributos de payment

Campo	Tipo	Obrigatoriedade	Descrição
target	object	obrigatório	Dados do beneficiário do pagamento.
target.name	string	obrigatório	Nome do beneficiário.
target.document_number	string	obrigatório	CPF ou CNPJ do beneficiário com pontuação.
target_account	object	opcional	Dados da conta bancária de destino (TED/DOC). Obrigatório quando transfer_type não é informado ou é wire_transfer.
target_account.account_number	string	obrigatório	Número da conta (1–20 dígitos, não pode ser zeros).
target_account.account_branch	string	obrigatório	Agência bancária (exatamente 4 dígitos, não pode ser zeros).
target_account.account_digit	string	obrigatório	Dígito verificador da conta (1 dígito).
target_account.financial_institution_code	string	obrigatório	Código do banco (exatamente 3 dígitos, não pode ser zeros).
target_account.financial_institution_ispb	string	opcional	ISPB do banco (exatamente 8 dígitos). Quando não informado, é preenchido automaticamente com base no financial_institution_code.
target_account.account_type	string	opcional	Tipo da conta bancária.
transfer_type	string	opcional	Tipo de transferência. Informe pix para pagamento via Pix. Quando omitido, o pagamento é via TED/DOC.
target_pix_key	string	opcional	Chave Pix do destinatário (máx. 77 caracteres). Obrigatório quando transfer_type é pix e target_account não é informado. A chave Pix deve pertencer ao CPF/CNPJ de 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": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "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"
        }
    }
}

Atributos da resposta

Campo	Tipo	Descrição
analysis_key	string	Chave única da análise (UUID). Guarde este valor para as próximas etapas.
status	string	Status inicial da análise. Sempre retorna pending_submission.
requires_invoice	boolean	Indica se esta análise exige nota fiscal.
manager	object	Dados do gestor autenticado.
manager.name	string	Nome do gestor.
manager.manager_key	string	Chave única do gestor (UUID).
manager.document_number	string	CNPJ do gestor.
vendor	object	Dados do fornecedor.
vendor.vendor_key	string	Chave única do fornecedor. Disponível após aprovação para uso em contratos.
vendor.name	string	Nome do fornecedor.
vendor.document_number	string	CPF ou CNPJ do fornecedor.
vendor.requires_invoice	boolean	Indica se o fornecedor exige nota fiscal.
vendor.status	string	Status do fornecedor: pending_analysis enquanto a análise estiver em curso.
payment_method	string	Método de pagamento, quando informado.
payment	object	Dados bancários, quando informados.

---

Possíveis erros

STATUS

409

Fornecedor já ativo

Já existe um fornecedor ativo (status = active) com o CNPJ/CPF informado. Utilize a listagem de fornecedores para obter a 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

Gestor não encontrado

O manager_key do agente autenticado não corresponde a nenhum gestor cadastrado na plataforma.

{
  "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

Número de documento inválido

O CPF ou CNPJ informado em vendor_document_number não é válido.

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

---

Próximos passos

Com a análise criada (status pending_submission), as próximas etapas são:

1. Upload de documentos — anexe o contrato social e documentos dos representantes.
2. Submissão para análise — encaminhe a análise para revisão da QI Tech.