API atual/Referência completa/Conta do seller

Cadastro de aprovação

Acompanha, abre e instrui com documentos o cadastro de premoderação do seller.

Antes de vender, um seller pode precisar passar por uma premoderação: a loja analisa o cadastro e os documentos (CNPJ, comprovantes) e aprova ou recusa. Estas três rotas deixam o seller acompanhar a situação, abrir o cadastro de análise e anexar documentos. A decisão é tomada pela equipe da loja, no painel do administrador.

GET/api/v1/vendor/applicationSeller

Ver a situação do cadastro

Devolve o cadastro mais recente do seller do token, com os documentos. Sem cadastro, responde 200 com status: not_started; é a chamada para decidir o que mostrar na tela de onboarding.

Cabeçalhos

Authorizationstringobrigatório

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

Exemplo de requisição

bash

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

Resposta

200Cadastro em análise

json

{
  "application": {
    "id": "e1b9a0c2-7d34-4f58-9c6a-0b8d2e5f1a73",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "vendor_name": "Loja Exemplo Ltda",
    "status": "under_review",
    "submitted_at": "2026-10-05T14:03:11Z",
    "documents": [
      {
        "id": "0f7c2d84-3a61-4b9e-8d25-6c1e9a4b7f30",
        "application_id": "e1b9a0c2-7d34-4f58-9c6a-0b8d2e5f1a73",
        "document_type": "cnpj",
        "file_url": "https://minhaloja.io.venddor.com.br/media/cnpj.pdf",
        "file_name": "cnpj.pdf",
        "status": "pending",
        "created_at": "2026-10-05T14:10:40Z"
      }
    ],
    "created_at": "2026-10-05T14:03:11Z",
    "updated_at": "2026-10-05T14:10:40Z"
  },
  "status": "under_review"
}

200Sem cadastro

json

{
  "application": null,
  "status": "not_started"
}

Campos da resposta

applicationobject

O cadastro, ou null quando ainda não existe.

application.iduuid

Id do cadastro (use em documents).

application.vendor_iduuid

Id do seller.

application.vendor_namestring

Nome da loja; pode vir vazio.

application.statusstring

pendingunder_reviewapprovedrejected

Situação do cadastro.

application.submitted_atstring

Quando foi enviado, RFC 3339 em UTC.

application.reviewed_atstring

Quando foi analisado. Ausente antes da decisão.

application.reviewed_bystring

Quem decidiu. Ausente antes da decisão.

application.rejection_reasonstring

Motivo da recusa, quando rejected.

application.notesstring

Observações da análise, quando houver.

application.documentsobject[]

Documentos anexados: id, application_id, document_type, file_url, file_name, status (pending, approved ou rejected), notes e created_at.

application.created_atstring

Criação do registro.

application.updated_atstring

Última alteração.

statusstring

Atalho: igual a application.status, ou not_started sem cadastro.

vendor_profile_requiredboolean

Presente e true quando o usuário ainda não tem um seller vinculado; peça à loja para criá-lo.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"invalid or expired token"}`
403	O token não é de usuário seller.	`{"error":"vendor access required"}`
500	Falha ao ler.	`{"error":"failed to get application","detail":"..."}`

POST/api/v1/vendor/applicationSeller

Enviar o cadastro para análise

Abre o cadastro de análise do seller do token. Não precisa de corpo (um vendor_id enviado é ignorado: o seller vem do token). É idempotente: se já existe um cadastro em aberto (pending ou under_review), devolve esse mesmo cadastro em vez de criar outro.

Cabeçalhos

Authorizationstringobrigatório

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

Exemplo de requisição

bash

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

Resposta

201Cadastro aberto

json

{
  "application": {
    "id": "e1b9a0c2-7d34-4f58-9c6a-0b8d2e5f1a73",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "vendor_name": "Loja Exemplo Ltda",
    "status": "pending",
    "submitted_at": "2026-10-05T14:03:11Z",
    "documents": null,
    "created_at": "2026-10-05T14:03:11Z",
    "updated_at": "2026-10-05T14:10:40Z"
  }
}

Os campos de application são os mesmos de Ver a situação do cadastro.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"invalid or expired token"}`
403	O usuário não tem seller vinculado.	`{"error":"no vendor account associated with this user"}`
500	Falha ao enviar.	`{"error":"failed to submit application","detail":"..."}`

POST/api/v1/vendor/application/{id}/documentsSeller

Anexar documento ao cadastro

Registra um documento no cadastro do próprio seller. O primeiro documento muda o cadastro de pending para under_review. O documento nasce com status pending até a análise.

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de caminho

iduuidobrigatório

Id do cadastro, o application.id devolvido acima.

Corpo da requisição

document_typestringobrigatório

business_licenseidentitytax_registrationproof_of_addressbank_statementothercnpjaddressbankid_cardcpf_cnpjcompany_registrationbank_infoaddress_prooftax_certificate

Tipo do documento.

file_urlstringobrigatório

URL do arquivo já enviado (por exemplo, pela rota de mídia do painel do seller). A plataforma guarda o endereço; não recebe o arquivo aqui.

file_namestringobrigatório

Nome do arquivo mostrado ao analista.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/application/e1b9a0c2-7d34-4f58-9c6a-0b8d2e5f1a73/documents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "document_type": "cnpj",
  "file_url": "https://minhaloja.io.venddor.com.br/media/cnpj.pdf",
  "file_name": "cnpj.pdf"
}'

Resposta

201Documento anexado

json

{
  "message": "document added",
  "application_id": "e1b9a0c2-7d34-4f58-9c6a-0b8d2e5f1a73",
  "document_type": "cnpj"
}

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"invalid or expired token"}`
400	Falta `document_type`, `file_url` ou `file_name`.	`{"error":"document_type, file_url, and file_name are required"}`
403	O usuário não tem seller vinculado.	`{"error":"no vendor account associated with this user"}`
404	O cadastro não existe ou não é do seller do token.	`{"error":"application not found"}`
500	Falha ao anexar, inclusive quando `document_type` não é um dos valores aceitos.	`{"error":"failed to add document","detail":"invalid document type \"foto\""}`

Veja também

Cadastro de aprovação

Acompanha, abre e instrui com documentos o cadastro de premoderação do seller.

GET/api/v1/vendor/applicationSeller

Ver a situação do cadastro

Devolve o cadastro mais recente do seller do token, com os documentos. Sem cadastro, responde 200 com status: not_started; é a chamada para decidir o que mostrar na tela de onboarding.

Cabeçalhos

Authorizationstringobrigatório

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

Exemplo de requisição

bash

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

Resposta

200Cadastro em análise

json

{
  "application": {
    "id": "e1b9a0c2-7d34-4f58-9c6a-0b8d2e5f1a73",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "vendor_name": "Loja Exemplo Ltda",
    "status": "under_review",
    "submitted_at": "2026-10-05T14:03:11Z",
    "documents": [
      {
        "id": "0f7c2d84-3a61-4b9e-8d25-6c1e9a4b7f30",
        "application_id": "e1b9a0c2-7d34-4f58-9c6a-0b8d2e5f1a73",
        "document_type": "cnpj",
        "file_url": "https://minhaloja.io.venddor.com.br/media/cnpj.pdf",
        "file_name": "cnpj.pdf",
        "status": "pending",
        "created_at": "2026-10-05T14:10:40Z"
      }
    ],
    "created_at": "2026-10-05T14:03:11Z",
    "updated_at": "2026-10-05T14:10:40Z"
  },
  "status": "under_review"
}

200Sem cadastro

json

{
  "application": null,
  "status": "not_started"
}

Campos da resposta

applicationobject

O cadastro, ou null quando ainda não existe.

application.iduuid

Id do cadastro (use em documents).

application.vendor_iduuid

Id do seller.

application.vendor_namestring

Nome da loja; pode vir vazio.

application.statusstring

pendingunder_reviewapprovedrejected

Situação do cadastro.

application.submitted_atstring

Quando foi enviado, RFC 3339 em UTC.

application.reviewed_atstring

Quando foi analisado. Ausente antes da decisão.

application.reviewed_bystring

Quem decidiu. Ausente antes da decisão.

application.rejection_reasonstring

Motivo da recusa, quando rejected.

application.notesstring

Observações da análise, quando houver.

application.documentsobject[]

Documentos anexados: id, application_id, document_type, file_url, file_name, status (pending, approved ou rejected), notes e created_at.

application.created_atstring

Criação do registro.

application.updated_atstring

Última alteração.

statusstring

Atalho: igual a application.status, ou not_started sem cadastro.

vendor_profile_requiredboolean

Presente e true quando o usuário ainda não tem um seller vinculado; peça à loja para criá-lo.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"invalid or expired token"}`
403	O token não é de usuário seller.	`{"error":"vendor access required"}`
500	Falha ao ler.	`{"error":"failed to get application","detail":"..."}`

POST/api/v1/vendor/applicationSeller

Enviar o cadastro para análise

Cabeçalhos

Authorizationstringobrigatório

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

Exemplo de requisição

bash

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

Resposta

201Cadastro aberto

json

{
  "application": {
    "id": "e1b9a0c2-7d34-4f58-9c6a-0b8d2e5f1a73",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "vendor_name": "Loja Exemplo Ltda",
    "status": "pending",
    "submitted_at": "2026-10-05T14:03:11Z",
    "documents": null,
    "created_at": "2026-10-05T14:03:11Z",
    "updated_at": "2026-10-05T14:10:40Z"
  }
}

Os campos de application são os mesmos de Ver a situação do cadastro.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"invalid or expired token"}`
403	O usuário não tem seller vinculado.	`{"error":"no vendor account associated with this user"}`
500	Falha ao enviar.	`{"error":"failed to submit application","detail":"..."}`

POST/api/v1/vendor/application/{id}/documentsSeller

Anexar documento ao cadastro

Registra um documento no cadastro do próprio seller. O primeiro documento muda o cadastro de pending para under_review. O documento nasce com status pending até a análise.

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de caminho

iduuidobrigatório

Id do cadastro, o application.id devolvido acima.

Corpo da requisição

document_typestringobrigatório

business_licenseidentitytax_registrationproof_of_addressbank_statementothercnpjaddressbankid_cardcpf_cnpjcompany_registrationbank_infoaddress_prooftax_certificate

Tipo do documento.

file_urlstringobrigatório

URL do arquivo já enviado (por exemplo, pela rota de mídia do painel do seller). A plataforma guarda o endereço; não recebe o arquivo aqui.

file_namestringobrigatório

Nome do arquivo mostrado ao analista.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/application/e1b9a0c2-7d34-4f58-9c6a-0b8d2e5f1a73/documents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "document_type": "cnpj",
  "file_url": "https://minhaloja.io.venddor.com.br/media/cnpj.pdf",
  "file_name": "cnpj.pdf"
}'

Resposta

201Documento anexado

json

{
  "message": "document added",
  "application_id": "e1b9a0c2-7d34-4f58-9c6a-0b8d2e5f1a73",
  "document_type": "cnpj"
}

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"invalid or expired token"}`
400	Falta `document_type`, `file_url` ou `file_name`.	`{"error":"document_type, file_url, and file_name are required"}`
403	O usuário não tem seller vinculado.	`{"error":"no vendor account associated with this user"}`
404	O cadastro não existe ou não é do seller do token.	`{"error":"application not found"}`
500	Falha ao anexar, inclusive quando `document_type` não é um dos valores aceitos.	`{"error":"failed to add document","detail":"invalid document type \"foto\""}`