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

Clientes por token de app

Acesso de aplicativos de terceiros aos clientes, com token vat_ e escopos read_customers e write_customers, sem usuário administrador.

Um app de terceiros (um conector de CRM, uma ferramenta de e-mail marketing, um sistema de fidelidade) não deve usar o login de uma pessoa. A plataforma oferece o token de app: o app é cadastrado no portal de desenvolvedores da loja, recebe um token que começa com vat_live_ ou vat_test_ e só pode o que os escopos aprovados permitem.

As rotas de clientes sob /api/admin/... aceitam esse token. Elas leem e alteram os mesmos cadastros das demais rotas desta seção, mas com um formato próprio: ids em UUID, nomes de campo como first_name e email, datas em RFC 3339 e paginação por page e per_page. Esta página descreve o cabeçalho, os escopos, as rotas, os parâmetros e a resposta de cada uma. O mesmo mecanismo vale para pedidos (Pedidos por token de app).

Pontos-chave
  • Cabeçalho: Authorization: Bearer vat_live_... (o token do app, não um JWT de usuário).
  • Escopos: read_customers para ler clientes e endereços, write_customers para alterar, read_orders para os pedidos de um cliente. Sem o escopo, a resposta é 403.
  • Aceita somente token de app. Um JWT de usuário nestas rotas responde 401 app_token_required.
  • Os privilégios finos do painel (como manage_users) não são verificados aqui; o que vale é o escopo aprovado para o app.
  • Não há criação, exclusão, mudança de status, senha, grupos nem pagamento por token de app. Para isso use as rotas /api/v1.0 com um usuário administrador.
  • Ids são UUID em texto e a resposta usa JSON; dinheiro, quando aparece, é inteiro em centavos.

Rotas disponíveis com token de app

RotaEscopoO que faz
GET /api/admin/usersread_customersLista usuários, com filtros e paginação.
GET /api/admin/users/{id}read_customersConsulta um usuário.
PUT /api/admin/users/{id}write_customersAltera dados de um usuário.
GET /api/admin/users/{id}/addressesread_customersLista os endereços de um usuário.
GET /api/admin/users/{id}/ordersread_ordersLista os pedidos de um cliente.
GET/api/admin/usersAutenticada

Listar usuários

Escopo read_customers. Os filtros se combinam (E lógico).

Parâmetros de consulta

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.
GET/api/admin/users/{id}Autenticada

Consultar um usuário

Escopo read_customers. Devolve o cadastro completo do usuário.

Parâmetros de caminho

iduuidobrigatório
Id do usuário.
PUT/api/admin/users/{id}Autenticada

Atualizar um usuário

Escopo write_customers. Só os campos enviados mudam e a resposta é o usuário atualizado. Como o app não é um usuário, a proteção contra o administrador alterar a si mesmo não se aplica: cuide dos campos user_type, status e is_root, que um app com write_customers consegue mudar.

Parâmetros de caminho

iduuidobrigatório
Id do usuário.

Corpo da requisição

first_namestring
Nome. Numa PJ, o valor é substituído pela razão social.
last_namestring
Sobrenome. Numa PJ, fica vazio.
emailstring
Novo e-mail (vira minúsculo). Se já existe em outro usuário: 400 email already in use.
phonestring
Telefone, gravado em formato internacional.
user_typestring
customervendoradminroot_admin
Papel. Fora da lista: 400 invalid user_type.
statusstring
ADP
Status. Aceita letra ou palavra. Fora da lista: 400 invalid status.
cpfstring
CPF, validado pelos dígitos. "" apaga.
cnpjstring
CNPJ, validado pelos dígitos. "" apaga.
state_regstring
Inscrição estadual (PJ).
person_typestring
FPFJPJ
Declara ou troca o tipo de pessoa.
legal_namestring
Razão social (PJ). Atualiza também first_name.
trade_namestring
Nome fantasia (PJ).
responsible_namestring
Responsável da conta PJ (campo de perfil).
responsible_cpfstring
CPF do responsável da PJ.
languagestring
pt-BRenes
Idioma da conta. Outro valor: 400 invalid language.
currencystring
Moeda preferida (BRL).
timezonestring
Fuso (America/Sao_Paulo).
whatsapp_phonestring
Número do consentimento de WhatsApp.
whatsapp_opt_inboolean
Aceite de WhatsApp.
marketing_opt_inboolean
Aceite de marketing: true grava a data de agora, false apaga.
notify_on_ordersboolean
Recebe aviso de pedido novo.
is_rootboolean
Marca o usuário como dono. Só um dono pode enviar este campo (senão 403).
GET/api/admin/users/{id}/addressesAutenticada

Listar os endereços de um usuário

Escopo read_customers. Usuário sem endereços devolve lista vazia ([]).

Parâmetros de caminho

iduuidobrigatório
Id do usuário.
GET/api/admin/users/{id}/ordersAutenticada

Listar os pedidos de um usuário

Os pedidos de um cliente, no mesmo formato da lista de pedidos (Listar pedidos), já filtrados por esse cliente. Aceita os demais filtros e a paginação da lista de pedidos. Escopo read_orders.

Parâmetros de caminho

iduuidobrigatório
Id do cliente.

Exemplo de requisição

bash
curl "$BASE_URL/api/admin/users?user_type=customer&sort_by=updated_at&sort_dir=asc&per_page=50" \
  -H "Authorization: Bearer $APP_TOKEN"

Resposta da lista

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.

Resposta da consulta de um usuário

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

Resposta da alteração

200Usuário alterado (trecho)
json
{
  "id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
  "email": "contato@paodoce.example.com",
  "user_type": "customer",
  "status": "A",
  "first_name": "Padaria Pão Doce Ltda",
  "phone": "+5511977776666",
  "legal_name": "Padaria Pão Doce Ltda",
  "trade_name": "Pão Doce Centro",
  "person_type": "J",
  "display_name": "Pão Doce Centro",
  "updated_at": "2026-10-11T20:56:18.510829Z"
}

A resposta é o usuário completo, com os campos da consulta acima.

Resposta dos endereços

200Endereços do usuário
json
{
  "addresses": [
    {
      "id": "d9e1749d-ae6a-4f9a-8943-22d93d90cde0",
      "user_id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
      "label": "Matriz",
      "is_default": true,
      "first_name": "Padaria Pão Doce Ltda",
      "last_name": "",
      "address_line1": "Avenida Paulista, 1000",
      "complement": "Sala 14",
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01310-100",
      "country": "BR",
      "phone": "1133334444",
      "created_at": "2026-10-11T20:56:23.338259Z",
      "updated_at": "2026-10-11T20:57:46.981711Z"
    }
  ],
  "total": 1
}

Campos do endereço

iduuid
Id do endereço. address_id repete o valor.
user_iduuid
Dono do endereço.
labelstring
Apelido ("Casa", "Matriz"). Pode ser vazio.
is_defaultboolean
Endereço padrão do usuário. Só um por usuário.
first_namestring
Nome do destinatário. Para destinatário PJ, a razão social inteira.
last_namestring
Sobrenome do destinatário. Pode ser vazio.
address_line1string
Logradouro e número (Avenida Paulista, 1000).
address_line2string
Segunda linha, quando existe (a vitrine usa para o número).
complementstring
Complemento (Sala 14, Bloco B). Campo próprio, não se mistura com address_line2.
districtstring
Bairro. district_id é o id no catálogo de bairros, quando o bairro existe lá.
citystring
Cidade. city_id é o id no catálogo de cidades, quando a cidade existe lá (usado para casar áreas de entrega).
statestring
UF (SP).
postal_codestring
CEP, como foi enviado (01310-100 ou 01310100).
countrystringpadrão: BR
País (código de 2 letras).
phonestring
Telefone do destinatário, gravado como veio (sem normalizar).
typestring
Apelido fixo (D).
s_*, b_*string
Apelidos para entrega (s_firstname, s_lastname, s_address, s_city, s_state, s_zipcode, s_country, s_phone) e cobrança (b_*, os mesmos nomes). Sempre iguais aos campos acima.
created_atstring
Criação (RFC 3339). updated_at é a última alteração.

Erros

StatusQuandoCorpo
400Corpo da alteração que não é JSON, ou campo recusado (por exemplo status ou user_type inválido){"error":"invalid request body","detail":"..."} ou {"error":"invalid status: zzz (must be active, disabled, or pending)"}
401Sem token, ou um JWT de usuário no lugar do token de app{"error":"app_token_required"}
401Token de app inválido, revogado ou expirado{"error":"invalid or expired app access token"}
403O app não tem o escopo exigido pela rota{"error":"missing_scope","required":"read_customers"}
404Usuário inexistente{"error":"user not found"}
500Id que não é UUID{"error":"failed to get user","detail":"..."}
Sincronize por data de alteração

Para um conector que só quer o que mudou, ordene com sort_by=updated_at&sort_dir=asc e guarde o maior updated_at já lido. Ele muda quando o cadastro muda, não só quando nasce.

Veja também

  • Listar clientes
  • Alterar cliente
  • Pedidos por token de app
Anterior
Pedidos e carrinho
Próxima
Cliente por CNPJ (modo específico)
Nesta página
  • Rotas disponíveis com token de app
  • Exemplo de requisição
  • Resposta da lista
  • Resposta da consulta de um usuário
  • Resposta da alteração
  • Resposta dos endereços
  • Erros
  • Veja também