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

Conta do seller

Segundo fator, privilégios, equipe, cadastro de aprovação e saúde do seller (lojista) no painel do seller.

Um seller (lojista) é um vendedor que opera dentro do marketplace da loja, com catálogo, pedidos e financeiro próprios. Esta seção reúne as rotas de conta do usuário do seller, sob /api/v1/vendor: identidade, segundo fator, o que ele pode fazer, a equipe da loja, o cadastro de aprovação (premoderação) e o painel de saúde. Todas exigem o token de um usuário do tipo seller, obtido no login do seller (veja Autenticação).

Pontos principais
  • Existem dois conceitos chamados "privilégio" no seller: o que a pessoa pode fazer (me/privileges, vem dos grupos) e o que a loja pode usar conforme o plano (privileges, privileges/all).
  • O dono da loja é o usuário vinculado ao seller. Só ele adiciona, edita e remove a equipe; gerente e membro só leem.
  • Um membro novo sem grupo de usuários não pode fazer nada: conceda ao menos um grupo em usergroup_ids.
  • Até o cadastro ser aprovado, a loja pode ter funções limitadas. Acompanhe em application.
  • O token de administrador não funciona nestas rotas, e o do seller não funciona em /api/v1/admin.

Como funciona

Uma loja de seller tem um dono e, opcionalmente, uma equipe. Cada pessoa da equipe tem um papel e, o que realmente define o que ela alcança, os grupos de usuários concedidos:

Papel (role)Quem éGerencia a equipe?Privilégios
ownerUsuário vinculado ao seller; criado com a lojaSimTodos
managerMembro adicionado pelo donoNãoSó os dos grupos concedidos
memberMembro adicionado pelo dono (padrão)NãoSó os dos grupos concedidos

O cadastro de aprovação passa por estes estados:

pending→under_review→approved
StatusSignificado
not_startedAinda não há cadastro enviado.
pendingEnviado, aguardando documentos ou análise.
under_reviewHá documento anexado e a loja está em análise.
approvedAprovado pela equipe da loja.
rejectedRecusado; o motivo vem em rejection_reason.

Conceitos importantes

Erros e papéis

As rotas de equipe respondem com um código curto em error e a explicação em detail, por exemplo {"error":"owner_only","detail":"only the store owner can manage administrators"}. Os detail vêm em inglês, exceto onde indicado.

Ids

Ids de usuário, seller, grupo e cadastro são UUID em texto. Datas são RFC 3339 em UTC.

Equipe no painel do administrador

O administrador da plataforma também gerencia a equipe de um seller, por rotas em /api/v1/admin/vendors/{id}/team, documentadas na seção de administração de sellers.

Endpoints

MétodoCaminhoPara que serveAutenticação
GET/api/v1/vendor/meIdentidade mínima do usuário seller.vendor
GET/api/v1/vendor/me/privilegesPrivilégios do próprio usuário.vendor
GET/api/v1/vendor/me/preferencesLê as preferências de tela.vendor
PUT/api/v1/vendor/me/preferencesGrava preferências (mescla).vendor
GET/api/v1/vendor/me/panel-menusMenus escondidos para o seller.vendor
GET/api/v1/vendor/2fa/statusEstado do segundo fator.vendor
POST/api/v1/vendor/2fa/setupGera segredo e QR code.vendor
POST/api/v1/vendor/2fa/confirmLiga o 2FA.vendor
POST/api/v1/vendor/2fa/disableDesliga o 2FA.vendor
GET/api/v1/vendor/privilegesRecursos liberados à loja pelo plano.vendor
GET/api/v1/vendor/privileges/allTodos os recursos possíveis.vendor
GET/api/v1/vendor/privileges/checkPergunta se um recurso está liberado.vendor
GET/api/v1/vendor/teamLista a equipe da loja.vendor
POST/api/v1/vendor/teamAdiciona uma pessoa à equipe.vendor
PUT/api/v1/vendor/team/{userId}Edita um membro da equipe.vendor
DELETE/api/v1/vendor/team/{userId}Remove um membro da equipe.vendor
GET/api/v1/vendor/team/usergroupsGrupos que o dono pode conceder.vendor
GET/api/v1/vendor/applicationSituação do cadastro de aprovação.vendor
POST/api/v1/vendor/applicationEnvia o cadastro para análise.vendor
POST/api/v1/vendor/application/{id}/documentsAnexa um documento ao cadastro.vendor
GET/api/v1/vendor/health/summaryIndicadores de despacho do seller.vendor
GET/api/v1/vendor/health/listingsQualidade de cada anúncio.vendor
POST/api/v1/vendor/health/listings/{productId}/ai-fixPede uma proposta de correção.vendor
POST/api/v1/vendor/health/listings/{productId}/ai-fix/applyAplica a correção e recalcula a nota.vendor

Erros comuns

  • Criar um membro sem usergroup_ids: ele entra na equipe, mas todas as suas chamadas recusam por falta de privilégio.
  • Enviar usergroup_ids com um grupo que não é de seller ou que a plataforma não liberou: 403 usergroup_not_grantable. Liste os permitidos em GET /api/v1/vendor/team/usergroups.
  • Tentar editar ou remover o dono: 403 cannot_edit_owner e 409 cannot_remove_owner.
  • Usar GET /api/v1/vendor/privileges/check esperando uma resposta: hoje a rota recusa toda chamada (veja Privilégios).
  • Enviar documentos do cadastro sem antes ter criado o cadastro com POST /api/v1/vendor/application.
  • Esperar que ai-fix devolva um texto novo para o anúncio: hoje ele devolve uma proposta vazia (veja Saúde).

Próximos passos

Equipe
Adicionar e gerenciar quem opera a loja.
Cadastro de aprovação
Enviar documentos e acompanhar a análise.
Saúde do seller
Prazo de despacho e qualidade dos anúncios.
Atores
Administrador, seller e cliente.
Anterior
Verificar IP e limpar vencidos
Próxima
Segundo fator (2FA)
Nesta página
  • Como funciona
  • Conceitos importantes
  • Erros e papéis
  • Ids
  • Equipe no painel do administrador
  • Endpoints
  • Erros comuns
  • Próximos passos