Criação do fornecedor
Cria o fornecedor a partir do CPF ou CNPJ e do nome, e abre a primeira análise cadastral em pending_submission. A resposta é a análise, não o fornecedor: guarde analysis_key para as próximas etapas e vendor.vendor_key para identificar o fornecedor.
O tipo de pessoa vem do documento: CPF cria natural_person; CNPJ cria legal_person.
Para renovar ou corrigir um fornecedor que já existe, use Abrir nova análise.
Criar fornecedor
| Perfil | Host | Permissão exigida |
|---|---|---|
| Gestora | manager-api | Escrita |
| Consultoria | consultant-api | Integração ativa |
URL base de cada host: Ambientes (Hosts).
{
"document_number": "44.555.666/0001-81",
"name": "AUDITORES EXEMPLO S.A.",
"email": "contato@auditoresexemplo.com.br"
}
Atributos do corpo
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
document_number | string | Sim | CPF ou CNPJ do fornecedor, com ou sem pontuação. De 11 a 18 caracteres. CNPJ alfanumérico é aceito. |
name | string | Sim | Nome ou razão social. Máximo de 255 caracteres. |
email | string | Não | E-mail do fornecedor. Máximo de 255 caracteres. Pode ser informado depois nos dados cadastrais; é obrigatório para enviar a análise. |
person_type | string | Não | natural_person ou legal_person. Quando informado, precisa bater com o documento. |
Nenhum outro campo é aceito.
Resposta
{
"analysis_key": "8c2a6f0e-1b3d-4f7a-9c1e-2a4b6d8f0c13",
"analysis_number": 1,
"agent": {
"agent_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
"agent_type": "manager",
"name": "EXEMPLO GESTORA LTDA",
"document_number": "22.333.444/0001-81"
},
"status": "pending_submission",
"reproval_reason": null,
"reproval_details": null,
"last_updated": "2026-11-09 14:03:21.123456+00:00",
"signer_groups": [],
"vendor": {
"vendor_key": "5d2e7b9a-3c4f-4e8a-b1d6-9f0a2c3e4b57",
"name": "AUDITORES EXEMPLO S.A.",
"document_number": "44.555.666/0001-81",
"email": "contato@auditoresexemplo.com.br",
"address": null,
"person_type": "legal_person",
"status": "pending_analysis",
"block_reason": null,
"expiration_date": null,
"agents": [
{
"agent_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
"agent_type": "manager",
"name": "EXEMPLO GESTORA LTDA",
"document_number": "22.333.444/0001-81",
"permission_type": "owner"
}
],
"related_parties": [],
"bank_accounts": [],
"signer_groups": [],
"last_analysis": {
"analysis_key": "8c2a6f0e-1b3d-4f7a-9c1e-2a4b6d8f0c13",
"analysis_number": 1,
"status": "pending_submission",
"analysis_related_parties": [],
"documents": [],
"annotations": [],
"last_updated": "2026-11-09 14:03:21.123456+00:00",
"reproval_reason": null,
"reproval_details": null,
"signer_groups": []
}
},
"analysis_data": {
"name": "AUDITORES EXEMPLO S.A.",
"document_number": "44.555.666/0001-81",
"email": "contato@auditoresexemplo.com.br",
"address": null,
"ai_pending_reasons": null,
"ai_pending_reason_details": null
},
"related_parties": [],
"annotations": []
}
Atributos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
analysis_key | string | Chave da análise (UUID). Use nas chamadas de dados cadastrais, documentos, envio e cancelamento. |
analysis_number | integer | Número sequencial da análise dentro do fornecedor, a partir de 1. |
agent | object | Agente dono do fornecedor (gestora ou consultoria): agent_key, agent_type (manager ou consultant), name, document_number. |
status | string | Status da análise. Na criação, sempre pending_submission. Ver status da análise. |
reproval_reason | string | Motivo da reprovação, ou null. |
reproval_details | string | Detalhe da reprovação, ou null. |
last_updated | string | Última alteração da análise. |
signer_groups | array | Grupos de assinantes ligados a esta análise. Ver Grupo de assinantes. |
vendor | object | Fornecedor completo. Ver atributos do fornecedor. |
analysis_data | object | Dados em preenchimento nesta análise: name, document_number, email, address (ver dados cadastrais), ai_pending_reasons e ai_pending_reason_details (pendências apontadas pela validação automática, ou null). |
related_parties | array | Partes relacionadas vinculadas a esta análise. Ver Partes relacionadas. |
annotations | array | Apontamentos desta análise. Ver Apontamentos. |
Valores possíveis de ai_pending_reasons: signer_not_identified, signature_rule_unclear, signer_contradiction_between_documents, mandate_expired_or_undated, societary_amendment_not_provided, company_document_mismatch, company_identification_unconfirmed, societary_data_incomplete, document_illegible. ai_pending_reason_details traz a frase em português de cada um.
Abrir nova análise
Abre a próxima análise de um fornecedor que já existe. Use para:
- renovar um fornecedor
activeouexpired; - corrigir um cadastro cuja última análise foi reprovada por motivo cadastral (
reproved) ou cancelada (canceled).
A nova análise nasce em pending_submission com uma cópia da análise anterior:
- os dados cadastrais;
- os documentos em
validouin_manual_analysis; - as partes relacionadas não inativas, cada uma com os seus documentos nesses mesmos status.
Na reprovação cadastral, as partes ainda não confirmadas (pending_registry) ficam inactive e os documentos que estavam em análise ficam invalid, e a nova análise não os copia. Depois de uma reprovação, reative as partes e reenvie os documentos que ficaram invalid. Fora isso, altere só o que mudou e envie.
| Perfil | Host | Permissão exigida |
|---|---|---|
| Gestora | manager-api | Escrita |
| Consultoria | consultant-api | Integração ativa |
URL base de cada host: Ambientes (Hosts).
Parâmetros de caminho
| Parâmetro | Tipo | Descrição |
|---|---|---|
vendor_key | string | Chave do fornecedor (UUID). |
Esta chamada não leva corpo. Um corpo com qualquer campo devolve 400 (QIT000001).
Resposta
A resposta é a nova análise, na mesma estrutura da criação do fornecedor, com analysis_number incrementado. Um fornecedor active ou expired mantém o status durante a nova análise; um fornecedor nunca aprovado fica pending_analysis.
Erros
Criar fornecedor
Fornecedor já cadastrado pela gestora
Você já tem acesso a um fornecedor com esse CPF ou CNPJ: um que você criou, um que você vê pelo contrato de uma consultoria ou o fornecedor que representa a sua própria gestora, criado automaticamente quando ela foi cadastrada no serviço. A resposta traz vendor_key e document_number do fornecedor existente: use esse fornecedor em vez de criar outro.
{
"title": "Agent Already Registered Vendor",
"description": "The selected agent has already registered a vendor with the document number 44.555.666/0001-81.",
"translation": "O agente selecionado ja registrou um fornecedor com o documento 44.555.666/0001-81.",
"code": "VRG000015",
"vendor_key": "5d2e7b9a-3c4f-4e8a-b1d6-9f0a2c3e4b57",
"document_number": "44.555.666/0001-81"
}
Documento inválido
document_number não é um CPF nem um CNPJ válido, ou person_type não corresponde ao documento.
{
"title": "Invalid document number",
"description": "The document number 44.555.666/0001-00 is invalid.",
"translation": "O documento 44.555.666/0001-00 e invalido.",
"code": "VRG000002"
}
Gestora não cadastrada no serviço
Sua gestora ainda não está cadastrada no serviço de fornecedores. Fale com integracao.dtvm@qitech.com.br.
{
"title": "Agent not found",
"description": "Agent with the key a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c was not found.",
"translation": "O agente com a chave a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c nao foi encontrado.",
"code": "VRG000043"
}
Abrir nova análise
Já existe uma análise em preenchimento
O fornecedor já tem uma análise em pending_submission. Envie ou cancele essa análise antes de abrir outra.
{
"title": "Vendor Analysis Already Open",
"description": "The vendor 5d2e7b9a-3c4f-4e8a-b1d6-9f0a2c3e4b57 already has an analysis pending submission; a new analysis can only be opened after the current one ends.",
"translation": "Este fornecedor ja tem um cadastro em preenchimento. Envie ou cancele o cadastro atual antes de abrir uma nova analise.",
"code": "VRG000106"
}
Cadastro em análise pela QI Tech
A análise atual está em sent_to_analysis, in_manual_analysis ou in_compliance_analysis. Aguarde o resultado ou cancele a análise.
{
"title": "Vendor Registration Under Analysis",
"description": "The registration of the vendor 5d2e7b9a-3c4f-4e8a-b1d6-9f0a2c3e4b57 is under analysis by QI Tech and cannot be changed until the analysis ends.",
"translation": "O cadastro deste fornecedor esta em analise pela QI Tech e nao pode ser alterado ate a analise terminar.",
"code": "VRG000104"
}
Fornecedor reprovado pelo compliance
O compliance reprovou o fornecedor em definitivo (compliance_reproval). Ele está inactive e não aceita nova análise.
{
"title": "Vendor Definitively Reproved",
"description": "The vendor 5d2e7b9a-3c4f-4e8a-b1d6-9f0a2c3e4b57 was definitively reproved by compliance and cannot open a new analysis.",
"translation": "O fornecedor 5d2e7b9a-3c4f-4e8a-b1d6-9f0a2c3e4b57 foi reprovado definitivamente pelo compliance e nao pode abrir uma nova analise.",
"code": "VRG000063"
}
Fornecedor não encontrado
A vendor_key não existe ou o fornecedor não é visível para você.
{
"title": "Vendor not found",
"description": "Vendor with the key 5d2e7b9a-3c4f-4e8a-b1d6-9f0a2c3e4b57 was not found.",
"translation": "O fornecedor com a chave 5d2e7b9a-3c4f-4e8a-b1d6-9f0a2c3e4b57 nao foi encontrada.",
"code": "VRG000014"
}
Erros de autenticação, permissão e host: veja Erros da API.
Próximo passo
Dados cadastrais: informe e-mail e endereço do fornecedor.