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

Documentos de sellers

Lista, consulta, baixa e revisa os documentos de verificação (KYC) enviados pelos sellers, um a um ou em lote.

KYC ("conheça seu cliente") é a verificação de identidade de uma empresa antes de deixá-la vender: contrato social, CNPJ, comprovante de endereço, dados bancários. O seller envia os comprovantes pelo painel dele; aqui o administrador abre cada arquivo e aprova ou recusa. Todas as rotas desta página exigem o módulo vendor-kyc (403 module_disabled caso contrário). Decidir exige manage_documents, manage_kyc ou manage_vendors.

Exemplos ilustrativos

Os corpos de exemplo desta página são ilustrativos (ids e nomes fictícios). Nomes de campos e formatos seguem a definição das rotas.

Listar documentos

Devolve os documentos de verificação, do mais recente para o mais antigo, com paginação, e um resumo de quantos há em cada estado. Só aparecem documentos ligados a um seller; os anexados à candidatura não entram aqui (veja a visão geral).

GET/api/v1/admin/vendor-documentsAdmin

Lista os documentos de verificação dos sellers

Parâmetros de consulta

statusstring
pendingapprovedrejectedexpiredall
Filtra por estado. Aceita a palavra ou a letra (P, A, R, E). all ou ausente lista todos. O status_counts da resposta ignora este filtro.
vendor_iduuid
Só os documentos deste seller.
vendor_searchstring
Parte da razão social do seller (sem diferenciar maiúsculas).
pageintegerpadrão: 1
Página.
per_pageintegerpadrão: 20
Itens por página, de 1 a 100. Fora disso volta a 20.

Exemplo de requisição

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

Resposta

200Documentos retornados
json
{
  "documents": [
    {
      "id": "8f6a3b4e-1c2d-4e5f-9a0b-1c2d3e4f5a6b",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "doc_type": "cnpj",
      "file_name": "cartao-cnpj.pdf",
      "file_url": "/uploads/vendor-documents/94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36/cartao-cnpj.pdf",
      "file_size": 184320,
      "status": "P",
      "created_at": "2026-10-10T14:20:00Z",
      "vendor_name": "Loja Seller Teste"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1,
  "status_counts": { "P": 1, "A": 4, "R": 1 }
}

Campos da resposta

documentsarray
Documentos da página.
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 estado, com a letra como chave (P, A, R, E, O). Respeita vendor_id e vendor_search, mas não status. Serve para as abas da tela de análise.
documents[].iduuid
Id do documento.
documents[].vendor_iduuid
Seller dono do documento.
documents[].doc_typestring
Tipo. Veja a lista na visão geral.
documents[].file_namestring
Nome original do arquivo.
documents[].file_urlstring
Endereço do arquivo, relativo à loja (/uploads/...).
documents[].file_sizeinteger
Tamanho em bytes. Ausente se desconhecido.
documents[].statusstring
PAREO
Estado, como letra: P pendente, A aprovado, R recusado, E vencido, O pendente (antigo).
documents[].notesstring
Observação do seller no envio.
documents[].review_notesstring
Observação da análise do administrador.
documents[].reviewed_atstring
Quando foi decidido. Ausente se pendente.
documents[].reviewed_bystring
Quem decidiu. Ausente se pendente.
documents[].created_atstring
Envio, RFC 3339 em UTC.
documents[].vendor_namestring
Razão social do seller.

Erros

StatusQuandoCorpo
401 / 403Sem token, sem privilégio, ou módulo desligado{"error":"module_disabled","module":"vendor-kyc"}
500Falha interna, ou vendor_id que não é UUID{"error":"failed to list vendor documents","detail":"..."}

Consultar um documento

Devolve um documento com o nome do seller, no mesmo formato de cada item da lista.

GET/api/v1/admin/vendor-documents/{id}Admin

Detalha um documento de seller

Parâmetros de caminho

iduuidobrigatório
Id do documento.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/vendor-documents/8f6a3b4e-1c2d-4e5f-9a0b-1c2d3e4f5a6b" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Documento retornado
json
{
  "id": "8f6a3b4e-1c2d-4e5f-9a0b-1c2d3e4f5a6b",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "doc_type": "cnpj",
  "file_name": "cartao-cnpj.pdf",
  "file_url": "/uploads/vendor-documents/94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36/cartao-cnpj.pdf",
  "file_size": 184320,
  "status": "A",
  "review_notes": "Conferido na Receita.",
  "reviewed_at": "2026-10-11T09:00:00Z",
  "reviewed_by": "67bf291c-0846-4053-9528-8cfd5ab0ebf1",
  "created_at": "2026-10-10T14:20:00Z",
  "vendor_name": "Loja Seller Teste"
}

Erros

StatusQuandoCorpo
404Documento inexistente{"error":"document not found"}
500id que não é UUID, ou documento sem seller ligado (os anexados à candidatura){"error":"failed to get document","detail":"..."}

Baixar o arquivo

Entrega o arquivo enviado pelo seller, com Content-Disposition: attachment. Só funciona para arquivos guardados pela própria plataforma (file_url começando por /uploads/). A rota protege contra caminhos que saiam da pasta de envios.

GET/api/v1/admin/vendor-documents/{id}/downloadAdmin

Baixa o arquivo de um documento

Parâmetros de caminho

iduuidobrigatório
Id do documento.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/vendor-documents/8f6a3b4e-1c2d-4e5f-9a0b-1c2d3e4f5a6b/download" \
  -H "Authorization: Bearer $TOKEN" \
  -o cartao-cnpj.pdf

Resposta

200Arquivo
text
(conteúdo binário do arquivo, por exemplo um PDF)

O Content-Type é detectado pela extensão do arquivo, e o nome sugerido é o file_name do documento.

Erros

StatusQuandoCorpo
404Documento inexistente, ou arquivo que não está mais no disco{"error":"document not found"} ou 404 page not found
403O caminho do arquivo sai da pasta de envios{"error":"access denied: path traversal detected"}
500id que não é UUID{"error":"failed to get document","detail":"..."}

Revisar um documento

Aprova ou recusa um documento. Grava a decisão, a observação, a data e quem decidiu. Não muda o estado da candidatura do seller.

PUT/api/v1/admin/vendor-documents/{id}/reviewAdmin

Aprova ou recusa um documento

Parâmetros de caminho

iduuidobrigatório
Id do documento.

Corpo da requisição

statusstringobrigatório
approvedrejected
Decisão.
review_notesstring
Observação da análise. Ao recusar, diga o que o seller deve corrigir.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/vendor-documents/8f6a3b4e-1c2d-4e5f-9a0b-1c2d3e4f5a6b/review" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "approved", "review_notes": "Conferido na Receita."}'

Resposta

200Documento revisado
json
{
  "message": "document reviewed",
  "document_id": "8f6a3b4e-1c2d-4e5f-9a0b-1c2d3e4f5a6b",
  "status": "approved"
}

Erros

StatusQuandoCorpo
400Corpo que não é JSON{"error":"invalid request body","detail":"..."}
400status diferente de approved e rejected{"error":"status must be 'approved' or 'rejected'"}
500Documento inexistente (deveria ser 404) ou id que não é UUID{"error":"failed to review document","detail":"document 0000... not found"}
401 / 403Sem token, sem manage_documents/manage_kyc/manage_vendors, ou módulo desligado{"error":"module_disabled","module":"vendor-kyc"}

Revisar vários documentos

Decide vários documentos de uma vez com a mesma decisão. Só altera os que estão pendentes; ids já decididos são ignorados em silêncio.

Há três jeitos de chamar, do mais simples ao mais seguro:

  1. Lista de ids (document_ids): decide na hora e responde com a contagem.
  2. Simulação (simulate: true, com document_ids ou filter): não altera nada; devolve quantos documentos seriam afetados, uma amostra e um confirm_token.
  3. Por critério (filter): o servidor escolhe os documentos pelos critérios. Exige simular antes e repetir o mesmo corpo com o confirm_token recebido.
POST/api/v1/admin/vendor-documents/bulk-reviewAdmin

Aprova ou recusa vários documentos

Corpo da requisição

statusstringobrigatório
approvedrejected
Decisão aplicada a todos.
document_idsarrayobrigatório
Ids (UUID) dos documentos. Obrigatório quando não se usa filter; lista vazia dá 400.
review_notesstring
Observação gravada em todos.
filterobject
Critérios em vez de ids. Chaves aceitas: status (pending, approved, rejected), pending (true), document_type, vendor_id (UUID), created_after e created_before (YYYY-MM-DD), ids (lista de ids), exclude_ids (ids a deixar de fora) e all (true, para alcançar todos os pendentes). Um filtro sem nenhum recorte é recusado. Chave desconhecida é recusada com 400 invalid_filter.
simulatebooleanpadrão: false
Só simula: conta, mostra a amostra e devolve o confirm_token.
confirm_tokenstring
Token da simulação, obrigatório para executar por filter. Vale por pouco tempo e só para o mesmo pedido.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/vendor-documents/bulk-review" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "approved",
    "document_ids": ["8f6a3b4e-1c2d-4e5f-9a0b-1c2d3e4f5a6b", "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"],
    "review_notes": "Conferidos"
  }'

Resposta

200Documentos revisados (lista de ids)
json
{ "message": "documents reviewed", "status": "approved", "reviewed": 2 }
200Simulação (simulate true)
json
{
  "simulate": true,
  "action": "approved",
  "description": "Aprovar documentos de seller",
  "total": 12,
  "sample": [],
  "confirm_token": "tok_exemplo",
  "expires_at": "2026-10-11T22:20:00Z",
  "async": false,
  "by": "filter"
}

Campos da resposta

reviewedinteger
Documentos de fato alterados (lista de ids). Pode ser menor que o número de ids, porque os já decididos são ignorados.
totalinteger
Na simulação, quantos documentos pendentes o pedido alcança.
samplearray
Na simulação, uma amostra com o antes e o depois de alguns documentos.
confirm_tokenstring
Na simulação, o token para confirmar a execução.
expires_atstring
Na simulação, quando o token vence.
asyncboolean
Se a execução vai rodar em segundo plano como tarefa com progresso.

Na execução por filter a resposta usa o formato comum das operações em lote: action, by, total_requested, status, affected e failed; um lote parcial vem com partial_failure: true. Quando é grande, responde 202 com async: true e a tarefa em job.

Erros

StatusQuandoCorpo
400Corpo que não é JSON{"error":"invalid request body","detail":"..."}
400status diferente de approved e rejected{"error":"status must be 'approved' or 'rejected'"}
400Sem document_ids (nem filter){"error":"document_ids is required"}
400Filtro com chave desconhecida ou valor inválido{"error":"invalid_filter","detail":"..."}
409confirm_token de outro pedido, ou o recorte cresceu desde a simulação{"error":"confirm_token_invalid","detail":"..."}
428Execução por filter sem simulação prévia{"error":"simulate_required","detail":"..."}
500Falha interna{"error":"failed to bulk review documents","detail":"..."}
Confira o reviewed

200 não quer dizer que todos os ids foram decididos. Compare reviewed com o tamanho da lista que você enviou; a diferença são documentos que já estavam decididos ou não existem.

Veja também

  • Candidaturas
  • Cadastro de sellers: visão geral
Anterior
Candidaturas de sellers
Próxima
Termos de uso dos sellers
Nesta página
  • Listar documentos
  • Exemplo de requisição
  • Resposta
  • Erros
  • Consultar um documento
  • Exemplo de requisição
  • Resposta
  • Erros
  • Baixar o arquivo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Revisar um documento
  • Exemplo de requisição
  • Resposta
  • Erros
  • Revisar vários documentos
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também