VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Identidade e configurações da loja

Cadastro e configurações

Lê e altera o cadastro do seller (empresa, endereço, contato, conta de repasse, preferências) e informa o prazo de postagem.

Ler o cadastro

Devolve o cadastro completo do seller do token. É a mesma resposta de GET /api/v1/vendor/profile. Campos sem valor são omitidos. Além dos campos abaixo, voltam com o mesmo nome os campos de cadastro aceitos em Alterar o cadastro (empresa, endereço, contato, banco, preferências).

GET/api/v1/vendor/settingsSeller

Ler o cadastro do seller

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/settings" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Cadastro
json
{
  "id": "7c1f0b52-3a64-4d1e-9a40-5f0c2b6a91d3",
  "display_id": 42,
  "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "company_name": "Minha Empresa",
  "slug": "minha-empresa",
  "status": "active",
  "cnpj": "12345678000195",
  "legal_name": "Minha Empresa Comércio Ltda",
  "tax_regime": "simples_nacional",
  "email": "contato@minhaempresa.example",
  "phone": "+551133334444",
  "address_line1": "Av. Paulista, 1000",
  "city": "São Paulo",
  "state": "SP",
  "postal_code": "01310-100",
  "country": "BR",
  "commission_rate": 10,
  "commission_type": "percentage",
  "payment_model": "marketplace_collects",
  "fulfillment_type": "vendor_fulfilled",
  "marketplace_shipping_fee_bps": 0,
  "payout_method": "bank_transfer",
  "bank_code": "341",
  "bank_agency": "1234",
  "bank_account": "56789-0",
  "pix_key": "contato@minhaempresa.example",
  "logo_url": "https://cdn.example.com/vendor/logo.png",
  "description": "Cafeteiras e acessórios.",
  "terms_accepted": true,
  "products_require_approval": false,
  "email_new_order": true,
  "email_order_status": true,
  "email_low_stock": true,
  "email_payout": true,
  "is_on_vacation": false,
  "debt_balance": 0,
  "created_at": "2026-09-01T12:00:00Z",
  "updated_at": "2026-10-11T18:20:00Z"
}
200Usuário sem seller
json
{
  "vendor": null,
  "vendor_profile_required": true
}

Campos da resposta

iduuid
Id do seller.
display_idinteger
Número curto do seller para exibição.
user_iduuid
Usuário dono do seller.
statusstring
Situação: pending, active, suspended, deleted.
commission_ratenumber
Comissão da loja sobre as vendas deste seller, em pontos percentuais. Só leitura.
commission_typestring
Tipo da comissão (percentage). Só leitura.
payment_modelstring
marketplace_collects (a loja recebe e repassa) ou direct_to_vendor. Só leitura.
fulfillment_typestring
vendor_fulfilled ou marketplace_fulfilled. Só leitura.
marketplace_shipping_fee_bpsinteger
Taxa de frete da loja em pontos-base (500 = 5%). Só leitura.
terms_acceptedboolean
Se o seller aceitou os termos.
products_require_approvalboolean
Se os produtos do seller passam por aprovação. Só leitura.
is_on_vacationboolean
Se o seller está em modo férias.
debt_balanceinteger
Saldo devedor do seller com a loja, em centavos.
created_atstring
RFC 3339.
updated_atstring
RFC 3339.

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":"..."}
Dados sensíveis para toda a equipe

Esta leitura não exige privilégio de equipe: qualquer usuário do seller vê CNPJ, conta bancária e chave Pix. Trate o token como credencial financeira.

Usuário sem seller

Um usuário com papel de seller que ainda não tem a linha de seller recebe 200 com {"vendor": null, "vendor_profile_required": true}, não 404. A tela deve levá-lo ao cadastro.

Alterar o cadastro

Altera só os campos enviados (alteração parcial). A resposta é o cadastro completo, igual à leitura. É a mesma rota de PUT /api/v1/vendor/profile. Exige um privilégio de configuração da equipe.

PUT/api/v1/vendor/settingsSeller

Alterar o cadastro do seller

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

company_namestring
Nome fantasia, mostrado na loja.
legal_namestring
Razão social, o nome registrado na Receita.
slugstring
Endereço curto da vitrine do seller. 2 a 100 caracteres, minúsculas, números e hífens (^[a-z0-9]+(-[a-z0-9]+)*$). Reservados: new, edit, admin, api, register, login, logout, settings, profile, create, delete, search, all, page, index, null, undefined, vendors.
cnpjstring
CNPJ, com ou sem pontuação. Validado (dígitos verificadores) e único na loja. Vazio apaga.
cnae_codestring
Código CNAE. Precisa ser aceito pelas regras da loja.
state_regstring
Inscrição estadual.
tax_regimestring
meisimples_nacionallucro_presumidolucro_reallucro_arbitrado
Regime tributário.
rep_full_namestring
Representante legal: nome completo.
rep_cpfstring
Representante legal: CPF.
rep_birth_datestring
Representante legal: nascimento (AAAA-MM-DD).
rep_emailstring
Representante legal: e-mail.
rep_phonestring
Representante legal: telefone.
rep_mother_namestring
Representante legal: nome da mãe.
dpo_namestring
Encarregado de dados (LGPD): nome.
dpo_emailstring
Encarregado de dados: e-mail.
dpo_phonestring
Encarregado de dados: telefone.
emailstring
E-mail de contato do seller.
phonestring
Telefone.
mobile_phonestring
Celular.
websitestring
Site.
address_line1string
Logradouro.
address_numberstring
Número.
address_complementstring
Complemento.
address_districtstring
Bairro.
address_line2string
Linha de endereço adicional.
citystring
Cidade.
statestring
UF.
postal_codestring
CEP.
countrystring
País (código de 2 letras).
latitudenumber
Latitude.
longitudenumber
Longitude.
payout_methodstring
Forma de repasse. Hoje bank_transfer.
bank_codestring
Banco: código COMPE de 3 dígitos.
bank_namestring
Banco: nome.
bank_agencystring
Agência.
bank_accountstring
Conta.
bank_account_typestring
checkingsavings
Tipo da conta.
bank_account_holderstring
Titular, só quando for diferente da razão social.
pix_keystring
Chave Pix.
email_new_orderboolean
Receber e-mail de novo pedido.
email_order_statusboolean
Receber e-mail de mudança de status.
email_low_stockboolean
Receber e-mail de estoque baixo.
email_payoutboolean
Receber e-mail de repasse.
logo_urlstring
URL do logo.
email_logo_urlstring
URL do logo usado nos e-mails.
banner_urlstring
URL do banner.
descriptionstring
Descrição do seller.
ignore_emailstring
E-mail genérico que o ERP usa para clientes sem e-mail; clientes que chegam com ele ganham um e-mail único gerado. Vazio desliga a regra.
settlement_term_daysinteger
Prazo em dias até o repasse deste seller, se a loja permite personalizar.
settlement_term_anchorstring
Âncora do prazo de repasse.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/vendor/settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "company_name": "Minha Empresa",
  "phone": "+551133334444",
  "email_low_stock": false
}'

Resposta

200Cadastro alterado
json
{
  "id": "7c1f0b52-3a64-4d1e-9a40-5f0c2b6a91d3",
  "display_id": 42,
  "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "company_name": "Minha Empresa",
  "slug": "minha-empresa",
  "status": "active",
  "cnpj": "12345678000195",
  "legal_name": "Minha Empresa Comércio Ltda",
  "tax_regime": "simples_nacional",
  "email": "contato@minhaempresa.example",
  "phone": "+551133334444",
  "address_line1": "Av. Paulista, 1000",
  "city": "São Paulo",
  "state": "SP",
  "postal_code": "01310-100",
  "country": "BR",
  "commission_rate": 10,
  "commission_type": "percentage",
  "payment_model": "marketplace_collects",
  "fulfillment_type": "vendor_fulfilled",
  "marketplace_shipping_fee_bps": 0,
  "payout_method": "bank_transfer",
  "bank_code": "341",
  "bank_agency": "1234",
  "bank_account": "56789-0",
  "pix_key": "contato@minhaempresa.example",
  "logo_url": "https://cdn.example.com/vendor/logo.png",
  "description": "Cafeteiras e acessórios.",
  "terms_accepted": true,
  "products_require_approval": false,
  "email_new_order": true,
  "email_order_status": true,
  "email_low_stock": true,
  "email_payout": true,
  "is_on_vacation": false,
  "debt_balance": 0,
  "created_at": "2026-09-01T12:00:00Z",
  "updated_at": "2026-10-11T18:20:00Z"
}

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 usuário da equipe do seller não tem nenhum dos privilégios de configuração (por exemplo vendor_settings).{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings", "..."]}
400Corpo que não é JSON; slug ou CNPJ inválido; regime tributário inválido.{"error":"slug_invalid","detail":"slug_invalid: length must be 2-100 characters"} / {"error":"slug_reserved"} / {"error":"vendor_cnpj_invalid"} / {"error":"vendor_tax_regime_invalid"}
403Sessão de administrador em modo "entrar como seller" tentou mudar e-mail, senha ou dados de repasse.{"error":"impersonation_blocked_field", ...}
403O usuário não está ligado a nenhum seller.{"error":"vendor_profile_required"}
409Slug ou CNPJ já em uso por outro seller (seller excluído também conta).{"error":"slug_taken","detail":"..."} / {"error":"vendor_cnpj_in_use"}
500Outras falhas de gravação (por exemplo, CNAE não aceito pela loja volta como erro genérico).{"error":"failed to update vendor profile","detail":"..."}
Campos que o seller não altera

commission_rate, commission_type, status, payment_model, pagarme_recipient_id, fulfillment_type, marketplace_shipping_fee_bps e products_require_approval são descartados sem aviso: a resposta é 200 e o valor não muda.

Conta de repasse

Trocar bank_* ou pix_key redireciona os próximos repasses. Faça isso só pelo próprio seller, depois de conferir o titular.

Prazo de postagem

Informa em quantos dias o seller despacha um pedido depois de aprovado. A plataforma usa esse prazo para estimar a data de entrega mostrada ao comprador. O padrão de um seller novo é 2 dias.

PUT/api/v1/vendor/settings/handling-timeSeller

Prazo de postagem em dias

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

handling_time_daysintegerobrigatório
Dias para despachar. Valores negativos são gravados como 0. Não há teto.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/vendor/settings/handling-time" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "handling_time_days": 3
}'

Resposta

200Prazo gravado
json
{
  "handling_time_days": 3
}

Campos da resposta

handling_time_daysinteger
O valor que você enviou, sem ajuste.

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 usuário tem papel de seller, mas não está ligado a nenhum seller.{"error":"no vendor account associated with this user"}
400Corpo que não é JSON ou handling_time_days que não é inteiro.{"error":"invalid request body","detail":"..."}
500Falha ao gravar.{"error":"failed to update handling time"}
A resposta repete o que você enviou

Se enviar -1, o banco guarda 0 mas a resposta traz -1. Releia o cadastro se precisar do valor gravado.

Anterior
Vitrine do seller
Próxima
Upload de mídia
Nesta página
  • Ler o cadastro
  • Exemplo de requisição
  • Resposta
  • Erros
  • Alterar o cadastro
  • Exemplo de requisição
  • Resposta
  • Erros
  • Prazo de postagem
  • Exemplo de requisição
  • Resposta
  • Erros