VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Guia rápido/Clientes

Listar clientes

Retorna os usuários da loja com filtros e paginação, e traz a busca avançada, a presença de PF e PJ e os totais.

Use estas operações para varrer a base de clientes: um CRM que sincroniza cadastros novos, um ERP que procura um cliente pelo CNPJ, ou uma tela de busca. A lista traz o resumo de cada usuário. Para endereços, grupos e campos de perfil, abra o usuário com Consultar cliente.

A mesma lista serve a clientes, administradores e usuários de seller: o filtro user_type escolhe quem entra. Quando você filtra por customer, os logins de subcontas (funcionários de uma empresa B2B) ficam de fora por padrão, porque o cliente comercial é a empresa.

GET/api/v1/admin/usersAdmin

Lista os usuários

Exige view_users ou manage_users. Os filtros se combinam (E lógico).

Query parameters

pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
Itens por página, de 1 a 100. Fora do intervalo volta ao padrão (não é limitado).
sort_bystringpadrão: created_at
created_atemailfirst_namelast_namelast_login_atupdated_atlogin_count
Campo de ordenação. Outro valor cai em created_at. O desempate é pelo id.
sort_dirstringpadrão: desc
ascdesc
Direção.
user_typestring
customervendoradminroot_admin
Um tipo de usuário.
user_typesstring
Vários tipos separados por vírgula (admin,vendor). Tem precedência sobre user_type.
vendor_iduuid
Usuários ligados a este seller (dono e equipe).
exclude_trade_rep_managersbooleanpadrão: true
Ao listar vendor, esconde os gerentes de venda que não são donos de seller. Mande false para incluí-los.
exclude_subaccountsbooleanpadrão: true
Ao listar customer, esconde subcontas B2B. Mande false para ver todos os logins.
statusstring
ADP
Status, por letra ou palavra (active, disabled, pending, inactive, deleted).
searchstring
Texto livre: e-mail, nome, CPF e CNPJ (contém).
emailstring
E-mail (contém).
phonestring
Telefone (contém).
cpfstring
CPF exato, com ou sem pontuação.
cnpjstring
CNPJ exato, com ou sem pontuação.
person_typestring
FPFJPJ
Tipo de pessoa efetivo (declarado, ou deduzido do documento).
citystring
Cidade do endereço padrão (contém).
statestring
UF do endereço padrão.
countrystring
País do endereço padrão.
languagestring
pt-BRenes
Idioma da conta.
email_verifiedboolean
true ou false. Valor inválido é ignorado.
marketing_opt_inboolean
Aceitou comunicação de marketing.
whatsapp_opt_inboolean
Aceitou comunicação por WhatsApp.
registered_afterstring
Cadastro a partir de (AAAA-MM-DD ou RFC 3339).
registered_beforestring
Cadastro até. Com AAAA-MM-DD o dia inteiro entra.
last_login_afterstring
Último login a partir de.
last_login_beforestring
Último login até (dia inteiro com AAAA-MM-DD).
has_ordersboolean
true: tem ao menos um pedido; false: nunca comprou.
min_total_spendinteger
Gasto total mínimo, em centavos, somando os pedidos não cancelados.
max_total_spendinteger
Gasto total máximo, em centavos.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/users?user_type=customer&person_type=J&has_orders=true&sort_by=created_at&sort_dir=desc&per_page=50" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Usuários retornados
json
{
  "users": [
    {
      "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,
      "account_type": "individual",
      "person_type": "J",
      "person_type_declared": true,
      "display_name": "Pão Doce",
      "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
    }
  ],
  "total": 8173,
  "page": 1,
  "per_page": 50,
  "total_pages": 164
}

Campos da resposta

usersarray
Usuários da página. Cada item tem os campos descritos em Consultar cliente. Nas listas, sms_opt_in, push_opt_in, whatsapp_opt_in e notify_on_orders podem vir false mesmo quando a conta tem outro valor: leia o usuário para o valor real.
totalinteger
Total que atende ao filtro, em todas as páginas.
pageinteger
Página retornada.
per_pageinteger
Itens por página aplicados.
total_pagesinteger
Quantidade de páginas.
POST/api/v1/admin/users/searchAdmin

Busca avançada de usuários

Busca com critérios no corpo, útil quando o filtro é longo ou combina grupo e endereço. Exige view_users ou manage_users (é uma leitura, apesar do POST). A resposta tem o mesmo formato de GET /api/v1/admin/users.

Corpo da requisição

searchstring
Texto livre em e-mail, nome e sobrenome.
user_typestring
customervendoradmin
Tipo de usuário.
statusstring
ADP
Status.
emailstring
E-mail (contém).
phonestring
Telefone (contém).
citystring
Cidade de algum endereço do usuário.
statestring
UF de algum endereço.
postal_codestring
CEP de algum endereço.
countrystring
País de algum endereço.
cpfstring
CPF exato.
cnpjstring
CNPJ exato.
usergroup_iduuid
Quem pertence a este grupo.
created_afterstring
Cadastro a partir de (AAAA-MM-DD).
created_beforestring
Cadastro até.
last_login_afterstring
Último login a partir de.
last_login_beforestring
Último login até.
pageintegerpadrão: 1
Página.
per_pageintegerpadrão: 20
Itens por página, de 1 a 100.
sort_bystringpadrão: created_at
Campo de ordenação.
sort_orderstringpadrão: desc
ascdesc
Direção. Atenção ao nome: aqui é sort_order, não sort_dir.
GET/api/v1/admin/users/person-type-presenceAdmin

Quais tipos de pessoa existem na loja

Responde se a loja tem ao menos um cliente PF e ao menos um PJ. Serve para telas que só mostram o filtro de CPF ou de CNPJ quando ele pode encontrar alguém. Exige view_users ou manage_users. Em caso de dúvida a resposta é true para os dois, nunca esconde.

200Presença por tipo
json
{ "has_pf": true, "has_pj": true }
GET/api/v1/admin/users/stats/summaryAdmin

Totais de usuários para um painel

Contagens para um painel: total, por status, por tipo e cadastros recentes. Exige view_users ou manage_users.

200Totais
json
{
  "total_users": 8175,
  "active_users": 8172,
  "pending_users": 0,
  "disabled_users": 1,
  "total_customers": 8044,
  "total_vendors": 114,
  "total_admins": 16,
  "new_users_today": 4,
  "new_users_week": 6,
  "new_users_month": 8
}

Campos da resposta

total_usersinteger
Usuários não excluídos.
active_usersinteger
Com status A.
pending_usersinteger
Deveria contar o status P, mas hoje conta uma letra que nenhuma conta usa e por isso vem 0. Para saber quantos estão pendentes use GET /api/v1/admin/users?status=pending e leia total.
disabled_usersinteger
Com status D.
total_customersinteger
Usuários do tipo customer.
total_vendorsinteger
Usuários do tipo vendor.
total_adminsinteger
Usuários do tipo admin.
new_users_todayinteger
Cadastrados hoje.
new_users_weekinteger
Cadastrados na semana.
new_users_monthinteger
Cadastrados no mês.

Erros

StatusQuandoCorpo
400(busca avançada) corpo que não é JSON{"error":"invalid request body","detail":"..."}
401Sem credenciais, chave inválida ou token expirado{"error":"missing authorization header"} ou {"error":"invalid or expired token"}
403Usuário sem o privilégio necessário{"error":"insufficient privileges","privilege_required_any":["manage_users","view_users"]}
429Limite de requisições{"error":"rate limit exceeded","detail":"too many requests, please try again later"}
500Falha interna, ou UUID inválido em vendor_id{"error":"failed to list users","detail":"..."}
Como sincronizar cadastros com um CRM

Ordene por updated_at crescente (sort_by=updated_at&sort_dir=asc) e guarde o maior updated_at já processado: ele muda quando o cadastro muda, não só quando nasce. Use registered_after apenas para cadastros novos.

Contas B2B repetem o CNPJ

Filtrar por cnpj pode devolver várias contas: contas da mesma empresa podem compartilhar o CNPJ. Ao procurar "a empresa", escolha pelo account_type (individual, corporate_parent ou subaccount) e pelo e-mail, não pelo primeiro resultado.

Veja também

  • Consultar cliente
  • Criar cliente
  • Ações em lote
  • Pedidos
Anterior
Clientes
Próxima
Consultar cliente
Nesta página
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também