VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa

Verificação KYC

Como funciona a verificação de identidade (KYC) dos sellers no painel do administrador, do pedido ao veredito, com o mapa das rotas.

KYC ("conheça seu cliente") é a checagem de que um seller (lojista) é quem diz ser antes de receber dinheiro da plataforma. O seller abre uma verificação, envia os documentos da empresa pelo painel dele, e o administrador confere cada documento e um checklist interno antes de aprovar ou recusar. Esta seção cobre o lado do administrador.

Pontos-chave
  • Todas as rotas exigem o módulo vendor-kyc ligado na loja e o privilégio manage_kyc ou manage_vendors. Sem o módulo a resposta é 403 com {"error":"module_disabled","module":"vendor-kyc"}.
  • A verificação tem status em letra no JSON: P pendente, O em análise, A aprovada, R recusada, E vencida. Os filtros aceitam a palavra (in_review) ou a letra.
  • Documentos e checklist são decididos um a um. Aprovar todos os documentos não aprova a verificação, e aprovar a verificação não exige que documentos ou checklist estejam completos. A decisão final é sua.
  • A aprovação vale por 1 ano (expires_at). Passado o prazo a verificação deixa de contar como válida.
  • Se a loja ligou require_kyc_for_payouts, o seller sem verificação aprovada e válida não consegue pedir repasse (422 kyc_required na API do seller).

Como funciona

Pendente→Em análise→Aprovada ou Recusada
  1. O seller abre a verificação

    Pelo painel dele (POST /api/v1/vendor/kyc). A verificação nasce P (pendente) com 5 itens de checklist em branco. Um seller só pode ter uma verificação ativa por vez.

  2. O seller envia os documentos

    Enviados pelo painel do seller em PDF, JPG ou PNG, até 10 MB. Só dá para enviar enquanto a verificação está pendente ou recusada.

  3. Você assume a análise

    Liste a fila, abra o caso e chame Iniciar análise para movê-lo a O. Isso registra quem está analisando.

  4. Você confere e decide

    Marque cada documento e cada item do checklist e então aprove ou recuse a verificação (o motivo da recusa é obrigatório).

Estados da verificação

LetraPalavra aceita nos filtrosSignificado
PpendingEnviada, ninguém assumiu.
Oin_reviewUm administrador assumiu a análise.
AapprovedAprovada. expires_at = data da aprovação + 1 ano.
RrejectedRecusada, com rejection_reason. O seller pode reenviar documentos.
EexpiredVencida.

Conceitos-chave

Tipos de documento

cnpj_card (cartão CNPJ), social_contract (contrato social), id_document (RG ou CNH do sócio), address_proof (comprovante de endereço), bank_statement (extrato que mostre a conta em nome do CNPJ). O estado de cada documento também sai em letra: P pendente, A aprovado, R recusado, E vencido.

Itens do checklist

Cada verificação nasce com 5 itens que só o administrador preenche: cnpj_valid, address_matches, bank_matches_cnpj, no_sanctions, documents_legible. O campo passed é null (não conferido), true ou false.

Ids

Todos os ids são UUID em string. A rota de documento usa o docId e a de checklist usa o itemId, ambos vindos do detalhe da verificação.

Endpoints

MétodoCaminhoPara que serveAuth
GET/api/v1/admin/kycListar a filaadmin
GET/api/v1/admin/kyc/{id}Abrir um casoadmin
POST/api/v1/admin/kyc/{id}/reviewIniciar a análiseadmin
PUT/api/v1/admin/kyc/{id}/documents/{docId}/statusAprovar ou recusar um documentoadmin
PUT/api/v1/admin/kyc/{id}/checklist/{itemId}Marcar um item do checklistadmin
POST/api/v1/admin/kyc/{id}/approveAprovar a verificaçãoadmin
POST/api/v1/admin/kyc/{id}/rejectRecusar a verificaçãoadmin

Erros comuns

  • Esperar 404/409 em transição inválida. Iniciar, aprovar ou recusar uma verificação que já foi decidida (ou que não existe) volta 500 com detail explicando ("verification not found or already processed"). Leia o status antes de agir.
  • Chamar review em verificação já em análise. Só P pode ir para O. Aprovar e recusar aceitam P ou O.
  • Recusar sem motivo. O corpo precisa de reason não vazio, senão 400.
  • Achar que o {id} valida o documento. As rotas de documento e de checklist usam só docId e itemId. O {id} da verificação não é conferido contra eles.
  • Comparar status por palavra. O JSON devolve letras. Mapeie P/O/A/R/E no seu código.
  • Ignorar o módulo. Se a loja não tem o módulo vendor-kyc, toda a seção responde 403 module_disabled.

Próximos passos

Fila e análise
Listar, abrir e iniciar a análise.
Decisões
Documentos, checklist, aprovar e recusar.
Erros da API
O formato de erro comum a todas as rotas.
Anterior
Validar e fechar o pedido
Próxima
Fila e análise de KYC
Nesta página
  • Como funciona
  • Estados da verificação
  • Conceitos-chave
  • Tipos de documento
  • Itens do checklist
  • Ids
  • Endpoints
  • Erros comuns
  • Próximos passos