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

Consultar, editar e excluir seller

Lê o cadastro completo de um seller, atualiza qualquer campo de forma parcial e exclui o seller liberando o slug.

Consultar um seller

Devolve o cadastro completo, incluindo os campos que só o administrador vê (dados bancários, representante legal, DPO, comissão).

GET/api/v1/admin/vendors/{id}Admin

Consulta o cadastro completo de um seller

Parâmetros de caminho

iduuidobrigatório
Id do seller. Valor que não é UUID devolve 404.
200Seller
json
{
  "id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "display_id": 26,
  "user_id": "0fd409fb-9869-4c50-a18c-a810a19abeed",
  "company_name": "Loja Seller Teste",
  "slug": "loja-seller-teste",
  "status": "A",
  "cnpj": "",
  "email": "contato@lojateste.example.com",
  "phone": "+5511999998888",
  "website": "https://lojateste.example.com",
  "address_line1": "Rua dos Testes, 100",
  "city": "Volta Redonda",
  "state": "RJ",
  "postal_code": "27253-650",
  "country": "BR",
  "commission_rate": 9,
  "commission_type": "percentage",
  "payment_model": "marketplace_collects",
  "fulfillment_type": "vendor_fulfilled",
  "marketplace_shipping_fee_bps": 0,
  "payout_method": "pix",
  "bank_name": "Banco Exemplo",
  "bank_agency": "0001",
  "bank_account": "12345-6",
  "pix_key": "pagamentos@lojateste.example.com",
  "terms_accepted": true,
  "products_require_approval": true,
  "email_new_order": true,
  "is_on_vacation": false,
  "debt_balance": 0,
  "created_at": "2026-04-26T21:01:28Z",
  "updated_at": "2026-10-09T10:00:00Z"
}

Campos da resposta

iduuid
Id do seller.
display_idinteger
Número sequencial amigável.
user_iduuid
Usuário dono. Ausente se não há.
company_namestring
Nome fantasia.
legal_namestring
Razão social.
slugstring
Slug da vitrine.
statusstring
PADR
Status em letra.
cnpjstring
CNPJ só com dígitos.
cnae_codestring
Atividade econômica (CNAE).
state_regstring
Inscrição estadual.
tax_regimestring
meisimples_nacionallucro_presumidolucro_reallucro_arbitrado
Regime tributário.
rep_full_namestring
Representante legal (sócio administrador). Também rep_cpf, rep_birth_date, rep_email, rep_phone, rep_mother_name.
emailstring
E-mail do seller.
phonestring
Telefone. Também mobile_phone e website.
address_line1string
Endereço. Também address_line2, address_number, address_complement, address_district, city, state, postal_code, country.
latitudenumber
Latitude da loja, quando há.
commission_ratenumber
Comissão em percentual.
payment_modelstring
marketplace_collectsdirect_to_vendor
Quem recebe o pagamento do cliente.
pagarme_recipient_idstring
Id do recebedor no gateway, quando usado.
fulfillment_typestring
vendor_fulfilledmarketplace_fulfilled
Quem despacha.
marketplace_shipping_fee_bpsinteger
Taxa sobre o frete retida pela plataforma, em pontos-base.
payout_methodstring
Forma de repasse (pix, bank_transfer).
bank_codestring
Código do banco (3 dígitos). Também bank_name, bank_agency, bank_account, bank_account_type, bank_account_holder, pix_key.
logo_urlstring
Logo. Também email_logo_url, banner_url e description.
products_require_approvalboolean
Se os produtos do seller passam pela moderação.
email_new_orderboolean
Notificações: também email_order_status, email_low_stock, email_payout.
is_on_vacationboolean
Se está em férias. Detalhes em vacation_message, vacation_until, vacation_started_at.
debt_balanceinteger
Dívida do seller com a plataforma, em centavos.
plan_idinteger
Plano de seller atribuído, quando há.
settlement_term_daysinteger
Prazo de liquidação próprio, em dias. Ausente = padrão da plataforma.
approved_atstring
Quando foi aprovado.
descriptionsobject
Descrições por idioma, quando cadastradas.
created_atstring
Cadastro (RFC 3339).
updated_atstring
Última alteração.

Atualizar um seller

Atualização parcial: só os campos enviados mudam. Texto vazio "" limpa o campo. Aceita todos os campos de dados do cadastro mostrados acima, mais o status.

PUT/api/v1/admin/vendors/{id}Admin

Atualiza o cadastro de um seller

Parâmetros de caminho

iduuidobrigatório
Id do seller.

Corpo da requisição

company_namestring
Nome fantasia.
slugstring
Novo slug. Mesmas regras de check-slug. Se outro seller já usa, 409 slug_taken.
legal_namestring
Razão social.
cnpjstring
CNPJ. Validado e único por loja.
tax_regimestring
meisimples_nacionallucro_presumidolucro_reallucro_arbitrado
Regime tributário.
emailstring
E-mail do seller.
phonestring
Telefone.
commission_ratenumber
Comissão em percentual, de 0 a 100.
payment_modelstring
marketplace_collectsdirect_to_vendor
Modelo de pagamento.
fulfillment_typestring
vendor_fulfilledmarketplace_fulfilled
Quem despacha.
marketplace_shipping_fee_bpsinteger
Taxa sobre o frete, em pontos-base.
products_require_approvalboolean
Exigir moderação de produtos.
settlement_term_daysinteger
Prazo de liquidação próprio, em dias.
statusstring
Status direto (palavra ou letra). Oculta ou devolve os produtos ao suspender e reativar, mas não grava approved_at/approved_by nem avisa o seller como a rota de status. Prefira aquela rota.
descriptionsobject
Descrições por idioma: um objeto por código de idioma.

Os demais campos do cadastro (endereço, dados bancários, representante legal, DPO, logo, notificações e outros) seguem os mesmos nomes da resposta acima.

bash
curl -X PUT "$BASE_URL/api/v1/admin/vendors/94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"commission_rate": 11, "phone": "+5511988887777"}'

A resposta (200) é o seller atualizado.

Excluir um seller

Exclusão lógica: marca o seller como excluído, libera o slug no registro de URLs e desativa o usuário dono se ele não administra nenhum outro seller. O seller some das listas.

DELETE/api/v1/admin/vendors/{id}Admin

Exclui um seller

Parâmetros de caminho

iduuidobrigatório
Id do seller.
200Excluído
json
{ "message": "vendor deleted" }

Erros

StatusQuandoCorpo de exemplo
400Corpo do PUT não é JSON.{"error":"invalid request body","detail":"..."}
400PUT com campo password.{"error":"password_not_updatable","detail":"este endpoint não troca senha..."}
400Slug com formato inválido ou reservado; CNPJ, regime ou comissão inválidos.{"error":"slug_reserved","detail":"..."}
404Seller não existe, já excluído, ou id que não é UUID (no GET).{"error":"vendor not found"}
409Slug, CNPJ ou e-mail já usado por outro seller.{"error":"slug_taken","detail":"..."}
500DELETE ou PUT com id que não é UUID.{"error":"failed to delete vendor","detail":"..."}
401 / 403Sem token, ou sem manage_vendors nas escritas.{"error":"missing authorization header"}
O slug de um seller excluído não volta

A exclusão libera o slug no registro de URLs da vitrine, mas o banco continua considerando o slug de um seller excluído como ocupado. check-slug já responde taken nesse caso.

Defina o modelo de pagamento antes de ativar

payment_model e commission_rate mudam como o dinheiro das próximas vendas é dividido. Altere com o seller ainda pendente, ou combine a janela com ele.

Veja também

  • Mudar status
  • Configurações do seller
  • Visão geral
Anterior
Criar um seller
Próxima
Status e candidatura do seller
Nesta página
  • Consultar um seller
  • Atualizar um seller
  • Excluir um seller
  • Erros
  • Veja também