Consultar cliente

Retorna o cadastro completo de um usuário e as estatísticas de compra dele.

Use esta operação quando você já tem o id do usuário e quer o cadastro inteiro: documento, nome da empresa (PJ), idioma, preferências de contato, status, grupos e campos de perfil. Para achar o id a partir de um e-mail ou documento, use Listar clientes com search, email ou cnpj.

O que a consulta não traz: endereços (veja Endereços), pedidos (Pedidos, com o filtro customer_id) e formas de pagamento (Formas de pagamento do cliente). A senha e o hash nunca saem pela API.

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

Consulta um usuário

Exige view_users ou manage_users.

Path parameters

iduuidobrigatório

Id do usuário. Um valor que não é UUID responde 500 (veja a tabela de erros).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/users/3dc023ca-3746-4b6e-8afd-686a4a9af99f" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Cliente PJ

json

{
  "id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
  "email": "contato@paodoce.example.com",
  "user_type": "customer",
  "status": "A",
  "first_name": "Padaria Pão Doce Ltda",
  "last_name": "",
  "phone": "+551133334444",
  "cnpj": "11222333000181",
  "legal_name": "Padaria Pão Doce Ltda",
  "trade_name": "Pão Doce",
  "language": "pt-BR",
  "currency": "BRL",
  "timezone": "America/Sao_Paulo",
  "email_verified": false,
  "login_count": 0,
  "is_root": false,
  "whatsapp_opt_in": false,
  "sms_opt_in": false,
  "push_opt_in": true,
  "notify_on_orders": true,
  "account_type": "individual",
  "person_type": "J",
  "person_type_declared": true,
  "display_name": "Pão Doce",
  "responsible_name": "João Pereira",
  "created_at": "2026-10-11T20:55:51.332285Z",
  "updated_at": "2026-10-11T20:56:18.510829Z",
  "user_id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
  "firstname": "Padaria Pão Doce Ltda",
  "lastname": "",
  "tax_id": "11222333000181",
  "timestamp": 1791752151,
  "updated_timestamp": 1791752178
}

Campos da resposta

iduuid

Id do usuário. user_id repete o mesmo valor.

emailstring

E-mail de login, sempre em minúsculas. Único entre os usuários não excluídos.

user_typestring

customervendoradminroot_admin

Papel do usuário.

statusstring

ADP

A ativo, D desativado, P pendente.

first_namestring

Nome. Numa PJ é a razão social inteira (espelho de legal_name).

last_namestring

Sobrenome. Vazio numa PJ.

phonestring

Telefone, em formato internacional (+55...) quando gravado pela plataforma. Vazio se não informado.

avatar_urlstring

URL da foto de perfil. Só aparece quando existe.

cpfstring

CPF, 11 dígitos sem máscara. Só aparece quando existe.

cnpjstring

CNPJ, 14 caracteres sem máscara. Só aparece quando existe.

legal_namestring

Razão social (PJ). Só aparece quando existe.

trade_namestring

Nome fantasia (PJ). Só aparece quando existe.

state_regstring

Inscrição estadual (PJ). Só aparece quando existe.

person_typestring

FJ

Tipo de pessoa efetivo: F física, J jurídica. Sempre preenchido.

person_type_declaredboolean

true se alguém declarou o tipo; false se ele foi deduzido do documento.

display_namestring

O nome que uma tela deve mostrar: nome fantasia, senão razão social, senão responsável, senão nome e sobrenome.

responsible_namestring

Nome do responsável de uma conta PJ (campo de perfil). Só aparece na consulta de um usuário.

company_namestring

Nome da empresa para telas B2B (subcontas mostram a empresa-mãe). Só aparece em listas e buscas, e só quando há empresa.

languagestring

pt-BRenes

Idioma da conta.

currencystring

Moeda preferida (BRL).

timezonestring

Fuso do usuário (America/Sao_Paulo).

email_verifiedboolean

E-mail confirmado. email_verified_at traz a data (RFC 3339), quando existe.

last_login_atstring

Último login (RFC 3339, UTC). Ausente se nunca entrou. login_count conta os logins.

vendor_namestring

Para usuário de seller, o nome do seller a que pertence.

is_rootboolean

Dono da loja ou do seller. Ignora os privilégios de grupo.

whatsapp_phonestring

Número usado no consentimento de WhatsApp, quando existe.

whatsapp_opt_inboolean

Aceitou receber mensagens por WhatsApp.

marketing_consent_atstring

Quando aceitou marketing (RFC 3339). Ausente se não aceitou.

terms_accepted_atstring

Aceite dos termos de uso, quando existe.

privacy_accepted_atstring

Aceite da política de privacidade, quando existe.

sms_opt_inboolean

Aceitou SMS.

push_opt_inboolean

Aceitou notificações push.

notify_on_ordersboolean

Recebe aviso de pedido novo (relevante para administradores e gerentes).

account_typestring

individualcorporate_parentsubaccount

individual é uma conta comum; corporate_parent é a conta-mãe de uma empresa B2B; subaccount é um comprador (funcionário) da empresa.

created_atstring

Cadastro (RFC 3339, UTC). updated_at é a última alteração.

firstnamestring

Campos de apelido, repetem outros campos do objeto: user_id, firstname, lastname, tax_id (CPF ou CNPJ), timestamp (cadastro em Unix), updated_timestamp e last_login (Unix, só se já entrou).

GET/api/v1/admin/users/{id}/statsAdmin

Estatísticas de compra de um usuário

Resume o comportamento de compra do usuário: quantos pedidos, quanto gastou, ticket médio e pontualidade de pagamento. Exige view_users ou manage_users. Dinheiro em centavos.

Path parameters

iduuidobrigatório

Id do usuário.

200Estatísticas

json

{
  "user_id": "264a70c1-9c69-458d-ac73-838543f87da2",
  "total_orders": 12,
  "total_paid_orders": 10,
  "total_spend_centavos": 482350,
  "average_order_value": 48235,
  "first_order_at": "2026-02-03T14:20:11Z",
  "last_order_at": "2026-10-02T09:41:50Z",
  "total_addresses": 2,
  "account_age_days": 250,
  "payment_punctuality": {
    "email": "maria.souza@example.com",
    "orders_4_months": 4,
    "late_payments_4_months": 0,
    "orders_5_years": 12,
    "late_payments_5_years": 1,
    "overdue_letter": "Y"
  }
}

Campos da resposta

total_ordersinteger

Pedidos do usuário.

total_paid_ordersinteger

Pedidos pagos.

total_spend_centavosinteger

Soma gasta, em centavos.

average_order_valueinteger

Ticket médio, em centavos.

first_order_atstring

Data do primeiro pedido. Ausente se nunca comprou. last_order_at é o mais recente.

total_addressesinteger

Endereços cadastrados.

account_age_daysinteger

Dias desde o cadastro.

payment_punctualityobject

Histórico por e-mail (vale para qualquer conta com esse e-mail): orders_4_months e late_payments_4_months nos últimos 4 meses, orders_5_years e late_payments_5_years nos últimos 5 anos. overdue_letter é a letra do status "pagamento em atraso" da loja. Pode estar ausente.

Erros

Status	Quando	Corpo
401	Sem credenciais, chave inválida ou token expirado	`{"error":"invalid or expired token"}`
403	Falta `view_users`/`manage_users`	`{"error":"insufficient privileges","privilege_required_any":["manage_users","view_users"]}`
404	Usuário não existe ou foi excluído	`{"error":"user not found"}`
500	Id que não é UUID	`{"error":"failed to get user","detail":"o valor \"abc\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}`

Veja também

Consultar cliente

Retorna o cadastro completo de um usuário e as estatísticas de compra dele.

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

Consulta um usuário

Exige view_users ou manage_users.

Path parameters

iduuidobrigatório

Id do usuário. Um valor que não é UUID responde 500 (veja a tabela de erros).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/users/3dc023ca-3746-4b6e-8afd-686a4a9af99f" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Cliente PJ

json

{
  "id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
  "email": "contato@paodoce.example.com",
  "user_type": "customer",
  "status": "A",
  "first_name": "Padaria Pão Doce Ltda",
  "last_name": "",
  "phone": "+551133334444",
  "cnpj": "11222333000181",
  "legal_name": "Padaria Pão Doce Ltda",
  "trade_name": "Pão Doce",
  "language": "pt-BR",
  "currency": "BRL",
  "timezone": "America/Sao_Paulo",
  "email_verified": false,
  "login_count": 0,
  "is_root": false,
  "whatsapp_opt_in": false,
  "sms_opt_in": false,
  "push_opt_in": true,
  "notify_on_orders": true,
  "account_type": "individual",
  "person_type": "J",
  "person_type_declared": true,
  "display_name": "Pão Doce",
  "responsible_name": "João Pereira",
  "created_at": "2026-10-11T20:55:51.332285Z",
  "updated_at": "2026-10-11T20:56:18.510829Z",
  "user_id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
  "firstname": "Padaria Pão Doce Ltda",
  "lastname": "",
  "tax_id": "11222333000181",
  "timestamp": 1791752151,
  "updated_timestamp": 1791752178
}

Campos da resposta

iduuid

Id do usuário. user_id repete o mesmo valor.

emailstring

E-mail de login, sempre em minúsculas. Único entre os usuários não excluídos.

user_typestring

customervendoradminroot_admin

Papel do usuário.

statusstring

ADP

A ativo, D desativado, P pendente.

first_namestring

Nome. Numa PJ é a razão social inteira (espelho de legal_name).

last_namestring

Sobrenome. Vazio numa PJ.

phonestring

Telefone, em formato internacional (+55...) quando gravado pela plataforma. Vazio se não informado.

avatar_urlstring

URL da foto de perfil. Só aparece quando existe.

cpfstring

CPF, 11 dígitos sem máscara. Só aparece quando existe.

cnpjstring

CNPJ, 14 caracteres sem máscara. Só aparece quando existe.

legal_namestring

Razão social (PJ). Só aparece quando existe.

trade_namestring

Nome fantasia (PJ). Só aparece quando existe.

state_regstring

Inscrição estadual (PJ). Só aparece quando existe.

person_typestring

FJ

Tipo de pessoa efetivo: F física, J jurídica. Sempre preenchido.

person_type_declaredboolean

true se alguém declarou o tipo; false se ele foi deduzido do documento.

display_namestring

O nome que uma tela deve mostrar: nome fantasia, senão razão social, senão responsável, senão nome e sobrenome.

responsible_namestring

Nome do responsável de uma conta PJ (campo de perfil). Só aparece na consulta de um usuário.

company_namestring

Nome da empresa para telas B2B (subcontas mostram a empresa-mãe). Só aparece em listas e buscas, e só quando há empresa.

languagestring

pt-BRenes

Idioma da conta.

currencystring

Moeda preferida (BRL).

timezonestring

Fuso do usuário (America/Sao_Paulo).

email_verifiedboolean

E-mail confirmado. email_verified_at traz a data (RFC 3339), quando existe.

last_login_atstring

Último login (RFC 3339, UTC). Ausente se nunca entrou. login_count conta os logins.

vendor_namestring

Para usuário de seller, o nome do seller a que pertence.

is_rootboolean

Dono da loja ou do seller. Ignora os privilégios de grupo.

whatsapp_phonestring

Número usado no consentimento de WhatsApp, quando existe.

whatsapp_opt_inboolean

Aceitou receber mensagens por WhatsApp.

marketing_consent_atstring

Quando aceitou marketing (RFC 3339). Ausente se não aceitou.

terms_accepted_atstring

Aceite dos termos de uso, quando existe.

privacy_accepted_atstring

Aceite da política de privacidade, quando existe.

sms_opt_inboolean

Aceitou SMS.

push_opt_inboolean

Aceitou notificações push.

notify_on_ordersboolean

Recebe aviso de pedido novo (relevante para administradores e gerentes).

account_typestring

individualcorporate_parentsubaccount

individual é uma conta comum; corporate_parent é a conta-mãe de uma empresa B2B; subaccount é um comprador (funcionário) da empresa.

created_atstring

Cadastro (RFC 3339, UTC). updated_at é a última alteração.

firstnamestring

GET/api/v1/admin/users/{id}/statsAdmin

Estatísticas de compra de um usuário

Resume o comportamento de compra do usuário: quantos pedidos, quanto gastou, ticket médio e pontualidade de pagamento. Exige view_users ou manage_users. Dinheiro em centavos.

Path parameters

iduuidobrigatório

Id do usuário.

200Estatísticas

json

{
  "user_id": "264a70c1-9c69-458d-ac73-838543f87da2",
  "total_orders": 12,
  "total_paid_orders": 10,
  "total_spend_centavos": 482350,
  "average_order_value": 48235,
  "first_order_at": "2026-02-03T14:20:11Z",
  "last_order_at": "2026-10-02T09:41:50Z",
  "total_addresses": 2,
  "account_age_days": 250,
  "payment_punctuality": {
    "email": "maria.souza@example.com",
    "orders_4_months": 4,
    "late_payments_4_months": 0,
    "orders_5_years": 12,
    "late_payments_5_years": 1,
    "overdue_letter": "Y"
  }
}

Campos da resposta

total_ordersinteger

Pedidos do usuário.

total_paid_ordersinteger

Pedidos pagos.

total_spend_centavosinteger

Soma gasta, em centavos.

average_order_valueinteger

Ticket médio, em centavos.

first_order_atstring

Data do primeiro pedido. Ausente se nunca comprou. last_order_at é o mais recente.

total_addressesinteger

Endereços cadastrados.

account_age_daysinteger

Dias desde o cadastro.

payment_punctualityobject

Erros

Status	Quando	Corpo
401	Sem credenciais, chave inválida ou token expirado	`{"error":"invalid or expired token"}`
403	Falta `view_users`/`manage_users`	`{"error":"insufficient privileges","privilege_required_any":["manage_users","view_users"]}`
404	Usuário não existe ou foi excluído	`{"error":"user not found"}`
500	Id que não é UUID	`{"error":"failed to get user","detail":"o valor \"abc\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}`