Configurações do seller
O que o administrador controla de cada seller além do cadastro, como categorias permitidas, privilégios, visibilidade, férias, reputação e vitrine, com o mapa das rotas.
Além do cadastro, o administrador da loja decide como cada seller aparece e opera no marketplace: em quais categorias ele pode vender, quais recursos extras do painel ele tem, para quem a loja dele é visível, se ele está de férias, como a reputação dele é exibida e como está a vitrine própria que ele montou. Esta seção reúne essas configurações. Todos os ids de seller são UUID, e a rota usa vendorId ou id no caminho.
Como funciona
Estas configurações não têm um fluxo único: cada uma é independente e pode ser mexida a qualquer momento. O que elas têm em comum é que o seller precisa existir (e quase sempre estar ativo) e que mudanças valem de imediato na vitrine ou no painel do seller.
Conceitos-chave
Privilégios básicos e extras do seller
Todo seller ativo tem cinco privilégios implícitos: manage_products, manage_orders, view_analytics, manage_shipping e manage_profile. Os extras, que você concede ou revoga, são manage_promotions, bulk_edit, export_data, api_access, manage_usergroups, manage_delivery_areas, view_customers e manage_messages.
Visibilidade
Um seller pode estar oculto (is_hidden), restrito a certos grupos de clientes (allowed_usergroups), ou visível a todos (os dois vazios). O modo por cliente (customer_mode) é configurado pelo próprio seller.
Reputação
Nota de 0 a 100 sobre os últimos 60 dias (cancelamentos, atrasos, devoluções, avaliações, tempo de resposta). Faixas: green de 80 a 100, yellow de 50 a 79, red abaixo de 50. Com menos de 10 pedidos no período o seller está em "partida a frio": faixa neutral e nota interna 70.
Endpoints
| Método | Caminho | Para que serve | Exige | Auth |
|---|---|---|---|---|
| GET | /api/v1/admin/vendors/{vendorId}/categories | Categorias do seller | manage_vendor_categories ou manage_vendors | admin |
| PUT | /api/v1/admin/vendors/{vendorId}/categories | Definir categorias | idem | admin |
| POST | /api/v1/admin/vendors/{vendorId}/categories/{categoryId} | Permitir uma categoria | idem | admin |
| DELETE | /api/v1/admin/vendors/{vendorId}/categories/{categoryId} | Retirar uma categoria | idem | admin |
| GET | /api/v1/admin/vendors/{vendorId}/privileges | Privilégios do seller | manage_vendor_usergroups ou manage_vendors | admin |
| PUT | /api/v1/admin/vendors/{vendorId}/privileges | Definir privilégios | idem | admin |
| POST | /api/v1/admin/vendors/{vendorId}/privileges/{privilege} | Conceder um privilégio | idem | admin |
| DELETE | /api/v1/admin/vendors/{vendorId}/privileges/{privilege} | Revogar um privilégio | idem | admin |
| GET | /api/v1/admin/vendors/visibility | Visibilidade de todos | módulo vendor-visibility | admin |
| GET | /api/v1/admin/vendors/visibility/hidden | Sellers com regra de visibilidade | idem | admin |
| GET | /api/v1/admin/vendors/{vendorId}/visibility | Visibilidade de um seller | idem | admin |
| PUT | /api/v1/admin/vendors/{vendorId}/visibility | Definir a visibilidade | manage_vendor_visibility ou manage_vendors | admin |
| GET | /api/v1/admin/vendors/vacation | Sellers de férias | manage_vendor_vacation ou manage_vendors | admin |
| POST | /api/v1/admin/vendors/vacation/auto-end | Encerrar férias vencidas | idem | admin |
| GET | /api/v1/admin/vendors/opening-hours | Horários (lista vazia) | view_vendors ou manage_vendors | admin |
| GET | /api/v1/admin/vendors/{vendorId}/vacation | Férias de um seller | manage_vendor_vacation ou manage_vendors | admin |
| POST | /api/v1/admin/vendors/{vendorId}/vacation | Colocar de férias | idem | admin |
| DELETE | /api/v1/admin/vendors/{vendorId}/vacation | Encerrar as férias | idem | admin |
| GET | /api/v1/admin/vendors/{id}/reputation | Ler a reputação | qualquer administrador | admin |
| PUT | /api/v1/admin/vendors/{id}/reputation/visibility | Esconder ou mostrar | idem | admin |
| POST | /api/v1/admin/vendors/{id}/reputation/recompute | Recalcular | idem | admin |
| GET | /api/v1/admin/vendors/{vendorId}/storefront-config | Vitrine própria | manage_vendor_storefronts ou manage_vendors | admin |
Erros comuns
- Esperar que as rotas de categoria funcionem. Hoje todas devolvem
400 vendor id is required, mesmo com o id certo. - Tentar conceder um privilégio básico.
manage_productse os outros quatro devolvem erro: já são implícitos. - Ler privilégios de seller não ativo. Seller pendente, suspenso ou recusado devolve lista vazia.
- Achar que
visibility/hiddenlista só os ocultos. Ela lista todo seller que tem uma regra gravada, escondido ou não. - Esperar horários de funcionamento.
opening-hoursé um espaço reservado e devolve sempre lista vazia. - Passar uma data de fim no passado nas férias. Nada impede; o seller entra de férias e a próxima execução do encerramento automático o tira.