VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Catálogo mestre e visibilidade

Visibilidade

Mostra quem enxerga o seller na vitrine e grava a lista de clientes que podem ou não vê-lo.

Em vendas B2B ou fechadas, o seller pode querer aparecer só para certos clientes. A visibilidade tem duas camadas independentes: o administrador oculta o seller ou o libera para grupos de clientes; o seller restringe por cliente com a lista abaixo. Para o cliente enxergar o seller, as duas camadas precisam permitir.

customer_modeQuem enxerga o seller (nesta camada)
allTodos. É o padrão, e a lista de ids precisa estar vazia.
allowlistSó os clientes da lista.
denylistTodos, menos os clientes da lista.

Ler a visibilidade

Devolve as duas camadas. Sem nenhum registro, o seller é visível a todos (customer_mode: "all").

GET/api/v1/vendor/visibilitySeller

Ver as regras de visibilidade

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário do painel do seller (lojista), obtido no login (veja Tokens).

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/visibility" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Regras
json
{
  "vendor_id": "7c1f0b52-3a64-4d1e-9a40-5f0c2b6a91d3",
  "company_name": "Minha Empresa",
  "is_hidden": false,
  "allowed_usergroups": [],
  "customer_mode": "allowlist",
  "customer_ids": [
    "10770e58-19ab-4f74-9540-ad12ac164dff"
  ],
  "customer_visibility_available": true,
  "updated_at": "2026-10-11T18:20:00Z"
}

Campos da resposta

vendor_iduuid
Seu seller.
company_namestring
Nome do seller.
is_hiddenboolean
Definido pelo administrador: seller oculto da vitrine (salvo exceção por grupo). Você não altera.
allowed_usergroupsarray
Definido pelo administrador: ids de grupos de clientes que enxergam o seller. Vazio, todos (se não oculto). Você não altera.
customer_modestring
allallowlistdenylist
Sua regra por cliente.
customer_idsarray
Ids de clientes da sua regra.
customer_visibility_availableboolean
false quando a loja ainda não tem o recurso por cliente instalado: nesse caso a gravação falha.
updated_atstring
RFC 3339. Quando não há registro, é o momento da consulta.

Erros

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} / {"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é de um administrador da loja).{"error":"insufficient permissions"}
403O cadastro do seller ainda está em análise (só a tela de cadastro funciona até a aprovação).{"error":"vendor_pending_review","message":"..."}
404O usuário não está ligado a nenhum seller.{"error":"VENDOR_NOT_FOUND"}

Buscar clientes

Ajuda a montar a lista: procura clientes ativos por nome ou e-mail. Devolve no máximo 20, ordenados por nome. Exige o módulo vendor-visibility.

GET/api/v1/vendor/visibility/customersSeller

Buscar clientes para a lista

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário do painel do seller (lojista), obtido no login (veja Tokens).

Parâmetros de consulta

qstringobrigatório
Texto procurado em nome, sobrenome ou e-mail. Mínimo 2 caracteres (com menos, volta lista vazia) e máximo 100.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/visibility/customers?q=maria" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Clientes
json
{
  "customers": [
    {
      "id": "10770e58-19ab-4f74-9540-ad12ac164dff",
      "name": "Maria Souza",
      "email": "maria.souza@example.com"
    }
  ]
}

Campos da resposta

customersarray
Clientes encontrados.
customers[].iduuid
Id do cliente.
customers[].namestring
Nome e sobrenome.
customers[].emailstring
E-mail.

Erros

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} / {"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é de um administrador da loja).{"error":"insufficient permissions"}
403O cadastro do seller ainda está em análise (só a tela de cadastro funciona até a aprovação).{"error":"vendor_pending_review","message":"..."}
403O módulo vendor-visibility está desligado nesta loja.{"error":"module_disabled","module":"vendor-visibility"}
400Consulta com mais de 100 caracteres, ou recurso por cliente não instalado na loja.{"error":"CUSTOMER_SEARCH_FAILED","detail":"search query too long"}
Dados pessoais

A resposta traz nome e e-mail de clientes da loja inteira, não só dos que compraram do seller. Não guarde nem exponha além do necessário.

Gravar a lista

Substitui a sua regra por cliente (modo e lista). Não mexe em is_hidden nem nos grupos do administrador. A gravação avisa a vitrine para atualizar o cache.

PUT/api/v1/vendor/visibility/customersSeller

Gravar a lista de clientes

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário do painel do seller (lojista), obtido no login (veja Tokens).
Content-Typestringobrigatório
application/json.

Corpo da requisição

customer_modestringobrigatório
allallowlistdenylist
Modo da regra.
customer_idsarray
Ids (UUID) de clientes ativos. Até 10.000; repetidos são unidos. Deve ser vazia no modo all. Só contas de cliente ativas e que não sejam subcontas.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/vendor/visibility/customers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "customer_mode": "allowlist",
  "customer_ids": [
    "10770e58-19ab-4f74-9540-ad12ac164dff"
  ]
}'

Resposta

200Regras gravadas
json
{
  "vendor_id": "7c1f0b52-3a64-4d1e-9a40-5f0c2b6a91d3",
  "company_name": "Minha Empresa",
  "is_hidden": false,
  "allowed_usergroups": [],
  "customer_mode": "allowlist",
  "customer_ids": [
    "10770e58-19ab-4f74-9540-ad12ac164dff"
  ],
  "customer_visibility_available": true,
  "updated_at": "2026-10-11T18:20:00Z"
}

Campos da resposta

vendor_iduuid
Seu seller.
company_namestring
Nome do seller.
is_hiddenboolean
Definido pelo administrador: seller oculto da vitrine (salvo exceção por grupo). Você não altera.
allowed_usergroupsarray
Definido pelo administrador: ids de grupos de clientes que enxergam o seller. Vazio, todos (se não oculto). Você não altera.
customer_modestring
allallowlistdenylist
Sua regra por cliente.
customer_idsarray
Ids de clientes da sua regra.
customer_visibility_availableboolean
false quando a loja ainda não tem o recurso por cliente instalado: nesse caso a gravação falha.
updated_atstring
RFC 3339. Quando não há registro, é o momento da consulta.

Erros

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} / {"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é de um administrador da loja).{"error":"insufficient permissions"}
403O cadastro do seller ainda está em análise (só a tela de cadastro funciona até a aprovação).{"error":"vendor_pending_review","message":"..."}
403O módulo vendor-visibility está desligado nesta loja.{"error":"module_disabled","module":"vendor-visibility"}
400Modo inválido, id inválido, mais de 10.000 ids, ids que não são de clientes ativos, ou all com ids.{"error":"INVALID_CUSTOMER_VISIBILITY","detail":"invalid customer visibility mode"} / "customer list contains unknown or non-customer ids" / "all mode requires empty customer list"
404O usuário não está ligado a nenhum seller.{"error":"VENDOR_NOT_FOUND"}
Todos os erros de gravação voltam 400

Até uma falha do servidor ao gravar volta como 400 INVALID_CUSTOMER_VISIBILITY. Confira o detail antes de concluir que o corpo está errado.

Lista vazia em allowlist

allowlist com lista vazia é aceito e deixa o seller invisível para todos os clientes.

Anterior
Modo catálogo
Próxima
Ferramentas do catálogo do seller
Nesta página
  • Ler a visibilidade
  • Exemplo de requisição
  • Resposta
  • Erros
  • Buscar clientes
  • Exemplo de requisição
  • Resposta
  • Erros
  • Gravar a lista
  • Exemplo de requisição
  • Resposta
  • Erros