API atual/Referência completa/Sellers (lojistas)

Listar sellers e checar slug

Lista os sellers com filtros, ordenação e contagem por status, e confere se um slug está livre antes de salvar.

Listar sellers

Devolve os sellers não excluídos, com os campos usados em tabelas do painel (não o cadastro completo: para isso use Consultar seller). Inclui a contagem de produtos de cada um.

GET/api/v1/admin/vendorsAdmin

Lista os sellers da loja

Parâmetros de consulta

statusstring

pendingactivesuspendedrejectedPADR

Filtra pelo status. Aceita a palavra ou a letra.

searchstring

Parte da razão social ou do e-mail, sem diferenciar maiúsculas.

citystring

Parte do nome da cidade.

statestring

Sigla do estado, exata (SP).

created_fromstring

Cadastrados a partir desta data (YYYY-MM-DD). Data inválida é ignorada.

created_tostring

Cadastrados até esta data, inclusive (YYYY-MM-DD).

sort_bystringpadrão: created_at

created_atcompany_nameemailcommission_rateproduct_count

Campo de ordenação. Outro valor volta a created_at.

sort_dirstringpadrão: desc

ascdesc

Direção. Qualquer valor diferente de asc é desc.

pageintegerpadrão: 1

Página, a partir de 1.

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/vendors?status=active&per_page=20&sort_by=company_name&sort_dir=asc" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Sellers

json

{
  "vendors": [
    {
      "id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
      "display_id": 274,
      "user_id": "a1a25b87-5e32-4439-b3df-f98eb03b6434",
      "company_name": "Loja Otávio",
      "slug": "loja-ot-vio-2",
      "status": "A",
      "email": "contato@lojaotavio.example.com",
      "commission_rate": 10,
      "commission_type": "percentage",
      "payment_model": "marketplace_collects",
      "fulfillment_type": "vendor_fulfilled",
      "product_count": 0,
      "is_system": false,
      "created_at": "2026-09-15T14:20:06Z",
      "updated_at": "2026-09-15T19:00:17Z",
      "company_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
      "company": "Loja Otávio",
      "timestamp": 1789482006
    }
  ],
  "total": 12,
  "page": 1,
  "per_page": 20,
  "total_pages": 1,
  "status_counts": { "active": 12 }
}

Campos da resposta

vendorsarray

Sellers da página.

vendors[].iduuid

Id do seller.

vendors[].display_idinteger

Número sequencial amigável (para telas, não é chave).

vendors[].user_iduuid

Usuário dono. Ausente se o seller não tem login.

vendors[].company_namestring

Nome fantasia.

vendors[].slugstring

Slug da vitrine.

vendors[].statusstring

PADR

Status em letra.

vendors[].emailstring

E-mail do seller.

vendors[].commission_ratenumber

Comissão em percentual (10 = 10%).

vendors[].commission_typestring

Sempre percentage.

vendors[].payment_modelstring

marketplace_collectsdirect_to_vendor

Quem recebe o pagamento.

vendors[].fulfillment_typestring

vendor_fulfilledmarketplace_fulfilled

Quem despacha.

vendors[].product_countinteger

Produtos do seller.

vendors[].is_systemboolean

true no seller interno da própria loja.

vendors[].created_atstring

Cadastro (RFC 3339, UTC).

vendors[].updated_atstring

Última alteração.

vendors[].company_iduuid

Cópia de id (campo duplicado).

vendors[].companystring

Cópia de company_name (campo duplicado).

vendors[].timestampinteger

Cadastro em Unix (segundos).

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 status, com a palavra como chave (active, pending...). Só aparecem os status que existem.

Checar um slug

Diz se um slug pode ser usado, antes de você salvar o seller. Faz a mesma validação de formato e de nomes reservados da criação.

GET/api/v1/admin/vendors/check-slugAdmin

Confere se um slug está livre

Parâmetros de consulta

slugstringobrigatório

Slug a conferir.

excludeuuid

Id do seller em edição. O slug atual dele conta como livre.

200Slug livre

json

{ "available": true }

Campos da resposta

availableboolean

true quando o slug pode ser usado.

reasonstring

formatreservedtaken

Presente quando available é false: format (fora do padrão ou do tamanho), reserved (nome protegido, como admin) ou taken (outro seller, inclusive excluído, já usa).

Erros

Status	Quando	Corpo de exemplo
400	`check-slug` sem `slug`.	`{"error":"slug query param is required"}`
401	Sem token.	`{"error":"missing authorization header"}`
403	Sem `view_vendors`/`manage_vendors`.	`{"error":"..."}`
500	Falha ao consultar.	`{"error":"failed to list vendors","detail":"..."}`

Veja também

Listar sellers e checar slug

Lista os sellers com filtros, ordenação e contagem por status, e confere se um slug está livre antes de salvar.

Listar sellers

Devolve os sellers não excluídos, com os campos usados em tabelas do painel (não o cadastro completo: para isso use Consultar seller). Inclui a contagem de produtos de cada um.

GET/api/v1/admin/vendorsAdmin

Lista os sellers da loja

Parâmetros de consulta

statusstring

pendingactivesuspendedrejectedPADR

Filtra pelo status. Aceita a palavra ou a letra.

searchstring

Parte da razão social ou do e-mail, sem diferenciar maiúsculas.

citystring

Parte do nome da cidade.

statestring

Sigla do estado, exata (SP).

created_fromstring

Cadastrados a partir desta data (YYYY-MM-DD). Data inválida é ignorada.

created_tostring

Cadastrados até esta data, inclusive (YYYY-MM-DD).

sort_bystringpadrão: created_at

created_atcompany_nameemailcommission_rateproduct_count

Campo de ordenação. Outro valor volta a created_at.

sort_dirstringpadrão: desc

ascdesc

Direção. Qualquer valor diferente de asc é desc.

pageintegerpadrão: 1

Página, a partir de 1.

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/vendors?status=active&per_page=20&sort_by=company_name&sort_dir=asc" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Sellers

json

{
  "vendors": [
    {
      "id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
      "display_id": 274,
      "user_id": "a1a25b87-5e32-4439-b3df-f98eb03b6434",
      "company_name": "Loja Otávio",
      "slug": "loja-ot-vio-2",
      "status": "A",
      "email": "contato@lojaotavio.example.com",
      "commission_rate": 10,
      "commission_type": "percentage",
      "payment_model": "marketplace_collects",
      "fulfillment_type": "vendor_fulfilled",
      "product_count": 0,
      "is_system": false,
      "created_at": "2026-09-15T14:20:06Z",
      "updated_at": "2026-09-15T19:00:17Z",
      "company_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
      "company": "Loja Otávio",
      "timestamp": 1789482006
    }
  ],
  "total": 12,
  "page": 1,
  "per_page": 20,
  "total_pages": 1,
  "status_counts": { "active": 12 }
}

Campos da resposta

vendorsarray

Sellers da página.

vendors[].iduuid

Id do seller.

vendors[].display_idinteger

Número sequencial amigável (para telas, não é chave).

vendors[].user_iduuid

Usuário dono. Ausente se o seller não tem login.

vendors[].company_namestring

Nome fantasia.

vendors[].slugstring

Slug da vitrine.

vendors[].statusstring

PADR

Status em letra.

vendors[].emailstring

E-mail do seller.

vendors[].commission_ratenumber

Comissão em percentual (10 = 10%).

vendors[].commission_typestring

Sempre percentage.

vendors[].payment_modelstring

marketplace_collectsdirect_to_vendor

Quem recebe o pagamento.

vendors[].fulfillment_typestring

vendor_fulfilledmarketplace_fulfilled

Quem despacha.

vendors[].product_countinteger

Produtos do seller.

vendors[].is_systemboolean

true no seller interno da própria loja.

vendors[].created_atstring

Cadastro (RFC 3339, UTC).

vendors[].updated_atstring

Última alteração.

vendors[].company_iduuid

Cópia de id (campo duplicado).

vendors[].companystring

Cópia de company_name (campo duplicado).

vendors[].timestampinteger

Cadastro em Unix (segundos).

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 status, com a palavra como chave (active, pending...). Só aparecem os status que existem.

Checar um slug

Diz se um slug pode ser usado, antes de você salvar o seller. Faz a mesma validação de formato e de nomes reservados da criação.

GET/api/v1/admin/vendors/check-slugAdmin

Confere se um slug está livre

Parâmetros de consulta

slugstringobrigatório

Slug a conferir.

excludeuuid

Id do seller em edição. O slug atual dele conta como livre.

200Slug livre

json

{ "available": true }

Campos da resposta

availableboolean

true quando o slug pode ser usado.

reasonstring

formatreservedtaken

Presente quando available é false: format (fora do padrão ou do tamanho), reserved (nome protegido, como admin) ou taken (outro seller, inclusive excluído, já usa).

Erros

Status	Quando	Corpo de exemplo
400	`check-slug` sem `slug`.	`{"error":"slug query param is required"}`
401	Sem token.	`{"error":"missing authorization header"}`
403	Sem `view_vendors`/`manage_vendors`.	`{"error":"..."}`
500	Falha ao consultar.	`{"error":"failed to list vendors","detail":"..."}`