API atual/Referência completa/Verificação KYC

Fila e análise de KYC

Lista as verificações de seller, abre o detalhe com documentos e checklist e move o caso para "em análise".

Use estas três operações para trabalhar a fila: ver o que está esperando, abrir um caso inteiro (documentos e checklist) e assumir a análise para que os outros administradores saibam que alguém já está nele. O módulo vendor-kyc precisa estar ligado e você precisa do privilégio manage_kyc ou manage_vendors.

Listar verificações

Devolve as verificações da mais recente para a mais antiga, com paginação, e um resumo de quantas existem em cada status (para montar as abas da tela).

GET/api/v1/admin/kycAdmin

Lista as verificações de KYC dos sellers

Parâmetros de consulta

statusstring

pendingin_reviewapprovedrejectedexpiredall

Filtra por status. Aceita a palavra ou a letra (P, O, A, R, E). Vazio ou all não filtra.

searchstring

Parte da razão social ou do CNPJ do seller, sem diferenciar maiúsculas.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Acima de 100 é cortado em 100; menor que 1 vira 20.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/kyc?status=pending&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Verificações retornadas

json

{
  "verifications": [
    {
      "id": "3f1c2a54-6b0e-4d1a-9c53-0a1f7a2b9e10",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "status": "P",
      "submitted_at": "2026-10-09T14:20:00Z",
      "notes": "",
      "vendor_name": "Loja Seller Teste"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1,
  "status_counts": { "P": 1, "A": 4 }
}

Campos da resposta

verificationsarray

Verificações da página.

verifications[].iduuid

Id da verificação.

verifications[].vendor_iduuid

Seller dono da verificação.

verifications[].vendor_namestring

Razão social do seller. Vazio se o seller foi removido.

verifications[].statusstring

POARE

Status em letra.

verifications[].submitted_atstring

Quando o seller abriu a verificação (RFC 3339, UTC).

verifications[].reviewed_atstring

Quando foi decidida. Ausente enquanto não decidida.

verifications[].reviewed_byuuid

Administrador que assumiu ou decidiu. Ausente se ninguém assumiu.

verifications[].expires_atstring

Fim da validade (aprovação + 1 ano). Só em verificações aprovadas.

verifications[].rejection_reasonstring

Motivo da recusa. Só em recusadas.

verifications[].notesstring

Observações internas, pode ser vazio.

totalinteger

Total que casa com o filtro, em todas as páginas.

pageinteger

Página devolvida.

per_pageinteger

Itens por página aplicados.

total_pagesinteger

Número de páginas.

status_countsobject

Quantidade por status, com a letra como chave. Não respeita o filtro status nem search: conta tudo.

Erros

Status	Quando	Corpo de exemplo
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	Módulo vendor-kyc desligado, ou sem o privilégio.	`{"error":"module_disabled","module":"vendor-kyc"}`
500	Falha ao consultar.	`{"error":"failed to list verifications","detail":"..."}`

Abrir uma verificação

Devolve o caso completo: a verificação, todos os documentos enviados e os 5 itens de checklist. É daqui que saem o docId e o itemId das decisões.

GET/api/v1/admin/kyc/{id}Admin

Consulta uma verificação com documentos e checklist

Parâmetros de caminho

iduuidobrigatório

Id da verificação.

200Verificação com documentos e checklist

json

{
  "id": "3f1c2a54-6b0e-4d1a-9c53-0a1f7a2b9e10",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "status": "O",
  "submitted_at": "2026-10-09T14:20:00Z",
  "reviewed_by": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "notes": "",
  "vendor_name": "Loja Seller Teste",
  "documents": [
    {
      "id": "8f6a3b4e-1c2d-4e5f-9a0b-1c2d3e4f5a6b",
      "verification_id": "3f1c2a54-6b0e-4d1a-9c53-0a1f7a2b9e10",
      "document_type": "cnpj_card",
      "file_name": "cartao-cnpj.pdf",
      "file_url": "/uploads/kyc-documents/94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36/b1e2.pdf",
      "status": "P",
      "uploaded_at": "2026-10-09T14:25:00Z"
    }
  ],
  "checklist": [
    {
      "id": "c7d8e9f0-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
      "verification_id": "3f1c2a54-6b0e-4d1a-9c53-0a1f7a2b9e10",
      "check_item": "cnpj_valid",
      "passed": null,
      "notes": ""
    }
  ]
}

Campos da resposta

documentsarray

Documentos enviados. Lista vazia ([]) se o seller ainda não enviou nenhum.

documents[].document_typestring

cnpj_cardsocial_contractid_documentaddress_proofbank_statement

Tipo do documento.

documents[].file_urlstring

Endereço do arquivo, relativo à loja (/uploads/...). Abra com o token do administrador.

documents[].statusstring

PARE

Status do documento, em letra.

documents[].rejection_reasonstring

Motivo, quando o documento foi recusado.

documents[].reviewed_atstring

Quando o documento foi decidido.

checklistarray

Os 5 itens de conferência.

checklist[].check_itemstring

cnpj_validaddress_matchesbank_matches_cnpjno_sanctionsdocuments_legible

Qual conferência.

checklist[].passedboolean

null = ainda não conferido; true passou; false falhou.

checklist[].checked_byuuid

Quem marcou, quando já marcado.

checklist[].checked_atstring

Quando foi marcado.

checklist[].notesstring

Observação do conferente.

Os demais campos são os mesmos da lista.

Erros

Status	Quando	Corpo de exemplo
400	`id` não é UUID.	`{"error":"invalid id","detail":"id must be a valid UUID"}`
404	Verificação não existe.	`{"error":"verification not found"}`
401 / 403	Como na lista.

Iniciar a análise

Move a verificação de P (pendente) para O (em análise) e grava você como reviewed_by. Não é obrigatório para aprovar ou recusar, mas evita que dois administradores trabalhem o mesmo caso.

POST/api/v1/admin/kyc/{id}/reviewAdmin

Assume a análise de uma verificação

Parâmetros de caminho

iduuidobrigatório

Id da verificação. Precisa estar em P.

Não há corpo.

bash

curl -X POST "$BASE_URL/api/v1/admin/kyc/3f1c2a54-6b0e-4d1a-9c53-0a1f7a2b9e10/review" \
  -H "Authorization: Bearer $TOKEN"

200Análise iniciada

json

{ "message": "review started", "status": "in_review" }

Erros

Status	Quando	Corpo de exemplo
400	`id` não é UUID.	`{"error":"invalid id","detail":"id must be a valid UUID"}`
500	A verificação não existe ou não está em `P`.	`{"error":"failed to start review","detail":"verification not found or not in pending status"}`

Veja também

API atual/Referência completa/Verificação KYC

Fila e análise de KYC

Lista as verificações de seller, abre o detalhe com documentos e checklist e move o caso para "em análise".

Listar verificações

Devolve as verificações da mais recente para a mais antiga, com paginação, e um resumo de quantas existem em cada status (para montar as abas da tela).

GET/api/v1/admin/kycAdmin

Lista as verificações de KYC dos sellers

Parâmetros de consulta

statusstring

pendingin_reviewapprovedrejectedexpiredall

Filtra por status. Aceita a palavra ou a letra (P, O, A, R, E). Vazio ou all não filtra.

searchstring

Parte da razão social ou do CNPJ do seller, sem diferenciar maiúsculas.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Acima de 100 é cortado em 100; menor que 1 vira 20.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/kyc?status=pending&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Verificações retornadas

json

{
  "verifications": [
    {
      "id": "3f1c2a54-6b0e-4d1a-9c53-0a1f7a2b9e10",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "status": "P",
      "submitted_at": "2026-10-09T14:20:00Z",
      "notes": "",
      "vendor_name": "Loja Seller Teste"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1,
  "status_counts": { "P": 1, "A": 4 }
}

Campos da resposta

verificationsarray

Verificações da página.

verifications[].iduuid

Id da verificação.

verifications[].vendor_iduuid

Seller dono da verificação.

verifications[].vendor_namestring

Razão social do seller. Vazio se o seller foi removido.

verifications[].statusstring

POARE

Status em letra.

verifications[].submitted_atstring

Quando o seller abriu a verificação (RFC 3339, UTC).

verifications[].reviewed_atstring

Quando foi decidida. Ausente enquanto não decidida.

verifications[].reviewed_byuuid

Administrador que assumiu ou decidiu. Ausente se ninguém assumiu.

verifications[].expires_atstring

Fim da validade (aprovação + 1 ano). Só em verificações aprovadas.

verifications[].rejection_reasonstring

Motivo da recusa. Só em recusadas.

verifications[].notesstring

Observações internas, pode ser vazio.

totalinteger

Total que casa com o filtro, em todas as páginas.

pageinteger

Página devolvida.

per_pageinteger

Itens por página aplicados.

total_pagesinteger

Número de páginas.

status_countsobject

Quantidade por status, com a letra como chave. Não respeita o filtro status nem search: conta tudo.

Erros

Status	Quando	Corpo de exemplo
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	Módulo vendor-kyc desligado, ou sem o privilégio.	`{"error":"module_disabled","module":"vendor-kyc"}`
500	Falha ao consultar.	`{"error":"failed to list verifications","detail":"..."}`

Abrir uma verificação

Devolve o caso completo: a verificação, todos os documentos enviados e os 5 itens de checklist. É daqui que saem o docId e o itemId das decisões.

GET/api/v1/admin/kyc/{id}Admin

Consulta uma verificação com documentos e checklist

Parâmetros de caminho

iduuidobrigatório

Id da verificação.

200Verificação com documentos e checklist

json

{
  "id": "3f1c2a54-6b0e-4d1a-9c53-0a1f7a2b9e10",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "status": "O",
  "submitted_at": "2026-10-09T14:20:00Z",
  "reviewed_by": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "notes": "",
  "vendor_name": "Loja Seller Teste",
  "documents": [
    {
      "id": "8f6a3b4e-1c2d-4e5f-9a0b-1c2d3e4f5a6b",
      "verification_id": "3f1c2a54-6b0e-4d1a-9c53-0a1f7a2b9e10",
      "document_type": "cnpj_card",
      "file_name": "cartao-cnpj.pdf",
      "file_url": "/uploads/kyc-documents/94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36/b1e2.pdf",
      "status": "P",
      "uploaded_at": "2026-10-09T14:25:00Z"
    }
  ],
  "checklist": [
    {
      "id": "c7d8e9f0-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
      "verification_id": "3f1c2a54-6b0e-4d1a-9c53-0a1f7a2b9e10",
      "check_item": "cnpj_valid",
      "passed": null,
      "notes": ""
    }
  ]
}

Campos da resposta

documentsarray

Documentos enviados. Lista vazia ([]) se o seller ainda não enviou nenhum.

documents[].document_typestring

cnpj_cardsocial_contractid_documentaddress_proofbank_statement

Tipo do documento.

documents[].file_urlstring

Endereço do arquivo, relativo à loja (/uploads/...). Abra com o token do administrador.

documents[].statusstring

PARE

Status do documento, em letra.

documents[].rejection_reasonstring

Motivo, quando o documento foi recusado.

documents[].reviewed_atstring

Quando o documento foi decidido.

checklistarray

Os 5 itens de conferência.

checklist[].check_itemstring

cnpj_validaddress_matchesbank_matches_cnpjno_sanctionsdocuments_legible

Qual conferência.

checklist[].passedboolean

null = ainda não conferido; true passou; false falhou.

checklist[].checked_byuuid

Quem marcou, quando já marcado.

checklist[].checked_atstring

Quando foi marcado.

checklist[].notesstring

Observação do conferente.

Os demais campos são os mesmos da lista.

Erros

Status	Quando	Corpo de exemplo
400	`id` não é UUID.	`{"error":"invalid id","detail":"id must be a valid UUID"}`
404	Verificação não existe.	`{"error":"verification not found"}`
401 / 403	Como na lista.

Iniciar a análise

POST/api/v1/admin/kyc/{id}/reviewAdmin

Assume a análise de uma verificação

Parâmetros de caminho

iduuidobrigatório

Id da verificação. Precisa estar em P.

Não há corpo.

bash

curl -X POST "$BASE_URL/api/v1/admin/kyc/3f1c2a54-6b0e-4d1a-9c53-0a1f7a2b9e10/review" \
  -H "Authorization: Bearer $TOKEN"

200Análise iniciada

json

{ "message": "review started", "status": "in_review" }

Erros

Status	Quando	Corpo de exemplo
400	`id` não é UUID.	`{"error":"invalid id","detail":"id must be a valid UUID"}`
500	A verificação não existe ou não está em `P`.	`{"error":"failed to start review","detail":"verification not found or not in pending status"}`