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

Perfil

Lê e altera o perfil do cliente logado e envia a foto de perfil.

O perfil é o registro do cliente logado: nome, contato, documentos, preferências de idioma e consentimentos. Use a leitura para preencher a tela "Minha conta" e a alteração para salvá-la. A foto de perfil tem rota própria.

GET/api/v1/storefront/profileCliente

Lê o perfil do cliente logado

Exemplo de requisição

Resposta

200Perfil

Campos da resposta

iduuid
Id do cliente. user_id repete o valor.
emailstring
E-mail de login.
user_typestring
Tipo de usuário. Para um cliente é sempre customer.
statusstring
AP
Situação da conta: A ativa, P aguardando aprovação da loja (conta nova em lojas que aprovam cadastros).
first_namestring
Nome. last_name é o sobrenome e display_name o nome para exibir. Os aliases firstname e lastname são apelidos dos mesmos campos.
phonestring
Telefone, normalizado com DDI (+5511987654321).
cpfstring
CPF da pessoa física (ou CPF do responsável numa conta jurídica), como a loja o guarda. tax_id é um alias que mostra o documento principal da conta.
cnpjstring
CNPJ, só em conta jurídica. Ausente em pessoa física.
person_typestring
FJ
Tipo de pessoa: F (física, CPF) ou J (jurídica, CNPJ). person_type_declared diz se o cliente já escolheu. account_type é o rótulo equivalente (individual...).
languagestring
Idioma preferido (pt-BR, en). currency e timezone completam as preferências.
email_verifiedboolean
true quando o e-mail já foi confirmado.
whatsapp_opt_inboolean
Aceite de contato por WhatsApp. sms_opt_in, push_opt_in e notify_on_orders são os demais consentimentos e avisos.
terms_accepted_atstring
Quando aceitou os termos. privacy_accepted_at é o aceite da política de privacidade.
avatar_urlstring
Foto de perfil, quando enviada.
last_login_atstring
Último login, RFC 3339. login_count conta os logins. Os campos timestamp, updated_timestamp e last_login são cópias em Unix timestamp.
StatusQuandoCorpo
401Sem token, ou token inválido ou expirado{"error":"missing authorization header"} / {"error":"invalid or expired token"}
404Usuário não encontrado ou removido{"error":"user not found"}
PUT/api/v1/storefront/profileCliente

Altera o perfil do cliente logado

Altera só os campos enviados (um campo ausente fica como está). Devolve o perfil atualizado. Valores em branco ("") apagam o campo quando a regra da loja permite (por exemplo, o telefone).

Corpo da requisição

first_namestring
Nome. last_name é o sobrenome.
phonestring
Telefone com DDD. É normalizado para o formato com DDI (+55...). Em lojas que exigem telefone, não pode ficar vazio (400 required_field_missing).
whatsapp_phonestring
Número a que vale o consentimento de WhatsApp. Vazio apaga. O aceite em si (whatsapp_opt_in) é dado por outra rota de marketing.
languagestring
Idioma (pt-BR, en).
currencystring
Moeda de exibição.
timezonestring
Fuso horário IANA, por exemplo America/Sao_Paulo.
cpfstring
CPF (11 dígitos) ou, por tolerância, CNPJ (14). Validado e guardado só com números. Numa conta jurídica, um valor de 11 dígitos é tratado como o CPF do responsável, sem tocar no CNPJ. Documento já existente na conta não pode mudar (403 document_locked).
cnpjstring
CNPJ da empresa, em campo próprio. Vazio apaga. CNPJ inválido: 400 invalid CNPJ.
person_typestring
FPFJPJ
F/PF ou J/PJ. Troca o tipo de pessoa da conta, quando a loja aceita o tipo.
legal_namestring
Razão social, só para conta jurídica. trade_name é o nome fantasia e state_reg a inscrição estadual.
current_passwordstring
Obrigatório em lojas que pedem a senha para salvar o perfil (403 current_password_required); senha errada responde 403 current_password_invalid.
emailstring
Aceito, com validação de formato e unicidade, mas sem pedir a senha e sem encerrar as sessões. Para trocar o e-mail use Senha e e-mail.

A resposta 200 é o perfil atualizado, no mesmo formato da leitura.

StatusQuandoCorpo
400Corpo que não é JSON, e-mail ou documento inválidos, telefone ausente onde é obrigatório{"error":"validation_failed","fields":{"email":"invalid"}} / {"error":"invalid CNPJ"} / {"error":"required_field_missing","detail":"phone"}
401Sem token, ou token inválido ou expirado{"error":"missing authorization header"} / {"error":"invalid or expired token"}
403Documento já existente que não pode mudar; senha de confirmação ausente ou errada; tipo de pessoa que a loja não aceita; e-mail/senha em sessão de suporte{"error":"document_locked","detail":"Para alterar o documento, fale com a loja"} / {"error":"current_password_required"} / {"error":"person_type_not_accepted"}
404Usuário não encontrado{"error":"user not found"}
409CPF ou e-mail já usados por outra conta{"error":"cpf_already_registered","fields":{"cpf":"already_registered"}} / {"error":"email_already_registered"}
500Falha ao gravar{"error":"failed to update profile","detail":"..."}
POST/api/v1/storefront/profile/avatarCliente

Envia a foto de perfil

Envia a imagem como multipart/form-data, no campo file. A plataforma decodifica a imagem, a converte para PNG e guarda com um nome que ela mesma escolhe: o arquivo e o nome do cliente nunca são armazenados como vieram. Devolve o perfil com o novo avatar_url. Também funciona numa sessão de suporte, porque a foto é um dado cosmético.

Cabeçalhos

Content-Typestringobrigatório
multipart/form-data com boundary (o cliente HTTP define sozinho).

Corpo da requisição

filefileobrigatório
Imagem PNG, JPEG, GIF ou WebP de até 5 MB. Mande já recortada e reduzida (por exemplo, 256 px).

A resposta 200 é o perfil completo (formato da leitura) com avatar_url preenchido.

StatusQuandoCorpo
400Não é multipart/form-data, sem o campo file, ou arquivo que não é uma imagem aceita{"error":"failed to parse multipart form"} / {"error":"file is required"} / {"error":"unsupported file type","detail":"Only PNG, JPEG, GIF or WebP images are allowed"}
401Sem token, ou token inválido ou expirado{"error":"missing authorization header"} / {"error":"invalid or expired token"}
404Usuário não encontrado{"error":"user not found"}
500Falha ao guardar a imagem{"error":"failed to store avatar","detail":"..."}
503Armazenamento de mídia indisponível na loja{"error":"media storage unavailable"}
Quando o perfil está incompleto

Lojas costumam exigir CPF e telefone no cadastro e usam o perfil para completar o que faltar antes do primeiro pedido. Confira cpf e phone ao abrir o checkout e leve o cliente a esta tela, em vez de deixar o pedido falhar.

Veja também

  • Senha e e-mail
  • Endereços
  • Campos do perfil
Anterior
Conta do cliente
Próxima
Senha e e-mail
Nesta página
  • Exemplo de requisição
  • Resposta
  • Veja também
bash
curl "$BASE_URL/api/v1/storefront/profile" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X PUT "$BASE_URL/api/v1/storefront/profile" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "first_name": "Maria",
  "last_name": "Souza",
  "phone": "11987654321",
  "language": "pt-BR"
}'
bash
curl -X POST "$BASE_URL/api/v1/storefront/profile/avatar" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@foto.png"
json
{
  "id": "264a70c1-9c69-458d-ac73-838543f87da2",
  "email": "maria.souza@example.com",
  "user_type": "customer",
  "status": "A",
  "first_name": "Maria",
  "last_name": "Souza",
  "display_name": "Maria Souza",
  "phone": "+5511987654321",
  "cpf": "123.456.789-09",
  "person_type": "F",
  "person_type_declared": true,
  "account_type": "individual",
  "language": "pt-BR",
  "currency": "BRL",
  "timezone": "America/Sao_Paulo",
  "email_verified": false,
  "last_login_at": "2026-10-11T20:54:30Z",
  "login_count": 1,
  "whatsapp_opt_in": false,
  "sms_opt_in": false,
  "push_opt_in": true,
  "notify_on_orders": true,
  "terms_accepted_at": "2026-10-11T20:50:22Z",
  "privacy_accepted_at": "2026-10-11T20:50:22Z",
  "created_at": "2026-10-11T20:50:22Z",
  "updated_at": "2026-10-11T20:54:30Z",
  "user_id": "264a70c1-9c69-458d-ac73-838543f87da2",
  "firstname": "Maria",
  "lastname": "Souza",
  "tax_id": "123.456.789-09"
}