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

Perfil e verificação do seller

Como o seller (lojista) consulta e edita o perfil da empresa, escolhe a URL da loja, acompanha a reputação e envia os documentos de verificação de identidade.

Um seller (lojista) é um vendedor que opera dentro do marketplace da loja. Esta seção reúne as rotas em que ele cuida de si mesmo: os dados da empresa (nome fantasia, CNPJ, endereço, dados bancários, preferências de e-mail), a URL da loja (slug), o termômetro de reputação que a vitrine mostra aos clientes e a verificação de identidade (KYC, "know your customer") exigida por algumas lojas antes de liberar vendas e repasses. Tudo vive em /api/v1/vendor e o seller é identificado pelo token.

Pontos principais
  • O seller nunca informa o próprio id: ele vem do token. Campos sensíveis como comissão, status, modelo de pagamento e de entrega são ignorados quando o próprio seller envia; só o administrador da loja os altera.
  • GET /profile devolve o objeto completo do seller; GET /profile/form devolve o mesmo perfil como uma lista de campos configuráveis pela loja. Os dois gravam nas mesmas colunas.
  • A URL da loja (slug) usa só letras minúsculas, números e hífens, entre 2 e 100 caracteres, e nomes reservados da loja são recusados.
  • A reputação só aparece como número depois de um mínimo de pedidos; antes disso é neutral com cold_start verdadeiro.
  • O KYC só existe quando a loja liga o módulo vendor-kyc. Sem ele, as rotas respondem 403 module_disabled.

Como funciona

Perfil, formulário e conta

O mesmo perfil pode ser lido de dois jeitos. GET /profile entrega o objeto fixo (company_name, cnpj, bank_account...). GET /profile/form entrega só os campos que a loja habilitou na tela de cadastro do seller, na ordem em que ela quer, com rótulo, placeholder, obrigatoriedade e o valor atual de cada um. É o que um painel deve usar para desenhar o formulário sem fixar os campos no código.

Reputação

Pedidos recentes→Indicadores de desempenho→Faixa verde, amarela ou vermelha

A plataforma recalcula a reputação todo dia a partir do desempenho do seller nos pedidos recentes e informa os principais pontos fracos em top_issues. Veja Reputação.

Verificação KYC

Enviar pedido→Anexar documentos→Em análise→Aprovada ou Recusada
statusSignificado
pendingPedido aberto, aceita documentos.
in_reviewA loja está analisando.
approvedAprovado. Vale por 1 ano.
rejectedRecusado; o seller pode enviar documentos de novo.
expiredVenceu a validade e precisa ser refeito.

Conceitos importantes

Dinheiro, taxas e datas

Valores em centavos; taxas de comissão em percentual (9 = 9%). Datas em RFC 3339, UTC.

Impersonação

Quando um administrador entra na conta do seller ("login como"), a troca de e-mail, senha e dados bancários é bloqueada com 403 impersonation_blocked_field. Isso é de propósito: essas mudanças redirecionam acesso e repasses e só o dono pode fazê-las.

Seller ainda sem cadastro completo

Um usuário seller sem a linha de cadastro da empresa recebe 200 em GET /profile com {"vendor": null, "vendor_profile_required": true} e 403 vendor_profile_required ao tentar gravar.

Endpoints

MétodoCaminhoPara quêAuth
GET/api/v1/vendor/profilePerfil completo do seller.seller
PUT/api/v1/vendor/profileAltera o perfil.seller
GET/api/v1/vendor/profile/formPerfil como lista de campos.seller
PUT/api/v1/vendor/profile/formGrava valores por nome de campo.seller
GET/api/v1/vendor/profile/check-slugConfere se uma URL de loja está livre.seller
GET/api/v1/vendor/reputationReputação do seller.seller
GET/api/v1/vendor/kycSituação da verificação e documentos.seller
POST/api/v1/vendor/kyc/submitAbre um pedido de verificação.seller
POST/api/v1/vendor/kyc/documentsEnvia um documento.seller
DELETE/api/v1/vendor/kyc/documents/{docId}Remove um documento ainda não analisado.seller

Erros comuns

  • Mandar commission_rate, status ou payment_model no PUT /profile esperando mudar. Chega 200, mas esses campos são descartados. Só o administrador os altera.
  • Mandar email ou dados bancários durante um "login como". Volta 403 impersonation_blocked_field.
  • Esquecer que PUT /profile/form aceita só strings e só campos habilitados. Um campo desconhecido ou desligado volta 400 unknown_or_disabled_profile_field.
  • Achar que check-slug com a própria URL volta "indisponível". O seller não colide consigo mesmo: a própria URL aparece como livre.
  • Tentar enviar documento KYC antes de abrir o pedido. Volta 400 no KYC verification found. Chame kyc/submit primeiro.

Próximos passos

Perfil e URL da loja
Ler e editar os dados da empresa.
Reputação
O termômetro do seller.
Verificação KYC
Enviar documentos de identidade.
Anterior
Documentos de cadastro
Próxima
Perfil do seller
Nesta página
  • Como funciona
  • Perfil, formulário e conta
  • Reputação
  • Verificação KYC
  • Conceitos importantes
  • Dinheiro, taxas e datas
  • Impersonação
  • Seller ainda sem cadastro completo
  • Endpoints
  • Erros comuns
  • Próximos passos