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

Perfil do seller

Lê e altera o perfil da empresa do seller, em formato fixo ou como formulário dinâmico, e confere se uma URL de loja está disponível.

O perfil reúne tudo o que identifica o seller dentro da loja: nome fantasia, CNPJ, contatos, endereço, logomarca, dados para receber repasses e as preferências de e-mail. Há duas formas de ler e gravar o mesmo perfil, e você escolhe conforme o que está construindo:

  • Formato fixo (/profile): um objeto com os campos conhecidos. Simples para integrações.
  • Formulário dinâmico (/profile/form): a lista de campos que a loja habilitou, com rótulos, obrigatoriedade e valor atual. Ideal para desenhar a tela de cadastro sem fixar campos no código.

Quem pode gravar: usuários do seller com o privilégio de configurações. A leitura é livre para qualquer usuário do seller.

Ler o perfil

GET/api/v1/vendor/profileSeller

Perfil completo do seller autenticado

Devolve o seller dono do token. Se o usuário seller ainda não tem o cadastro da empresa, a resposta é 200 com vendor nulo (veja abaixo).

Exemplo de requisição: ler

bash
curl "$BASE_URL/api/v1/vendor/profile" \
  -H "Authorization: Bearer $TOKEN"

Resposta: ler

200Perfil do seller
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@lojaseller.example.com",
  "phone": "+5511999998888",
  "website": "https://lojaseller.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": "contato@lojaseller.example.com",
  "logo_url": "/uploads/.../logo.png",
  "banner_url": "/uploads/.../banner.png",
  "description": "<p>Descrição da loja</p>",
  "terms_accepted": true,
  "products_require_approval": true,
  "email_new_order": true,
  "email_order_status": true,
  "email_low_stock": false,
  "email_payout": true,
  "is_on_vacation": false,
  "debt_balance": 0,
  "settlement_term_days": 20,
  "settlement_term_anchor": "per_installment",
  "approved_at": "2026-07-19T21:23:56.72622Z",
  "created_at": "2026-05-29T18:52:13.802087Z",
  "updated_at": "2026-09-15T19:00:17.901599Z"
}
200Usuário seller sem cadastro de empresa
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 da conta.
company_namestring
Nome fantasia.
slugstring
URL da loja: aparece em /<slug> na vitrine.
statusstring
Situação do seller na loja, em letra (por exemplo A, ativo). O seller não consegue alterá-la.
cnpjstring
CNPJ. Pode ser vazio.
emailstring
E-mail de contato e de acesso.
phonestring
Telefone.
mobile_phonestring
Celular.
websitestring
Site do seller.
address_line1string
Logradouro.
address_numberstring
Número.
address_complementstring
Complemento.
address_districtstring
Bairro.
citystring
Cidade.
statestring
UF.
postal_codestring
CEP.
countrystring
País (BR).
latitudenumber
Latitude, quando informada.
longitudenumber
Longitude, quando informada.
commission_ratenumber
Comissão que a loja cobra do seller, em percentual (9 = 9%). Somente leitura para o seller.
commission_typestring
Forma da comissão (por exemplo percentage). Somente leitura para o seller.
payment_modelstring
Quem recebe o pagamento do cliente (por exemplo marketplace_collects: a loja recebe e repassa). Somente leitura para o seller.
fulfillment_typestring
Quem entrega (por exemplo vendor_fulfilled: o próprio seller). Somente leitura para o seller.
marketplace_shipping_fee_bpsinteger
Taxa de frete da loja sobre o seller, em pontos-base (100 = 1%). Somente leitura para o seller.
payout_methodstring
Como o seller recebe os repasses (por exemplo pix).
bank_codestring
Código do banco.
bank_namestring
Nome do banco.
bank_agencystring
Agência.
bank_accountstring
Conta.
bank_account_typestring
Tipo da conta.
bank_account_holderstring
Titular da conta.
pix_keystring
Chave Pix para os repasses.
logo_urlstring
Caminho da logomarca.
email_logo_urlstring
Logomarca usada nos e-mails.
banner_urlstring
Caminho do banner da página do seller.
descriptionstring
Descrição da loja, em HTML.
terms_acceptedboolean
Se o seller aceitou os termos.
terms_accepted_atstring
Quando aceitou (RFC 3339).
products_require_approvalboolean
Se os produtos do seller passam por moderação antes de ir ao ar. Somente leitura para o seller.
email_new_orderboolean
Receber e-mail a cada pedido novo.
email_order_statusboolean
Receber e-mail quando o status de um pedido muda.
email_low_stockboolean
Receber e-mail de estoque baixo.
email_payoutboolean
Receber e-mail de repasse.
is_on_vacationboolean
Se a loja do seller está em modo férias.
debt_balanceinteger
Dívida do seller com a loja, em centavos.
settlement_term_daysinteger
Prazo, em dias, para o repasse liberar. Pode faltar quando vale o padrão da loja.
settlement_term_anchorstring
A partir de quando o prazo conta (por exemplo per_installment, a cada parcela).
approved_atstring
Quando a loja aprovou o seller.
created_atstring
Criação do cadastro (RFC 3339).
updated_atstring
Última alteração (RFC 3339).

A resposta traz ainda campos de compatibilidade com a plataforma antiga (address, company, company_id, zipcode, logos, timestamp, updated_timestamp) e os campos fiscais e de representante legal (legal_name, cnae_code, state_reg, tax_regime, rep_*, dpo_*) quando preenchidos. Em integrações novas, ignore os de compatibilidade.

Alterar o perfil

PUT/api/v1/vendor/profileSeller

Altera parcialmente o perfil do seller

Altera só os campos enviados; o que você omite fica como está. A resposta é o perfil completo depois da mudança. PUT /api/v1/vendor/settings é um apelido que faz exatamente a mesma coisa.

Campos que o seller não controla são descartados sem erro: commission_rate, commission_type, status, payment_model, pagarme_recipient_id, fulfillment_type, marketplace_shipping_fee_bps e products_require_approval.

Exige um privilégio de configurações do seller (por exemplo vendor_settings).

Corpo da requisição

company_namestring
Nome fantasia.
slugstring
Nova URL da loja. Veja as regras em conferir a URL. Trocar o slug muda o endereço público da loja.
cnpjstring
CNPJ válido (dígitos verificadores conferidos). Não pode estar em uso por outro seller.
legal_namestring
Razão social.
cnae_codestring
CNAE principal.
state_regstring
Inscrição estadual.
tax_regimestring
meisimples_nacionallucro_presumidolucro_reallucro_arbitrado
Regime tributário.
emailstring
E-mail de contato e de acesso.
phonestring
Telefone.
mobile_phonestring
Celular.
websitestring
Site.
address_line1string
Logradouro.
address_line2string
Complemento do logradouro.
address_numberstring
Número.
address_complementstring
Complemento.
address_districtstring
Bairro.
citystring
Cidade.
statestring
UF.
postal_codestring
CEP.
countrystring
País.
latitudenumber
Latitude.
longitudenumber
Longitude.
descriptionstring
Descrição da loja (HTML).
logo_urlstring
Caminho da logomarca já enviada pela biblioteca de mídia.
email_logo_urlstring
Logomarca dos e-mails.
banner_urlstring
Banner.
payout_methodstring
Forma de repasse (por exemplo pix).
bank_codestring
Código do banco.
bank_namestring
Banco.
bank_agencystring
Agência.
bank_accountstring
Conta.
bank_account_typestring
Tipo da conta.
bank_account_holderstring
Titular. Trocar o titular redireciona o repasse.
pix_keystring
Chave Pix.
email_new_orderboolean
E-mail de pedido novo.
email_order_statusboolean
E-mail de mudança de status.
email_low_stockboolean
E-mail de estoque baixo.
email_payoutboolean
E-mail de repasse.
ignore_emailstring
E-mail genérico que o ERP usa para clientes sem e-mail próprio. Quando um cliente chega pela API de compatibilidade com exatamente esse endereço, a plataforma o troca por um endereço único, para que dois clientes diferentes não colidam. Em branco, a regra fica desligada.
rep_full_namestring
Nome do representante legal. Também aceitos: rep_cpf, rep_birth_date, rep_email, rep_phone, rep_mother_name.
dpo_namestring
Nome do encarregado de dados (LGPD). Também aceitos: dpo_email, dpo_phone.

Exemplo de requisição: alterar

bash
curl -X PUT "$BASE_URL/api/v1/vendor/profile" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+5511988887777", "email_low_stock": true}'

A resposta de sucesso é 200 com o mesmo objeto do perfil.

Ler o formulário dinâmico

GET/api/v1/vendor/profile/formSeller

Perfil como lista de campos configuráveis

Devolve, em ordem, cada campo de perfil de seller que a loja habilitou, já com o valor atual. Use para montar a tela de cadastro sem listar campos no código. A senha nunca aparece.

200Campos do formulário
json
{
  "fields": [
    {
      "field_name": "company_name",
      "field_type": "I",
      "label": "Nome Fantasia",
      "label_en": "Trade Name",
      "placeholder": "Nome comercial do seller",
      "placeholder_en": "Seller trade name",
      "description": "Nome exibido na loja e nos pedidos.",
      "description_en": "Name displayed in the storefront and orders.",
      "required": true,
      "position": 1,
      "is_system": true,
      "is_mandatory": true,
      "section": "V",
      "value": "Loja Seller Teste"
    },
    {
      "field_name": "tax_regime",
      "field_type": "S",
      "label": "Regime tributário",
      "required": false,
      "position": 9,
      "is_system": true,
      "is_mandatory": false,
      "section": "V",
      "values": [
        { "label": "MEI", "value": "mei" },
        { "label": "Simples Nacional", "value": "simples_nacional" }
      ],
      "value": ""
    }
  ],
  "total": 25
}

Campos da resposta

fieldsarray
Campos habilitados, na ordem de exibição.
totalinteger
Quantidade de campos.
fields[].field_namestring
Nome do campo. É a chave usada no PUT /profile/form.
fields[].field_typestring
Tipo do campo, em letra: I texto curto, T texto longo, S lista de opções, P telefone, F arquivo. A loja pode definir outros.
fields[].labelstring
Rótulo em português. label_en é o rótulo em inglês.
fields[].placeholderstring
Texto de exemplo do campo. placeholder_en em inglês.
fields[].descriptionstring
Ajuda ao lado do campo. description_en em inglês.
fields[].requiredboolean
Se o campo é obrigatório no cadastro.
fields[].is_systemboolean
true quando o campo grava numa coluna do seller; false quando é um campo extra criado pela loja.
fields[].is_mandatoryboolean
true quando a plataforma exige o campo e a loja não pode torná-lo opcional.
fields[].positioninteger
Posição na tela.
fields[].sectionstring
Seção do cadastro (V é a seção do seller).
fields[].valuesarray
Opções (label e value) quando o tipo é lista.
fields[].valuestring
Valor atual.

Gravar o formulário dinâmico

PUT/api/v1/vendor/profile/formSeller

Grava valores do perfil por nome de campo

Recebe um objeto fields com pares nome do campo: valor (sempre texto). Cada valor vai para o destino certo: campos de sistema atualizam o cadastro do seller, campos extras ficam guardados à parte. A resposta é o formulário recalculado, no mesmo formato da leitura. Exige o privilégio de configurações.

Corpo da requisição

fieldsobjectobrigatório
Mapa field_name para o novo valor, em texto. Só campos habilitados na loja; um campo desconhecido ou desligado recusa a requisição inteira. A chave password é sempre recusada.

Exemplo de requisição: formulário

bash
curl -X PUT "$BASE_URL/api/v1/vendor/profile/form" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fields": {"company_name": "Loja Seller Teste", "phone": "+5511988887777"}}'

Conferir a URL da loja

GET/api/v1/vendor/profile/check-slugSeller

Confere se uma URL de loja está disponível

Antes de trocar o slug, pergunte se ele serve. A conferência ignora o próprio seller, então a URL que você já usa aparece como livre. Uma URL de loja já excluída continua ocupada.

Parâmetros de consulta

slugstringobrigatório
URL pretendida. Regra: 2 a 100 caracteres, só a-z, 0-9 e hífen entre grupos (minha-loja), sem começar nem terminar com hífen.
200Resultado da conferência
json
{ "available": false, "reason": "reserved" }

Campos da resposta

availableboolean
true se pode usar.
reasonstring
reservedformattaken
Presente só quando available é falso: reserved (nome reservado pela loja, como admin ou login) format (tamanho ou caracteres inválidos) ou taken (URL válida que já pertence a outro seller, inclusive um excluído).

Erros

StatusQuandoCorpo de exemplo
400Corpo não é JSON.{"error":"invalid request body","detail":"..."}
400slug ausente na conferência.{"error":"slug query param is required"}
400Slug fora da regra, na gravação.{"error":"slug_invalid","detail":"slug_invalid: must match ^[a-z0-9]+(-[a-z0-9]+)*$"}
400Slug reservado, na gravação.{"error":"slug_reserved","detail":"..."}
400CNPJ inválido.{"error":"vendor_cnpj_invalid","detail":"vendor_cnpj_invalid: 123"}
400Regime tributário fora da lista.{"error":"vendor_tax_regime_invalid","detail":"vendor_tax_regime_invalid: zzz"}
400E-mail inválido (formulário).{"error":"vendor_email_invalid","detail":"..."}
400Formulário sem o objeto fields.{"error":"fields object is required"}
400Campo desconhecido ou desligado (formulário).{"error":"unknown_or_disabled_profile_field","detail":"unknown_or_disabled_profile_field: nonexistent"}
400Campo obrigatório ficaria vazio (formulário).{"error":"required_profile_field_missing","detail":"..."}
400password no formulário.{"error":"password_not_a_profile_field","detail":"password is set during registration, not via the profile form"}
401Sem token.{"error":"authentication required"}
403Falta privilégio de configurações.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","..."]}
403Usuário seller sem cadastro de empresa (gravação).{"error":"vendor_profile_required"}
403Troca de e-mail, senha ou dados bancários durante um "login como".{"error":"impersonation_blocked_field","field":"email","message":"Esta alteração requer login direto do usuário."}
404Conferência de slug sem seller para o usuário.{"error":"vendor profile not found"}
409Slug já em uso.{"error":"slug_taken","detail":"..."}
409CNPJ já em uso por outro seller.{"error":"vendor_cnpj_in_use","detail":"..."}
409E-mail já em uso (formulário).{"error":"vendor_email_in_use","detail":"..."}
Descartar não é recusar

Enviar commission_rate, status ou payment_model no PUT /profile devolve 200, mas nada muda para esses campos. Compare a resposta com o que você enviou antes de concluir que a alteração foi aplicada.

Troque o slug com cuidado

O slug compõe a URL pública do seller. Links que usam o slug anterior podem deixar de funcionar. Confira antes com check-slug e avise quem divulga a loja.

Veja também

  • Reputação do seller
  • Verificação KYC
  • Visão geral
Anterior
Perfil e verificação do seller
Próxima
Reputação do seller
Nesta página
  • Ler o perfil
  • Exemplo de requisição: ler
  • Resposta: ler
  • Alterar o perfil
  • Exemplo de requisição: alterar
  • Ler o formulário dinâmico
  • Gravar o formulário dinâmico
  • Exemplo de requisição: formulário
  • Conferir a URL da loja
  • Erros
  • Veja também