API atual/Referência completa/Perfil e verificação do seller

Verificação KYC

Abre o pedido de verificação de identidade do seller, envia e remove os documentos da empresa e consulta a situação da análise.

KYC ("know your customer", conheça seu cliente) é a verificação de identidade que algumas lojas exigem do seller antes de liberar vendas e repasses. O seller abre um pedido, anexa documentos da empresa (cartão CNPJ, contrato social, documento do responsável, comprovante de endereço, extrato bancário) e a equipe da loja analisa. Estas rotas são o lado do seller; a decisão é do administrador.

Só funcionam quando a loja ligou o módulo vendor-kyc. Sem ele, todas respondem 403 com {"error":"module_disabled","module":"vendor-kyc"}.

Abrir pedido→Enviar documentos→Em análise→Aprovada ou Recusada

Situações

Nas respostas, o status vem como letra de um caractere.

Letra	Nome	Significado
`P`	`pending`	Pedido aberto, aceita documentos.
`O`	`in_review`	A equipe da loja está analisando.
`A`	`approved`	Aprovado. Vale por 1 ano a partir da aprovação.
`R`	`rejected`	Recusado, veja `rejection_reason`.
`E`	`expired`	Vencido; é preciso refazer.

Os documentos têm P (pendente), A (aprovado) e R (recusado).

Tipos de documento (`document_type`)

Valor	Documento
`cnpj_card`	Cartão CNPJ
`social_contract`	Contrato social
`id_document`	Documento de identidade do responsável
`address_proof`	Comprovante de endereço
`bank_statement`	Extrato bancário

Consultar a situação

GET/api/v1/vendor/kycSeller

Situação da verificação e documentos enviados

Devolve a verificação mais recente do seller, seus documentos e se o seller está hoje verificado (aprovada e dentro da validade).

200Verificação encontrada

json

{
  "verification": {
    "id": "6c0a3b2e-4d5f-4a8e-9b1c-7e2f1a0b9c3d",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "status": "P",
    "submitted_at": "2026-10-11T20:00:00Z",
    "notes": "",
    "vendor_name": "Loja Seller Teste"
  },
  "documents": [
    {
      "id": "0b1c2d3e-4f50-4a61-8b72-93a4b5c6d7e8",
      "verification_id": "6c0a3b2e-4d5f-4a8e-9b1c-7e2f1a0b9c3d",
      "document_type": "cnpj_card",
      "file_name": "cartao-cnpj.pdf",
      "file_url": "/uploads/kyc-documents/94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36/5a1f0c9e.pdf",
      "status": "P",
      "uploaded_at": "2026-10-11T20:05:00Z"
    }
  ],
  "is_verified": false
}

200Nenhum pedido aberto ainda

json

{ "verification": null, "documents": [], "is_verified": false }

Campos da resposta

verificationobject

Verificação mais recente, ou null se o seller nunca abriu uma.

verification.iduuid

Id da verificação.

verification.statusstring

POARE

Situação, em letra.

verification.submitted_atstring

Quando o pedido foi aberto (RFC 3339).

verification.reviewed_atstring

Quando foi decidido. Ausente antes disso.

verification.expires_atstring

Validade da aprovação. Ausente antes de aprovar.

verification.rejection_reasonstring

Motivo da recusa, quando recusada.

verification.notesstring

Observações da equipe da loja.

documentsarray

Documentos do pedido, do mais antigo ao mais novo.

documents[].iduuid

Id do documento. É o docId da remoção.

documents[].document_typestring

cnpj_cardsocial_contractid_documentaddress_proofbank_statement

Tipo do documento.

documents[].file_namestring

Nome do arquivo enviado.

documents[].file_urlstring

Caminho do arquivo guardado.

documents[].statusstring

PAR

Situação do documento, em letra.

documents[].rejection_reasonstring

Motivo, se o documento foi recusado.

documents[].uploaded_atstring

Quando foi enviado (RFC 3339).

is_verifiedboolean

true só se há verificação aprovada e ainda válida.

Abrir o pedido

POST/api/v1/vendor/kyc/submitSeller

Abre um pedido de verificação KYC

Cria uma verificação nova em pending, com a lista de checagens que a equipe da loja vai percorrer. Sem corpo. Só pode haver um pedido ativo por vez: se já existe um pending ou in_review, a resposta é 409. Depois de uma recusa ou de uma expiração, você pode abrir outro.

201Pedido aberto

json

{
  "id": "6c0a3b2e-4d5f-4a8e-9b1c-7e2f1a0b9c3d",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "status": "P",
  "submitted_at": "2026-10-11T20:00:00Z",
  "notes": ""
}

Enviar um documento

POST/api/v1/vendor/kyc/documentsSeller

Envia um documento da empresa

Envio de arquivo em multipart/form-data. O servidor confere o conteúdo do arquivo, não a extensão: só PDF, JPEG e PNG são aceitos, com até 10 MB. O mesmo tipo de documento pode ser enviado mais de uma vez.

Corpo da requisição (multipart/form-data)

document_typestringobrigatório

cnpj_cardsocial_contractid_documentaddress_proofbank_statement

Tipo do documento.

filefileobrigatório

Arquivo PDF, JPEG ou PNG, de até 10 MB.

201Documento recebido

json

{
  "message": "document uploaded",
  "document_type": "cnpj_card",
  "file_url": "/uploads/kyc-documents/94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36/5a1f0c9e.pdf"
}

Remover um documento

DELETE/api/v1/vendor/kyc/documents/{docId}Seller

Remove um documento ainda pendente

Apaga um documento que a equipe da loja ainda não analisou (P). Documento já aprovado ou recusado não pode ser removido.

Parâmetros de caminho

docIduuidobrigatório

Id do documento, o id dentro de documents.

200Documento removido

json

{ "message": "document deleted" }

Exemplo de requisição

bash

# 1. abrir o pedido
curl -X POST "$BASE_URL/api/v1/vendor/kyc/submit" \
  -H "Authorization: Bearer $TOKEN"

# 2. enviar um documento
curl -X POST "$BASE_URL/api/v1/vendor/kyc/documents" \
  -H "Authorization: Bearer $TOKEN" \
  -F "document_type=cnpj_card" \
  -F "file=@cartao-cnpj.pdf;type=application/pdf"

# 3. acompanhar
curl "$BASE_URL/api/v1/vendor/kyc" -H "Authorization: Bearer $TOKEN"

Erros

Status	Quando	Corpo de exemplo
400	Envio de documento sem ter aberto o pedido.	`{"error":"no KYC verification found ... submit for verification first"}`
400	Pedido fora de `pending` ou `rejected` ao enviar documento.	`{"error":"cannot upload documents while verification is O"}`
400	Formulário inválido ou maior que 10 MB.	`{"error":"failed to parse form (max 10MB)","detail":"..."}`
400	`document_type` ausente.	`{"error":"document_type is required"}`
400	`document_type` fora da lista.	`{"error":"invalid document_type","detail":"Valid types: cnpj_card, social_contract, id_document, address_proof, bank_statement"}`
400	`file` ausente.	`{"error":"file is required","detail":"..."}`
400	Arquivo que não é PDF, JPEG ou PNG.	`{"error":"unsupported file type","detail":"Accepted: PDF, JPG, PNG. Detected: text/plain; charset=utf-8"}`
400	`docId` não é UUID válido.	`{"error":"invalid docId","detail":"docId must be a valid UUID"}`
401	Sem token.	`{"error":"authentication required"}`
403	Módulo desligado na loja.	`{"error":"module_disabled","module":"vendor-kyc"}`
404	Usuário sem cadastro de seller.	`{"error":"vendor profile not found"}`
404	Remoção sem pedido de verificação.	`{"error":"no KYC verification found"}`
409	Já existe um pedido `pending` ou `in_review`.	`{"error":"failed to create verification","detail":"vendor already has an active KYC verification"}`
500	Remoção de documento inexistente ou já analisado.	`{"error":"failed to delete document","detail":"document not found or already reviewed"}`

Veja também

API atual/Referência completa/Perfil e verificação do seller

Verificação KYC

Abre o pedido de verificação de identidade do seller, envia e remove os documentos da empresa e consulta a situação da análise.

Só funcionam quando a loja ligou o módulo vendor-kyc. Sem ele, todas respondem 403 com {"error":"module_disabled","module":"vendor-kyc"}.

Abrir pedido→Enviar documentos→Em análise→Aprovada ou Recusada

Situações

Nas respostas, o status vem como letra de um caractere.

Letra	Nome	Significado
`P`	`pending`	Pedido aberto, aceita documentos.
`O`	`in_review`	A equipe da loja está analisando.
`A`	`approved`	Aprovado. Vale por 1 ano a partir da aprovação.
`R`	`rejected`	Recusado, veja `rejection_reason`.
`E`	`expired`	Vencido; é preciso refazer.

Os documentos têm P (pendente), A (aprovado) e R (recusado).

Tipos de documento (`document_type`)

Valor	Documento
`cnpj_card`	Cartão CNPJ
`social_contract`	Contrato social
`id_document`	Documento de identidade do responsável
`address_proof`	Comprovante de endereço
`bank_statement`	Extrato bancário

Consultar a situação

GET/api/v1/vendor/kycSeller

Situação da verificação e documentos enviados

Devolve a verificação mais recente do seller, seus documentos e se o seller está hoje verificado (aprovada e dentro da validade).

200Verificação encontrada

json

{
  "verification": {
    "id": "6c0a3b2e-4d5f-4a8e-9b1c-7e2f1a0b9c3d",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "status": "P",
    "submitted_at": "2026-10-11T20:00:00Z",
    "notes": "",
    "vendor_name": "Loja Seller Teste"
  },
  "documents": [
    {
      "id": "0b1c2d3e-4f50-4a61-8b72-93a4b5c6d7e8",
      "verification_id": "6c0a3b2e-4d5f-4a8e-9b1c-7e2f1a0b9c3d",
      "document_type": "cnpj_card",
      "file_name": "cartao-cnpj.pdf",
      "file_url": "/uploads/kyc-documents/94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36/5a1f0c9e.pdf",
      "status": "P",
      "uploaded_at": "2026-10-11T20:05:00Z"
    }
  ],
  "is_verified": false
}

200Nenhum pedido aberto ainda

json

{ "verification": null, "documents": [], "is_verified": false }

Campos da resposta

verificationobject

Verificação mais recente, ou null se o seller nunca abriu uma.

verification.iduuid

Id da verificação.

verification.statusstring

POARE

Situação, em letra.

verification.submitted_atstring

Quando o pedido foi aberto (RFC 3339).

verification.reviewed_atstring

Quando foi decidido. Ausente antes disso.

verification.expires_atstring

Validade da aprovação. Ausente antes de aprovar.

verification.rejection_reasonstring

Motivo da recusa, quando recusada.

verification.notesstring

Observações da equipe da loja.

documentsarray

Documentos do pedido, do mais antigo ao mais novo.

documents[].iduuid

Id do documento. É o docId da remoção.

documents[].document_typestring

cnpj_cardsocial_contractid_documentaddress_proofbank_statement

Tipo do documento.

documents[].file_namestring

Nome do arquivo enviado.

documents[].file_urlstring

Caminho do arquivo guardado.

documents[].statusstring

PAR

Situação do documento, em letra.

documents[].rejection_reasonstring

Motivo, se o documento foi recusado.

documents[].uploaded_atstring

Quando foi enviado (RFC 3339).

is_verifiedboolean

true só se há verificação aprovada e ainda válida.

Abrir o pedido

POST/api/v1/vendor/kyc/submitSeller

Abre um pedido de verificação KYC

201Pedido aberto

json

{
  "id": "6c0a3b2e-4d5f-4a8e-9b1c-7e2f1a0b9c3d",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "status": "P",
  "submitted_at": "2026-10-11T20:00:00Z",
  "notes": ""
}

Enviar um documento

POST/api/v1/vendor/kyc/documentsSeller

Envia um documento da empresa

Corpo da requisição (multipart/form-data)

document_typestringobrigatório

cnpj_cardsocial_contractid_documentaddress_proofbank_statement

Tipo do documento.

filefileobrigatório

Arquivo PDF, JPEG ou PNG, de até 10 MB.

201Documento recebido

json

{
  "message": "document uploaded",
  "document_type": "cnpj_card",
  "file_url": "/uploads/kyc-documents/94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36/5a1f0c9e.pdf"
}

Remover um documento

DELETE/api/v1/vendor/kyc/documents/{docId}Seller

Remove um documento ainda pendente

Apaga um documento que a equipe da loja ainda não analisou (P). Documento já aprovado ou recusado não pode ser removido.

Parâmetros de caminho

docIduuidobrigatório

Id do documento, o id dentro de documents.

200Documento removido

json

{ "message": "document deleted" }

Exemplo de requisição

bash

# 1. abrir o pedido
curl -X POST "$BASE_URL/api/v1/vendor/kyc/submit" \
  -H "Authorization: Bearer $TOKEN"

# 2. enviar um documento
curl -X POST "$BASE_URL/api/v1/vendor/kyc/documents" \
  -H "Authorization: Bearer $TOKEN" \
  -F "document_type=cnpj_card" \
  -F "file=@cartao-cnpj.pdf;type=application/pdf"

# 3. acompanhar
curl "$BASE_URL/api/v1/vendor/kyc" -H "Authorization: Bearer $TOKEN"

Erros

Status	Quando	Corpo de exemplo
400	Envio de documento sem ter aberto o pedido.	`{"error":"no KYC verification found ... submit for verification first"}`
400	Pedido fora de `pending` ou `rejected` ao enviar documento.	`{"error":"cannot upload documents while verification is O"}`
400	Formulário inválido ou maior que 10 MB.	`{"error":"failed to parse form (max 10MB)","detail":"..."}`
400	`document_type` ausente.	`{"error":"document_type is required"}`
400	`document_type` fora da lista.	`{"error":"invalid document_type","detail":"Valid types: cnpj_card, social_contract, id_document, address_proof, bank_statement"}`
400	`file` ausente.	`{"error":"file is required","detail":"..."}`
400	Arquivo que não é PDF, JPEG ou PNG.	`{"error":"unsupported file type","detail":"Accepted: PDF, JPG, PNG. Detected: text/plain; charset=utf-8"}`
400	`docId` não é UUID válido.	`{"error":"invalid docId","detail":"docId must be a valid UUID"}`
401	Sem token.	`{"error":"authentication required"}`
403	Módulo desligado na loja.	`{"error":"module_disabled","module":"vendor-kyc"}`
404	Usuário sem cadastro de seller.	`{"error":"vendor profile not found"}`
404	Remoção sem pedido de verificação.	`{"error":"no KYC verification found"}`
409	Já existe um pedido `pending` ou `in_review`.	`{"error":"failed to create verification","detail":"vendor already has an active KYC verification"}`
500	Remoção de documento inexistente ou já analisado.	`{"error":"failed to delete document","detail":"document not found or already reviewed"}`