Cadastro de fornecedor

Um fornecedor é a pessoa física ou jurídica que presta serviço ao fundo e recebe o pagamento de uma despesa: auditoria, custódia, consultoria, distribuição e outros. Antes de ser usado em um contrato ou em uma despesa, o fornecedor precisa ser aprovado numa análise cadastral da QI Tech.

Esta seção documenta as chamadas que a gestora e a consultoria usam para cadastrar o fornecedor pela API. Onde a página diz "gestora", vale também para a consultoria, nos fornecedores que ela cadastrou. Nos campos da API, a gestora ou a consultoria aparece como agente (agent).

O cadastro aprovado vale por dois anos. Para renová-lo, a gestora abre uma nova análise sobre o mesmo fornecedor e reenvia o que mudou.

Fluxo do cadastro

Legenda: caixas azuis de borda contínua são etapas da gestora pela API; caixas cinza tracejadas são etapas da análise da QI Tech; a caixa verde é o fornecedor aprovado; as vermelhas são análises encerradas sem aprovação.

Durante a revisão manual, a QI Tech pode abrir apontamentos. Enquanto a análise não chega ao compliance, a gestora pode retirá-la da fila para corrigir o cadastro.

1. Criar o fornecedor

Crie o fornecedor a partir do CPF ou CNPJ e do nome. A criação já abre a primeira análise em pending_submission. A resposta é a análise: guarde analysis_key e a chave do fornecedor, que vem em vendor.vendor_key.

2. Preencher os dados cadastrais

Informe nome, e-mail e endereço. Sem e-mail, a análise não pode ser enviada.

3. Declarar as partes relacionadas (pessoa jurídica)

Declare sócios, administradores, procuradores e a empresa controladora. O fornecedor pessoa jurídica precisa de ao menos uma parte com is_representative: true. Fornecedor pessoa física pula esta etapa: ele não tem partes relacionadas.

4. Enviar os documentos

Envie os documentos do fornecedor e de cada parte relacionada. Os principais obrigatórios:

• pessoa jurídica: contrato social ou estatuto;
• pessoa física e cada representante: um documento de identificação.

5. Cadastrar a conta bancária e o grupo de assinantes

Cadastre a conta que recebe os pagamentos das despesas do fornecedor e declare quem assina pelo fornecedor nos contratos de despesa. Nenhum dos dois é exigido para enviar a análise.

6. Enviar para análise

Envie o cadastro para a QI Tech (status: sent_to_analysis). A partir daí, o cadastro fica travado até a análise terminar.

7. Acompanhar a análise

Se os documentos e as pessoas passam nas validações automáticas, a QI Tech aprova o cadastro sozinha. Senão, um analista revisa o cadastro (in_manual_analysis) e, se necessário, o compliance também (in_compliance_analysis). Durante a revisão manual, o analista pode abrir apontamentos pedindo um esclarecimento ou um documento.

Status da análise

Status	Descrição	Quem aplica
pending_submission	Em preenchimento. Único status da análise em que dados, partes e documentos podem ser alterados.	Status inicial. A gestora volta a ele ao retirar a análise da fila.
sent_to_analysis	Enviada. Validação automática de documentos e pessoas em andamento.	Gestora
in_manual_analysis	Em revisão por um analista da QI Tech.	Automático ou QI Tech
in_compliance_analysis	Em revisão pelo compliance da QI Tech.	Automático ou QI Tech
approved	Aprovada. O fornecedor fica active por dois anos.	Automático ou QI Tech
reproved	Reprovada. reproval_reason diz o motivo.	QI Tech
canceled	Cancelada pela gestora.	Gestora

Transições que a gestora executa:

pending_submission     ──→ sent_to_analysis     (envio para análise)
sent_to_analysis       ──→ pending_submission   (retirada da fila, para corrigir)
in_manual_analysis     ──→ pending_submission   (retirada da fila, para corrigir)
qualquer não final     ──→ canceled             (cancelamento)

Em in_compliance_analysis, a única ação da gestora é cancelar. approved, reproved e canceled são finais.

Motivos de reprovação

reproval_reason	Origem	Efeito
invalid_documents, missing_documents, incorrect_information, missing_information, additional_documents_required	Analista da QI Tech	O fornecedor mantém o status. Abra uma nova análise, corrija e reenvie.
compliance_reproval	Compliance da QI Tech	Definitivo: o fornecedor vai para inactive com block_reason: compliance_reproval e não aceita nova análise.

reproval_details traz o detalhe em texto livre.

Status do fornecedor

Status	Descrição
pending_analysis	Nunca aprovado. Há uma análise em curso ou encerrada sem aprovação.
active	Aprovado e dentro da validade. Pode ser usado em contratos e despesas.
expired	Validade de dois anos vencida. Abra uma nova análise; na aprovação, volta a active.
inactive	Reprovado pelo compliance ou bloqueado pela QI Tech.

Durante uma nova análise, um fornecedor active ou expired mantém o status. Cancelar a análise ou ter uma reprovação cadastral também não muda o status do fornecedor.

Regras gerais

• Propriedade. O fornecedor pertence à gestora ou à consultoria que o criou. Para qualquer outro agente, a mesma vendor_key devolve 404.
• CPF ou CNPJ repetido. Agentes diferentes podem cadastrar o mesmo CPF ou CNPJ: cada um tem o seu fornecedor, independente dos outros. A criação só devolve 409 (VRG000015) quando você já vê um fornecedor com esse documento, inclusive pelo contrato de uma consultoria.
• Fornecedor de consultoria em contrato. Quando um contrato usa o fornecedor de uma consultoria, a gestora do fundo passa a vê-lo nas consultas, mas não pode alterá-lo: qualquer alteração dela devolve 403 (VRG000046).
• Permissão da consultoria. No consultant-api, basta a integração ativa: o cadastro de fornecedor não depende de permissão por fundo. A consultoria precisa estar cadastrada no serviço de fornecedores; senão, a API devolve 404 (VRG000043).
• Trava do cadastro. O que pode mudar depende do status da análise:
  • pending_submission: único status em que dados cadastrais, partes relacionadas e documentos da análise mudam. Só o que muda neste status entra na avaliação.
  • sent_to_analysis, in_manual_analysis ou in_compliance_analysis: a análise está com a QI Tech e esses dados ficam travados (409, VRG000104 ou VRG000072).
  • approved, reproved ou canceled: os dados cadastrais (409, VRG000010) e os documentos (409, VRG000072) da análise não mudam mais. Para mudá-los, abra uma nova análise.
  • Sem análise em curso, uma parte relacionada pode ser criada, ativada ou desativada, mas só entra na avaliação na próxima análise (ver Partes relacionadas).
• Conta bancária e grupo de assinantes não têm essa trava: não dependem do status da análise.
• Uma análise por vez. Cada fornecedor tem no máximo uma análise em curso. Uma nova só pode ser aberta quando a anterior está approved, reproved (motivo cadastral) ou canceled.
• Datas e horas. Campos *_datetime e last_updated vêm em UTC, no formato YYYY-MM-DD HH:MM:SS.ffffff, sem fuso. Exceção: na resposta de uma escrita, o valor gravado pela própria chamada vem com o sufixo +00:00. Datas vêm como YYYY-MM-DD.
• CPF e CNPJ. São aceitos com ou sem pontuação e sempre devolvidos com pontuação (123.456.789-09, 11.222.333/0001-81).
• Acompanhamento. O cadastro de fornecedor não está entre os sistemas de webhook configuráveis no portal. Acompanhe pela consulta de análises ou pelo histórico de status. O resultado da análise também chega por e-mail aos endereços cadastrados de cada agente com acesso ao fornecedor: quem o criou e quem o vê pelo contrato de uma consultoria.

Erros

Erros que se repetem nas chamadas sobre um fornecedor e os dados ligados a ele:

Status	code	Quando acontece
403	VRG000046	Você tentou alterar um fornecedor que vê, mas não é seu. Acontece com a gestora que vê o fornecedor de uma consultoria por um contrato.
404	VRG000014	A vendor_key não existe ou o fornecedor não é visível para você. Vale também para uma analysis_key de um fornecedor que você não vê.

Erros de autenticação, permissão e host: veja Erros da API. Os demais erros do cadastro de fornecedor têm prefixo VRG e estão na página de cada chamada.