API atual/Referência completa/Cadastro de sellers

Candidaturas de sellers

Lista as candidaturas de lojistas e aprova ou recusa cada uma, ativando ou recusando o seller.

A candidatura é o pedido de um seller para vender na loja. Estas duas operações montam a fila de análise e registram a decisão. Exigem o módulo vendor-moderation. Ler pede manage_vendor_moderation, manage_catalog ou view_catalog; decidir pede manage_vendor_moderation ou manage_catalog.

Listar candidaturas

Devolve as candidaturas, da mais recente para a mais antiga, sem paginação. Cada item traz o nome do seller, mas não os documentos.

GET/api/v1/admin/vendor-applicationsAdmin

Lista as candidaturas de sellers

Parâmetros de consulta

statusstring

pendingunder_reviewapprovedrejectedall

Filtra por estado. all ou ausente lista todas. Um valor desconhecido devolve lista vazia.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/vendor-applications?status=pending" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Candidaturas retornadas

json

{
  "applications": [
    {
      "id": "054c2645-ad96-4556-9606-7535b372f0b1",
      "vendor_id": "ce822da6-5869-4819-b8bb-9aefd2e62925",
      "vendor_name": "Loja do Zé Ltda",
      "status": "rejected",
      "submitted_at": "2026-05-26T17:29:43.791755Z",
      "reviewed_at": "2026-07-11T14:12:29.600924Z",
      "reviewed_by": "67bf291c-0846-4053-9528-8cfd5ab0ebf1",
      "rejection_reason": "Documentação incompleta, favor reenviar o CNPJ.",
      "created_at": "2026-05-26T17:29:43.791755Z",
      "updated_at": "2026-07-11T14:12:29.600924Z"
    }
  ],
  "total": 1
}

Campos da resposta

applicationsarray

Candidaturas. Vazio ([]) quando nenhuma casa.

totalinteger

Quantidade devolvida.

applications[].iduuid

Id da candidatura.

applications[].vendor_iduuid

Seller candidato.

applications[].vendor_namestring

Razão social do seller. Pode ser vazio.

applications[].statusstring

pendingunder_reviewapprovedrejected

Estado da candidatura.

applications[].submitted_atstring

Envio, RFC 3339 em UTC.

applications[].reviewed_atstring

Decisão, RFC 3339. Ausente antes da decisão.

applications[].reviewed_byuuid

Administrador que decidiu. Ausente antes da decisão.

applications[].rejection_reasonstring

Motivo da recusa. Ausente se não houve.

applications[].notesstring

Observações. Ausente se vazio.

applications[].created_atstring

Criação, RFC 3339 em UTC.

applications[].updated_atstring

Última alteração, RFC 3339 em UTC.

Erros

Status	Quando	Corpo
401 / 403	Sem token, sem privilégio, ou módulo desligado	`{"error":"module_disabled","module":"vendor-moderation"}`
500	Falha interna	`{"error":"failed to list vendor applications","detail":"..."}`

Decidir uma candidatura

Aprova ou recusa. Ao aprovar, o seller é ativado e pode vender. Ao recusar, o seller é marcado como recusado e o reason fica guardado. A decisão fica registrada com o administrador e a data.

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

Aprova ou recusa uma candidatura

Parâmetros de caminho

iduuidobrigatório

Id da candidatura (o id da lista, não o vendor_id).

Corpo da requisição

decisionstringobrigatório

approvedrejected

Decisão.

reasonstring

Motivo. Gravado como rejection_reason; sempre que informado, mesmo numa aprovação.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/vendor-applications/054c2645-ad96-4556-9606-7535b372f0b1/review" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"decision": "rejected", "reason": "Documentação incompleta, favor reenviar o CNPJ."}'

Resposta

200Candidatura decidida

json

{
  "message": "application reviewed",
  "application_id": "054c2645-ad96-4556-9606-7535b372f0b1",
  "decision": "rejected"
}

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	`decision` diferente de `approved` e `rejected`	`{"error":"decision must be 'approved' or 'rejected'"}`
500	Candidatura inexistente (deveria ser 404)	`{"error":"failed to review application","detail":"application 0000... not found"}`
500	`id` que não é UUID, ou falha ao ativar ou recusar o seller	`{"error":"failed to review application","detail":"..."}`
401 / 403	Sem token, sem privilégio, ou módulo desligado	`{"error":"module_disabled","module":"vendor-moderation"}`

Veja também

API atual/Referência completa/Cadastro de sellers

Candidaturas de sellers

Lista as candidaturas de lojistas e aprova ou recusa cada uma, ativando ou recusando o seller.

Listar candidaturas

Devolve as candidaturas, da mais recente para a mais antiga, sem paginação. Cada item traz o nome do seller, mas não os documentos.

GET/api/v1/admin/vendor-applicationsAdmin

Lista as candidaturas de sellers

Parâmetros de consulta

statusstring

pendingunder_reviewapprovedrejectedall

Filtra por estado. all ou ausente lista todas. Um valor desconhecido devolve lista vazia.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/vendor-applications?status=pending" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Candidaturas retornadas

json

{
  "applications": [
    {
      "id": "054c2645-ad96-4556-9606-7535b372f0b1",
      "vendor_id": "ce822da6-5869-4819-b8bb-9aefd2e62925",
      "vendor_name": "Loja do Zé Ltda",
      "status": "rejected",
      "submitted_at": "2026-05-26T17:29:43.791755Z",
      "reviewed_at": "2026-07-11T14:12:29.600924Z",
      "reviewed_by": "67bf291c-0846-4053-9528-8cfd5ab0ebf1",
      "rejection_reason": "Documentação incompleta, favor reenviar o CNPJ.",
      "created_at": "2026-05-26T17:29:43.791755Z",
      "updated_at": "2026-07-11T14:12:29.600924Z"
    }
  ],
  "total": 1
}

Campos da resposta

applicationsarray

Candidaturas. Vazio ([]) quando nenhuma casa.

totalinteger

Quantidade devolvida.

applications[].iduuid

Id da candidatura.

applications[].vendor_iduuid

Seller candidato.

applications[].vendor_namestring

Razão social do seller. Pode ser vazio.

applications[].statusstring

pendingunder_reviewapprovedrejected

Estado da candidatura.

applications[].submitted_atstring

Envio, RFC 3339 em UTC.

applications[].reviewed_atstring

Decisão, RFC 3339. Ausente antes da decisão.

applications[].reviewed_byuuid

Administrador que decidiu. Ausente antes da decisão.

applications[].rejection_reasonstring

Motivo da recusa. Ausente se não houve.

applications[].notesstring

Observações. Ausente se vazio.

applications[].created_atstring

Criação, RFC 3339 em UTC.

applications[].updated_atstring

Última alteração, RFC 3339 em UTC.

Erros

Status	Quando	Corpo
401 / 403	Sem token, sem privilégio, ou módulo desligado	`{"error":"module_disabled","module":"vendor-moderation"}`
500	Falha interna	`{"error":"failed to list vendor applications","detail":"..."}`

Decidir uma candidatura

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

Aprova ou recusa uma candidatura

Parâmetros de caminho

iduuidobrigatório

Id da candidatura (o id da lista, não o vendor_id).

Corpo da requisição

decisionstringobrigatório

approvedrejected

Decisão.

reasonstring

Motivo. Gravado como rejection_reason; sempre que informado, mesmo numa aprovação.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/vendor-applications/054c2645-ad96-4556-9606-7535b372f0b1/review" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"decision": "rejected", "reason": "Documentação incompleta, favor reenviar o CNPJ."}'

Resposta

200Candidatura decidida

json

{
  "message": "application reviewed",
  "application_id": "054c2645-ad96-4556-9606-7535b372f0b1",
  "decision": "rejected"
}

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	`decision` diferente de `approved` e `rejected`	`{"error":"decision must be 'approved' or 'rejected'"}`
500	Candidatura inexistente (deveria ser 404)	`{"error":"failed to review application","detail":"application 0000... not found"}`
500	`id` que não é UUID, ou falha ao ativar ou recusar o seller	`{"error":"failed to review application","detail":"..."}`
401 / 403	Sem token, sem privilégio, ou módulo desligado	`{"error":"module_disabled","module":"vendor-moderation"}`