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

Decisões de KYC

Aprova ou recusa documentos, marca o checklist e emite o veredito final (aprovar ou recusar) de uma verificação de seller.

A decisão tem dois níveis. Primeiro você marca cada documento (aprovado ou recusado) e cada item do checklist (passou ou falhou). Depois decide a verificação inteira. Os dois níveis são independentes: nenhuma das rotas abaixo impede a aprovação final por causa de um documento pendente. Todas gravam no log de atividade quem agiu.

Decidir um documento

Marca um documento como aprovado ou recusado. Pode ser chamada de novo para mudar a decisão.

PUT/api/v1/admin/kyc/{id}/documents/{docId}/statusAdmin

Aprova ou recusa um documento da verificação

Parâmetros de caminho

iduuidobrigatório

Id da verificação (não é conferido contra o documento).

docIduuidobrigatório

Id do documento, vindo de documents[].id no detalhe.

Corpo da requisição

statusstringobrigatório

approvedrejected

Decisão. Qualquer outro valor falha.

reasonstring

Motivo, normalmente usado ao recusar. Fica em rejection_reason. Vazio apaga o motivo anterior.

200Documento atualizado

json

{ "message": "document status updated", "status": "rejected" }

Marcar um item do checklist

Registra o resultado de uma conferência interna (por exemplo, "o CNPJ é válido").

PUT/api/v1/admin/kyc/{id}/checklist/{itemId}Admin

Marca um item do checklist como passou ou falhou

Parâmetros de caminho

iduuidobrigatório

Id da verificação (não é conferido contra o item).

itemIduuidobrigatório

Id do item, vindo de checklist[].id no detalhe.

Corpo da requisição

passedbooleanobrigatório

true passou, false falhou. Se omitido vale false.

notesstring

Observação livre. O valor anterior é substituído.

200Item atualizado

json

{ "message": "checklist item updated" }

Aprovar a verificação

Aprova um caso em P ou O. Grava reviewed_at, reviewed_by, limpa qualquer motivo de recusa anterior e define expires_at para um ano a partir de agora.

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

Aprova a verificação de KYC

Parâmetros de caminho

iduuidobrigatório

Id da verificação.

Não há corpo.

200Aprovada

json

{ "message": "verification approved", "status": "approved" }

Recusar a verificação

Recusa um caso em P ou O. O motivo é obrigatório e fica visível para o seller, que pode corrigir os documentos e tentar de novo.

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

Recusa a verificação de KYC

Parâmetros de caminho

iduuidobrigatório

Id da verificação.

Corpo da requisição

reasonstringobrigatório

Motivo da recusa. Texto não vazio.

200Recusada

json

{ "message": "verification rejected", "status": "rejected" }

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/kyc/3f1c2a54-6b0e-4d1a-9c53-0a1f7a2b9e10/reject" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Contrato social desatualizado."}'

Erros

Status	Quando	Corpo de exemplo
400	`id`, `docId` ou `itemId` não é UUID.	`{"error":"invalid docId","detail":"docId must be a valid UUID"}`
400	Corpo não é JSON válido.	`{"error":"invalid request body","detail":"..."}`
400	Recusa sem `reason`.	`{"error":"rejection reason is required"}`
500	Documento ou item não existe; `status` do documento diferente de `approved`/`rejected`.	`{"error":"failed to update document status","detail":"invalid document status \"x\": must be 'approved' or 'rejected'"}`
500	Aprovar ou recusar verificação que não existe ou já foi decidida.	`{"error":"failed to approve verification","detail":"verification not found or already processed"}`
401 / 403	Sem token, módulo desligado ou sem privilégio.	`{"error":"module_disabled","module":"vendor-kyc"}`

Veja também

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

Decisões de KYC

Aprova ou recusa documentos, marca o checklist e emite o veredito final (aprovar ou recusar) de uma verificação de seller.

Decidir um documento

Marca um documento como aprovado ou recusado. Pode ser chamada de novo para mudar a decisão.

PUT/api/v1/admin/kyc/{id}/documents/{docId}/statusAdmin

Aprova ou recusa um documento da verificação

Parâmetros de caminho

iduuidobrigatório

Id da verificação (não é conferido contra o documento).

docIduuidobrigatório

Id do documento, vindo de documents[].id no detalhe.

Corpo da requisição

statusstringobrigatório

approvedrejected

Decisão. Qualquer outro valor falha.

reasonstring

Motivo, normalmente usado ao recusar. Fica em rejection_reason. Vazio apaga o motivo anterior.

200Documento atualizado

json

{ "message": "document status updated", "status": "rejected" }

Marcar um item do checklist

Registra o resultado de uma conferência interna (por exemplo, "o CNPJ é válido").

PUT/api/v1/admin/kyc/{id}/checklist/{itemId}Admin

Marca um item do checklist como passou ou falhou

Parâmetros de caminho

iduuidobrigatório

Id da verificação (não é conferido contra o item).

itemIduuidobrigatório

Id do item, vindo de checklist[].id no detalhe.

Corpo da requisição

passedbooleanobrigatório

true passou, false falhou. Se omitido vale false.

notesstring

Observação livre. O valor anterior é substituído.

200Item atualizado

json

{ "message": "checklist item updated" }

Aprovar a verificação

Aprova um caso em P ou O. Grava reviewed_at, reviewed_by, limpa qualquer motivo de recusa anterior e define expires_at para um ano a partir de agora.

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

Aprova a verificação de KYC

Parâmetros de caminho

iduuidobrigatório

Id da verificação.

Não há corpo.

200Aprovada

json

{ "message": "verification approved", "status": "approved" }

Recusar a verificação

Recusa um caso em P ou O. O motivo é obrigatório e fica visível para o seller, que pode corrigir os documentos e tentar de novo.

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

Recusa a verificação de KYC

Parâmetros de caminho

iduuidobrigatório

Id da verificação.

Corpo da requisição

reasonstringobrigatório

Motivo da recusa. Texto não vazio.

200Recusada

json

{ "message": "verification rejected", "status": "rejected" }

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/kyc/3f1c2a54-6b0e-4d1a-9c53-0a1f7a2b9e10/reject" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Contrato social desatualizado."}'

Erros

Status	Quando	Corpo de exemplo
400	`id`, `docId` ou `itemId` não é UUID.	`{"error":"invalid docId","detail":"docId must be a valid UUID"}`
400	Corpo não é JSON válido.	`{"error":"invalid request body","detail":"..."}`
400	Recusa sem `reason`.	`{"error":"rejection reason is required"}`
500	Documento ou item não existe; `status` do documento diferente de `approved`/`rejected`.	`{"error":"failed to update document status","detail":"invalid document status \"x\": must be 'approved' or 'rejected'"}`
500	Aprovar ou recusar verificação que não existe ou já foi decidida.	`{"error":"failed to approve verification","detail":"verification not found or already processed"}`
401 / 403	Sem token, módulo desligado ou sem privilégio.	`{"error":"module_disabled","module":"vendor-kyc"}`