Consulta de fornecedores

Lista os fornecedores visíveis para você e consulta um fornecedor pela chave, com todos os seus dados: dados aprovados, partes relacionadas, contas bancárias, grupos de assinantes e a última análise.

Listar fornecedores

Disponível em

Perfil	Host	Permissão exigida
Gestora	`manager-api`	Leitura
Consultoria	`consultant-api`	Integração ativa

URL base de cada host: Ambientes (Hosts).

ENDPOINT

/vendor_registry/vendors

MÉTODO

GET

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
`status`	string	Não	Status do fornecedor: `pending_analysis`, `active`, `inactive`, `expired`. Aceita vários valores separados por vírgula.
`name`	string	Não	Início do nome do fornecedor, sem distinção de maiúsculas.
`document_number`	string	Não	CPF ou CNPJ exato, com ou sem pontuação.
`analysis_status`	string	Não	Status da última análise do fornecedor. Aceita vários valores separados por vírgula. Ver status da análise.
`annotation_status`	string	Não	Status do apontamento mais recente da última análise: `opened` ou `closed`. Fornecedores sem apontamento ficam fora do resultado quando este filtro é usado.
`agent_document_number`	string	Não	CPF ou CNPJ exato do agente dono do fornecedor, com ou sem pontuação.
`agent_name`	string	Não	Início do nome do agente dono do fornecedor, sem distinção de maiúsculas.
`limit`	integer	Não	Itens por página, de `0` a `1000`. Padrão: `10`.
`page`	integer	Não	Página, a partir de `0`. Padrão: `0`.

Devolve os fornecedores do mais recente para o mais antigo. Entram:

os fornecedores que você criou;
os que você vê pelo contrato de uma consultoria;
o fornecedor que representa a sua própria gestora, criado e aprovado automaticamente quando ela foi cadastrada no serviço.

Um valor desconhecido em status ou analysis_status não dá erro: a busca só não encontra nada.

Exemplo de chamada
GET /vendor_registry/vendors?status=active,expired&limit=50

Resposta

STATUS

200

Corpo da resposta
{
    "data": [
        {
            "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": {
                "postal_code": "01310-100",
                "street": "Avenida Paulista",
                "number": "1000",
                "complement": "10º andar",
                "neighborhood": "Bela Vista",
                "city": "São Paulo",
                "uf": "SP",
                "country": "BRA"
            },
            "person_type": "legal_person",
            "status": "active",
            "block_reason": null,
            "expiration_date": "2028-11-09",
            "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": [
                {
                    "related_party_key": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
                    "name": "João da Silva",
                    "document_number": "123.456.789-09",
                    "email": "joao.silva@auditoresexemplo.com.br",
                    "related_party_type": "administrator",
                    "is_representative": true,
                    "ownership_percentage": 50.0,
                    "nationality": "BRA",
                    "passport_number": null,
                    "status": "active"
                }
            ],
            "bank_accounts": [
                {
                    "bank_account_key": "0f9e8d7c-6b5a-4f3e-2d1c-0b9a8f7e6d5c",
                    "transfer_type": "pix",
                    "main_account": true,
                    "status": "active",
                    "pix_key": "44555666000181"
                }
            ],
            "signer_groups": [
                {
                    "signer_group_key": "7e6d5c4b-3a2f-4e1d-9c8b-7a6f5e4d3c2b",
                    "minimum_required_signers": 1,
                    "is_default": true,
                    "signers": [
                        {
                            "name": "João da Silva",
                            "document_number": "123.456.789-09",
                            "email": "joao.silva@auditoresexemplo.com.br",
                            "is_required_signer": true
                        }
                    ],
                    "status": "valid",
                    "analysis_key": "8c2a6f0e-1b3d-4f7a-9c1e-2a4b6d8f0c13"
                }
            ],
            "last_analysis": {
                "analysis_key": "8c2a6f0e-1b3d-4f7a-9c1e-2a4b6d8f0c13",
                "analysis_number": 1,
                "status": "approved",
                "analysis_related_parties": [
                    {
                        "analysis_related_party_key": "c0ffee00-1111-4222-8333-444455556666",
                        "related_party_key": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
                        "name": "João da Silva",
                        "document_number": "123.456.789-09"
                    }
                ],
                "documents": [
                    {
                        "document_name": "contrato_social.pdf",
                        "document_key": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a",
                        "document_type": "social_contract",
                        "file_type": "pdf",
                        "analysis_key": "8c2a6f0e-1b3d-4f7a-9c1e-2a4b6d8f0c13",
                        "status": "valid",
                        "reference_date": "2025-03-14",
                        "data": null
                    }
                ],
                "annotations": [],
                "last_updated": "2026-11-09 14:03:21.123456",
                "reproval_reason": null,
                "reproval_details": null,
                "signer_groups": []
            }
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}

Atributos do fornecedor

Campo	Tipo	Descrição
`vendor_key`	string	Chave do fornecedor (UUID).
`name`	string	Nome aprovado; antes da primeira aprovação, o informado na criação.
`document_number`	string	CPF ou CNPJ com pontuação.
`email`	string	E-mail aprovado (antes da primeira aprovação, o informado na criação), ou `null`.
`address`	object	Endereço aprovado, ou `null` antes da primeira aprovação. Mesma estrutura dos dados cadastrais.
`person_type`	string	`natural_person` ou `legal_person`.
`status`	string	`pending_analysis`, `active`, `inactive` ou `expired`. Ver status do fornecedor.
`block_reason`	string	`compliance_reproval` quando o fornecedor foi reprovado em definitivo; senão `null`.
`expiration_date`	string	Fim da validade do cadastro, `YYYY-MM-DD` (dois anos após a aprovação), ou `null` se nunca aprovado e no fornecedor que representa o próprio agente.
`agents`	array	Agentes (gestoras e consultorias) com acesso ao fornecedor: `agent_key`, `agent_type`, `name`, `document_number` e `permission_type` (`owner` ou `viewer`).
`related_parties`	array	Partes relacionadas em qualquer status. Ver Partes relacionadas.
`bank_accounts`	array	Contas bancárias em qualquer status. Ver Conta bancária.
`signer_groups`	array	Grupos de assinantes em qualquer status. Ver Grupo de assinantes.
`last_analysis`	object	Última análise: `analysis_key`, `analysis_number`, `status`, `analysis_related_parties` (partes vinculadas, com `analysis_related_party_key`, `related_party_key`, `name`, `document_number`), `documents` (sem URL), `annotations`, `last_updated`, `reproval_reason`, `reproval_details`, `signer_groups`. `null` se não houver análise.

Consultar fornecedor por chave

Disponível em

Perfil	Host	Permissão exigida
Gestora	`manager-api`	Leitura
Consultoria	`consultant-api`	Integração ativa

URL base de cada host: Ambientes (Hosts).

ENDPOINT

/vendor_registry/vendor/{vendor_key}

MÉTODO

GET

Parâmetros de caminho

Parâmetro	Tipo	Descrição
`vendor_key`	string	Chave do fornecedor (UUID).

Resposta

STATUS

200

Um fornecedor, na mesma estrutura de cada item de data da listagem.

Erros

STATUS

404

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

Gestora não cadastrada no serviço

Na listagem: 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"
}

STATUS

400

`code`	Quando acontece
`QIT000010`	`limit` ou `page` está fora do intervalo ou não é numérico.

Erros de autenticação, permissão e host: veja Erros da API.

Listar fornecedores​

Parâmetros de consulta​

Resposta​

Atributos do fornecedor​

Consultar fornecedor por chave​

Parâmetros de caminho​

Resposta​

Erros​

Listar fornecedores

Parâmetros de consulta

Resposta

Atributos do fornecedor

Consultar fornecedor por chave

Parâmetros de caminho

Resposta

Erros