Listar clientes

Retorna os usuários da loja com filtros e paginação, no formato da Venddor 1.0.

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, com uma letra (C, V ou A), escolhe quem entra. Os campos seguem o formato da Venddor 1.0: user_id, firstname, user_type em letra e datas em Unix.

GET/api/v1.0/usersAdmin

Listar usuários

Autenticação: HTTP Basic com e-mail:chave_de_api de um administrador, ou Authorization: Bearer <JWT>. A ordem é fixa: do cadastro mais recente para o mais antigo. A rota também responde em /api/users, com ids decimais (Rotas sem versão).

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1. Valor inválido ou menor que 1 é ignorado.

items_per_pageintegerpadrão: 10

Itens por página, de 1 a 250. Fora desse intervalo (ou texto) vale o padrão 10; o valor não é limitado a 250.

user_typestring

AVC

Tipo: A administrador, V usuário de seller, C cliente. Qualquer outra letra filtra por cliente.

statusstring

ADP

Status. Aceita a letra ou a palavra (active, disabled, pending).

emailstring

Texto procurado em e-mail, nome, CPF e CNPJ (contém, sem diferenciar maiúsculas). Apesar do nome, não é igualdade de e-mail.

cnpjstring

CNPJ exato, com ou sem pontuação.

user_ids[]string

Restringe a estes ids. Cuidado: o filtro é aplicado depois da paginação e params.total_items ignora o filtro, então a página pode voltar vazia. Para buscar um cliente conhecido use Consultar cliente.

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/users?user_type=C&status=A&items_per_page=50&page=1"

Resposta

200Usuários retornados

json

{
  "params": { "page": 1, "items_per_page": 50, "total_items": 8043 },
  "users": [
    {
      "user_id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
      "profile_id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
      "email": "contato@paodoce.example.com",
      "firstname": "Padaria Pão Doce Ltda",
      "lastname": "",
      "user_type": "C",
      "status": "A",
      "password": "",
      "phone": "+551133334444",
      "fax": "",
      "url": "",
      "company": "",
      "company_id": 0,
      "usergroup_ids": "",
      "lang_code": "pt-BR",
      "timestamp": 1791752151,
      "tax_exempt": "N",
      "birthday": "",
      "registration_date": "2026-10-11 20:55:51",
      "last_login": 0,
      "CNPJ": "11222333000181"
    }
  ]
}

Campos da resposta

paramsobject

Paginação: page, items_per_page e total_items (total que atende ao filtro, em todas as páginas).

usersarray

Usuários da página. Na lista, usergroup_ids vem sempre vazio e não há fields nem usergroups; eles só vêm em Consultar cliente.

users[].user_idstring

Id do usuário (UUID; decimal em /api/users). profile_id é igual.

users[].user_typestring

AVC

Tipo do usuário.

users[].statusstring

ADP

Status em letra.

users[].firstnamestring

Nome. Numa PJ, a razão social inteira.

users[].lastnamestring

Sobrenome. Vazio numa PJ.

users[].phonestring

Telefone, em formato internacional quando gravado pela plataforma.

users[].CNPJstring

Só aparece quando o usuário tem CNPJ. Dígitos, sem máscara. O CPF não é devolvido pela API 1.0.

users[].passwordstring

Sempre "". Mantido por compatibilidade; a plataforma nunca devolve senha.

users[].company_idinteger

Sempre 0 na lista. O id do seller de um usuário V vem em Consultar cliente.

users[].lang_codestring

Idioma da conta (pt-BR, en, es).

users[].timestampinteger

Data de cadastro, Unix (segundos, UTC). registration_date é a mesma data em texto.

users[].last_logininteger

Último login em Unix; 0 se nunca entrou.

users[].faxstring

Sempre vazio. Campos url, birthday e tax_exempt ("N") também são fixos, por compatibilidade.

Erros

Status	Quando	Corpo
401	Sem credenciais, chave inválida ou token expirado	`{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}` ou `{"message":"Invalid credentials","status":401}`
403	Usuário que não é administrador	`{"message":"Forbidden: admin scope required","status":403}`

Veja também

Listar clientes

Retorna os usuários da loja com filtros e paginação, no formato da Venddor 1.0.

GET/api/v1.0/usersAdmin

Listar usuários

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1. Valor inválido ou menor que 1 é ignorado.

items_per_pageintegerpadrão: 10

Itens por página, de 1 a 250. Fora desse intervalo (ou texto) vale o padrão 10; o valor não é limitado a 250.

user_typestring

AVC

Tipo: A administrador, V usuário de seller, C cliente. Qualquer outra letra filtra por cliente.

statusstring

ADP

Status. Aceita a letra ou a palavra (active, disabled, pending).

emailstring

Texto procurado em e-mail, nome, CPF e CNPJ (contém, sem diferenciar maiúsculas). Apesar do nome, não é igualdade de e-mail.

cnpjstring

CNPJ exato, com ou sem pontuação.

user_ids[]string

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/users?user_type=C&status=A&items_per_page=50&page=1"

Resposta

200Usuários retornados

json

{
  "params": { "page": 1, "items_per_page": 50, "total_items": 8043 },
  "users": [
    {
      "user_id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
      "profile_id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
      "email": "contato@paodoce.example.com",
      "firstname": "Padaria Pão Doce Ltda",
      "lastname": "",
      "user_type": "C",
      "status": "A",
      "password": "",
      "phone": "+551133334444",
      "fax": "",
      "url": "",
      "company": "",
      "company_id": 0,
      "usergroup_ids": "",
      "lang_code": "pt-BR",
      "timestamp": 1791752151,
      "tax_exempt": "N",
      "birthday": "",
      "registration_date": "2026-10-11 20:55:51",
      "last_login": 0,
      "CNPJ": "11222333000181"
    }
  ]
}

Campos da resposta

paramsobject

Paginação: page, items_per_page e total_items (total que atende ao filtro, em todas as páginas).

usersarray

Usuários da página. Na lista, usergroup_ids vem sempre vazio e não há fields nem usergroups; eles só vêm em Consultar cliente.

users[].user_idstring

Id do usuário (UUID; decimal em /api/users). profile_id é igual.

users[].user_typestring

AVC

Tipo do usuário.

users[].statusstring

ADP

Status em letra.

users[].firstnamestring

Nome. Numa PJ, a razão social inteira.

users[].lastnamestring

Sobrenome. Vazio numa PJ.

users[].phonestring

Telefone, em formato internacional quando gravado pela plataforma.

users[].CNPJstring

Só aparece quando o usuário tem CNPJ. Dígitos, sem máscara. O CPF não é devolvido pela API 1.0.

users[].passwordstring

Sempre "". Mantido por compatibilidade; a plataforma nunca devolve senha.

users[].company_idinteger

Sempre 0 na lista. O id do seller de um usuário V vem em Consultar cliente.

users[].lang_codestring

Idioma da conta (pt-BR, en, es).

users[].timestampinteger

Data de cadastro, Unix (segundos, UTC). registration_date é a mesma data em texto.

users[].last_logininteger

Último login em Unix; 0 se nunca entrou.

users[].faxstring

Sempre vazio. Campos url, birthday e tax_exempt ("N") também são fixos, por compatibilidade.

Erros

Status	Quando	Corpo
401	Sem credenciais, chave inválida ou token expirado	`{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}` ou `{"message":"Invalid credentials","status":401}`
403	Usuário que não é administrador	`{"message":"Forbidden: admin scope required","status":403}`