API atual/Referência completa/Sellers e microsites

Listar sellers

Devolve o diretório público de sellers, paginado, com busca por nome e filtro por cidade e estado.

Use para montar a página "Nossos lojistas" ou um seletor de seller. A lista omite sellers de sistema (contas internas da plataforma), ocultos ou restritos a outro grupo de clientes e, se a loja filtra por região de entrega, os que não entregam ao cliente.

GET/api/v1/storefront/vendorsPública

Lista os sellers da loja

Devolve uma página do diretório de sellers ativos, do mais novo para o mais antigo (padrão). Não exige token.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageinteger

Itens por página, de 1 a 100. Fora desse intervalo volta ao padrão de 20 (não é limitado). Sem o parâmetro, vale o tamanho de página configurado pela loja para o diretório (12 se nada foi configurado).

searchstring

Parte do nome do seller, sem diferenciar maiúsculas.

citystring

Cidade, igualdade exata (Rio de Janeiro).

statestring

UF, igualdade exata (RJ).

sort_bystringpadrão: created_at

created_atcompany_name

Campo de ordenação. Outro valor cai em created_at.

sort_dirstringpadrão: desc

ascdesc

Direção. Qualquer valor diferente de asc ordena de forma decrescente.

statusstring

Situação do seller. Por padrão só os ativos; não use para outra coisa na vitrine.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/vendors?per_page=12&sort_by=company_name&sort_dir=asc"

Resposta

200Página de sellers

json

{
  "vendors": [
    {
      "id": "c0000000-0000-0000-0000-000000000002",
      "display_id": 1,
      "company_name": "Moda Carioca",
      "slug": "moda-carioca",
      "logo_url": "https://cdn.example.com/moda-carioca/logo.png",
      "banner_url": "https://cdn.example.com/moda-carioca/banner.jpg",
      "description": "A melhor moda do Rio de Janeiro para você.",
      "city": "Rio de Janeiro",
      "state": "RJ",
      "product_count": 128,
      "min_order_amount": 15000,
      "is_on_vacation": false,
      "created_at": "2026-03-06T10:25:37.86958Z"
    }
  ],
  "total": 11,
  "page": 1,
  "per_page": 12,
  "total_pages": 1
}

Campos da resposta

vendorsobject[]

Os sellers da página. Vazio ([]) quando nenhum atende ao filtro.

vendors[].iduuid

Id do seller.

vendors[].display_idinteger

Número curto sequencial, para exibir no lugar do UUID. Ausente se não existir.

vendors[].company_namestring

Nome fantasia, o que a vitrine mostra.

vendors[].slugstring

Nome do seller para URLs.

vendors[].logo_urlstring

URL do logotipo. Ausente se não houver.

vendors[].banner_urlstring

URL do banner. Ausente se não houver.

vendors[].descriptionstring

Apresentação do seller. Ausente se não houver.

vendors[].citystring

Cidade. Ausente se não houver.

vendors[].statestring

UF. Ausente se não houver.

vendors[].product_countinteger

Produtos ativos do seller.

vendors[].is_on_vacationboolean

Seller em modo férias. A mensagem e a data de volta ficam em Situação do seller.

vendors[].created_atstring

RFC 3339. Quando o seller entrou na loja.

totalinteger

Sellers que atendem ao filtro, em todas as páginas.

pageinteger

Página devolvida.

per_pageinteger

Tamanho de página aplicado.

total_pagesinteger

Quantidade de páginas.

Erros

Status	Quando	Corpo
401	Loja que exige login para navegar e chamada sem token.	`{"error":"shopping_requires_login","message":"this storefront requires login to browse"}`
500	Falha ao ler o diretório.	`{"error":"failed to list vendors","detail":"..."}`

Veja também

Listar sellers

Devolve o diretório público de sellers, paginado, com busca por nome e filtro por cidade e estado.

GET/api/v1/storefront/vendorsPública

Lista os sellers da loja

Devolve uma página do diretório de sellers ativos, do mais novo para o mais antigo (padrão). Não exige token.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageinteger

searchstring

Parte do nome do seller, sem diferenciar maiúsculas.

citystring

Cidade, igualdade exata (Rio de Janeiro).

statestring

UF, igualdade exata (RJ).

sort_bystringpadrão: created_at

created_atcompany_name

Campo de ordenação. Outro valor cai em created_at.

sort_dirstringpadrão: desc

ascdesc

Direção. Qualquer valor diferente de asc ordena de forma decrescente.

statusstring

Situação do seller. Por padrão só os ativos; não use para outra coisa na vitrine.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/vendors?per_page=12&sort_by=company_name&sort_dir=asc"

Resposta

200Página de sellers

json

{
  "vendors": [
    {
      "id": "c0000000-0000-0000-0000-000000000002",
      "display_id": 1,
      "company_name": "Moda Carioca",
      "slug": "moda-carioca",
      "logo_url": "https://cdn.example.com/moda-carioca/logo.png",
      "banner_url": "https://cdn.example.com/moda-carioca/banner.jpg",
      "description": "A melhor moda do Rio de Janeiro para você.",
      "city": "Rio de Janeiro",
      "state": "RJ",
      "product_count": 128,
      "min_order_amount": 15000,
      "is_on_vacation": false,
      "created_at": "2026-03-06T10:25:37.86958Z"
    }
  ],
  "total": 11,
  "page": 1,
  "per_page": 12,
  "total_pages": 1
}

Campos da resposta

vendorsobject[]

Os sellers da página. Vazio ([]) quando nenhum atende ao filtro.

vendors[].iduuid

Id do seller.

vendors[].display_idinteger

Número curto sequencial, para exibir no lugar do UUID. Ausente se não existir.

vendors[].company_namestring

Nome fantasia, o que a vitrine mostra.

vendors[].slugstring

Nome do seller para URLs.

vendors[].logo_urlstring

URL do logotipo. Ausente se não houver.

vendors[].banner_urlstring

URL do banner. Ausente se não houver.

vendors[].descriptionstring

Apresentação do seller. Ausente se não houver.

vendors[].citystring

Cidade. Ausente se não houver.

vendors[].statestring

UF. Ausente se não houver.

vendors[].product_countinteger

Produtos ativos do seller.

vendors[].is_on_vacationboolean

Seller em modo férias. A mensagem e a data de volta ficam em Situação do seller.

vendors[].created_atstring

RFC 3339. Quando o seller entrou na loja.

totalinteger

Sellers que atendem ao filtro, em todas as páginas.

pageinteger

Página devolvida.

per_pageinteger

Tamanho de página aplicado.

total_pagesinteger

Quantidade de páginas.

Erros

Status	Quando	Corpo
401	Loja que exige login para navegar e chamada sem token.	`{"error":"shopping_requires_login","message":"this storefront requires login to browse"}`
500	Falha ao ler o diretório.	`{"error":"failed to list vendors","detail":"..."}`