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

bash

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

Resposta

200Perfil

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"
}

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.

Status	Quando	Corpo
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
404	Usuá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.

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"
}'

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

Status	Quando	Corpo
400	Corpo 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"}`
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
403	Documento 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"}`
404	Usuário não encontrado	`{"error":"user not found"}`
409	CPF ou e-mail já usados por outra conta	`{"error":"cpf_already_registered","fields":{"cpf":"already_registered"}}` / `{"error":"email_already_registered"}`
500	Falha 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).

bash

curl -X POST "$BASE_URL/api/v1/storefront/profile/avatar" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@foto.png"

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

Status	Quando	Corpo
400	Nã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"}`
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
404	Usuário não encontrado	`{"error":"user not found"}`
500	Falha ao guardar a imagem	`{"error":"failed to store avatar","detail":"..."}`
503	Armazenamento de mídia indisponível na loja	`{"error":"media storage unavailable"}`

Veja também

Perfil

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

GET/api/v1/storefront/profileCliente

Lê o perfil do cliente logado

Exemplo de requisição

bash

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

Resposta

200Perfil

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"
}

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.

Status	Quando	Corpo
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
404	Usuá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

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.

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"
}'

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

Status	Quando	Corpo
400	Corpo 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"}`
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
403	Documento 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"}`
404	Usuário não encontrado	`{"error":"user not found"}`
409	CPF ou e-mail já usados por outra conta	`{"error":"cpf_already_registered","fields":{"cpf":"already_registered"}}` / `{"error":"email_already_registered"}`
500	Falha ao gravar	`{"error":"failed to update profile","detail":"..."}`

POST/api/v1/storefront/profile/avatarCliente

Envia a foto de perfil

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).

bash

curl -X POST "$BASE_URL/api/v1/storefront/profile/avatar" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@foto.png"

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

Status	Quando	Corpo
400	Nã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"}`
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
404	Usuário não encontrado	`{"error":"user not found"}`
500	Falha ao guardar a imagem	`{"error":"failed to store avatar","detail":"..."}`
503	Armazenamento de mídia indisponível na loja	`{"error":"media storage unavailable"}`