API atual/Referência completa/Plano e documentos

Documentos de cadastro

Lista, envia e apaga os documentos que o seller manda para a loja analisar.

Estas rotas só funcionam com o módulo vendor-kyc ligado na loja. Quem revisa os documentos é o administrador; o seller só envia e acompanha o status.

Listar documentos

Devolve todos os documentos enviados pelo seller, do mais novo para o mais antigo.

GET/api/v1/vendor/documentsSeller

Listar documentos

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/vendor/documents" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Documentos

json

{
  "documents": [
    {
      "id": "c3d4e5f6-0a1b-4c2d-8e3f-4a5b6c7d8e9f",
      "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/1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b.pdf",
      "file_size": 183204,
      "status": "P",
      "notes": "Cartão CNPJ atualizado",
      "created_at": "2026-10-11T22:40:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

documentsobject[]

Os documentos.

iduuid

Id do documento (UUID).

vendor_iduuid

Seller (UUID).

doc_typestring

Tipo do documento.

file_namestring

Nome do arquivo enviado, já limpo de caminhos.

file_urlstring

Caminho do arquivo guardado.

file_sizeinteger

Tamanho em bytes.

statusstring

PAR

P pendente, A aprovado, R rejeitado.

notesstring

Observação do seller.

review_notesstring

Observação da análise. Ausente antes da revisão.

reviewed_atstring

Quando foi revisado. Ausente antes da revisão.

reviewed_bystring

Quem revisou. Ausente antes da revisão.

created_atstring

Envio, RFC 3339 em UTC.

totalinteger

Quantidade.

Erros

Status	Quando	Corpo de exemplo
404	Usuário sem seller vinculado.	`{"error":"vendor profile not found"}`
403	O módulo `vendor-kyc` está desligado nesta loja.	`{"error":"module_disabled","module":"vendor-kyc"}`
401	Token ausente, inválido, expirado ou revogado.	`invalid or expired token`
403	O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.	`{"error":"vendor_pending_review"}`

Enviar documento

Envia um arquivo com seu tipo. O arquivo é conferido pelo conteúdo: PDF, JPEG, PNG ou WebP, até 10 MB. O documento nasce com status: P.

POST/api/v1/vendor/documentsSeller

Enviar documento

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Corpo da requisição

filefileobrigatório

O arquivo.

doc_typestringobrigatório

cnpjidentityid_cardbusiness_licensetax_registrationaddressproof_of_addressbankother

Tipo do documento. Use um dos listados. Os tipos cpf_cnpj, company_registration, bank_info, address_proof, tax_certificate e bank_statement passam pela validação do código, mas o banco de dados só aceita os listados aqui e responde 500 aos demais.

notesstring

Observação opcional para quem vai revisar.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/documents" \
  -H "Authorization: Bearer $TOKEN" \
  -F "doc_type=cnpj" \
  -F "notes=Cartão CNPJ atualizado" \
  -F "file=@cartao-cnpj.pdf;type=application/pdf"

Resposta

201Documento recebido

json

{
  "id": "c3d4e5f6-0a1b-4c2d-8e3f-4a5b6c7d8e9f",
  "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/1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b.pdf",
  "file_size": 183204,
  "status": "P",
  "notes": "Cartão CNPJ atualizado",
  "created_at": "2026-10-11T22:40:00Z"
}

Campos da resposta

(campos / fields)object

Os mesmos de Listar documentos.

Erros

Status	Quando	Corpo de exemplo
400	Não é `multipart` válido ou passa de 10 MB; `doc_type` ausente; `file` ausente; tipo de arquivo não aceito.	`{"error":"unsupported file type","detail":"Accepted types: PDF, JPG, PNG, WebP. Detected: text/plain; charset=utf-8"}`
404	Usuário sem seller vinculado.	`{"error":"vendor profile not found"}`
500	`doc_type` fora da lista (hoje volta `500`, não `400`) ou falha ao gravar.	`{"error":"failed to store document metadata","detail":"invalid document type \"foo\""}`
403	O módulo `vendor-kyc` está desligado nesta loja.	`{"error":"module_disabled","module":"vendor-kyc"}`
401	Token ausente, inválido, expirado ou revogado.	`invalid or expired token`
403	O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.	`{"error":"vendor_pending_review"}`

Apagar documento

Apaga um documento que ainda não foi revisado. Documentos aprovados ou rejeitados ficam como registro e não podem ser apagados pelo seller.

DELETE/api/v1/vendor/documents/{id}Seller

Apagar documento

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

iduuidobrigatório

Id do documento (UUID).

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/vendor/documents/c3d4e5f6-0a1b-4c2d-8e3f-4a5b6c7d8e9f" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Apagado

json

{
  "message": "document deleted"
}

Erros

Status	Quando	Corpo de exemplo
404	Usuário sem seller vinculado.	`{"error":"vendor profile not found"}`
500	Documento inexistente, de outro seller ou já revisado. Hoje a API responde `500` nestes casos, não `404`.	`{"error":"failed to delete document","detail":"document not found or already reviewed"}`
403	O módulo `vendor-kyc` está desligado nesta loja.	`{"error":"module_disabled","module":"vendor-kyc"}`
401	Token ausente, inválido, expirado ou revogado.	`invalid or expired token`
403	O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.	`{"error":"vendor_pending_review"}`

Veja também

API atual/Referência completa/Plano e documentos

Documentos de cadastro

Lista, envia e apaga os documentos que o seller manda para a loja analisar.

Estas rotas só funcionam com o módulo vendor-kyc ligado na loja. Quem revisa os documentos é o administrador; o seller só envia e acompanha o status.

Listar documentos

Devolve todos os documentos enviados pelo seller, do mais novo para o mais antigo.

GET/api/v1/vendor/documentsSeller

Listar documentos

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/vendor/documents" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Documentos

json

{
  "documents": [
    {
      "id": "c3d4e5f6-0a1b-4c2d-8e3f-4a5b6c7d8e9f",
      "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/1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b.pdf",
      "file_size": 183204,
      "status": "P",
      "notes": "Cartão CNPJ atualizado",
      "created_at": "2026-10-11T22:40:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

documentsobject[]

Os documentos.

iduuid

Id do documento (UUID).

vendor_iduuid

Seller (UUID).

doc_typestring

Tipo do documento.

file_namestring

Nome do arquivo enviado, já limpo de caminhos.

file_urlstring

Caminho do arquivo guardado.

file_sizeinteger

Tamanho em bytes.

statusstring

PAR

P pendente, A aprovado, R rejeitado.

notesstring

Observação do seller.

review_notesstring

Observação da análise. Ausente antes da revisão.

reviewed_atstring

Quando foi revisado. Ausente antes da revisão.

reviewed_bystring

Quem revisou. Ausente antes da revisão.

created_atstring

Envio, RFC 3339 em UTC.

totalinteger

Quantidade.

Erros

Status	Quando	Corpo de exemplo
404	Usuário sem seller vinculado.	`{"error":"vendor profile not found"}`
403	O módulo `vendor-kyc` está desligado nesta loja.	`{"error":"module_disabled","module":"vendor-kyc"}`
401	Token ausente, inválido, expirado ou revogado.	`invalid or expired token`
403	O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.	`{"error":"vendor_pending_review"}`

Enviar documento

Envia um arquivo com seu tipo. O arquivo é conferido pelo conteúdo: PDF, JPEG, PNG ou WebP, até 10 MB. O documento nasce com status: P.

POST/api/v1/vendor/documentsSeller

Enviar documento

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Corpo da requisição

filefileobrigatório

O arquivo.

doc_typestringobrigatório

cnpjidentityid_cardbusiness_licensetax_registrationaddressproof_of_addressbankother

notesstring

Observação opcional para quem vai revisar.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/documents" \
  -H "Authorization: Bearer $TOKEN" \
  -F "doc_type=cnpj" \
  -F "notes=Cartão CNPJ atualizado" \
  -F "file=@cartao-cnpj.pdf;type=application/pdf"

Resposta

201Documento recebido

json

{
  "id": "c3d4e5f6-0a1b-4c2d-8e3f-4a5b6c7d8e9f",
  "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/1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b.pdf",
  "file_size": 183204,
  "status": "P",
  "notes": "Cartão CNPJ atualizado",
  "created_at": "2026-10-11T22:40:00Z"
}

Campos da resposta

(campos / fields)object

Os mesmos de Listar documentos.

Erros

Status	Quando	Corpo de exemplo
400	Não é `multipart` válido ou passa de 10 MB; `doc_type` ausente; `file` ausente; tipo de arquivo não aceito.	`{"error":"unsupported file type","detail":"Accepted types: PDF, JPG, PNG, WebP. Detected: text/plain; charset=utf-8"}`
404	Usuário sem seller vinculado.	`{"error":"vendor profile not found"}`
500	`doc_type` fora da lista (hoje volta `500`, não `400`) ou falha ao gravar.	`{"error":"failed to store document metadata","detail":"invalid document type \"foo\""}`
403	O módulo `vendor-kyc` está desligado nesta loja.	`{"error":"module_disabled","module":"vendor-kyc"}`
401	Token ausente, inválido, expirado ou revogado.	`invalid or expired token`
403	O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.	`{"error":"vendor_pending_review"}`

Apagar documento

Apaga um documento que ainda não foi revisado. Documentos aprovados ou rejeitados ficam como registro e não podem ser apagados pelo seller.

DELETE/api/v1/vendor/documents/{id}Seller

Apagar documento

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

iduuidobrigatório

Id do documento (UUID).

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/vendor/documents/c3d4e5f6-0a1b-4c2d-8e3f-4a5b6c7d8e9f" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Apagado

json

{
  "message": "document deleted"
}

Erros

Status	Quando	Corpo de exemplo
404	Usuário sem seller vinculado.	`{"error":"vendor profile not found"}`
500	Documento inexistente, de outro seller ou já revisado. Hoje a API responde `500` nestes casos, não `404`.	`{"error":"failed to delete document","detail":"document not found or already reviewed"}`
403	O módulo `vendor-kyc` está desligado nesta loja.	`{"error":"module_disabled","module":"vendor-kyc"}`
401	Token ausente, inválido, expirado ou revogado.	`invalid or expired token`
403	O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.	`{"error":"vendor_pending_review"}`