OmniTicketz API Documentation

GET/api/v1/api-clientes

Lista clientes do tenant com sincronização automática por API Key.

Sincronização Automática

Por padrão, ao chamar este endpoint, os clientes retornados são automaticamente marcados como sincronizados para sua API Key. Use ?marcar_sincronizado=false para apenas consultar sem marcar.

Sincronização Multi-Sistema

Cada API Key representa uma integração diferente. O Sistema X puxa clientes e eles são marcados como sincronizados apenas para ele. O Sistema Y ainda verá os mesmos clientes como não sincronizados.

Autenticação

Permissão necessária: clientes:read

Parâmetros

Sincronização

Parâmetro	Tipo	Padrão	Descrição
`sincronizado`	boolean	—	false = não sincronizados, true = já sincronizados, omitir = todos
`marcar_sincronizado`	boolean	`true`	Marcar clientes retornados como sincronizados

Filtros

Parâmetro	Tipo	Padrão	Descrição
`email`	string	—	Busca parcial por email
`cpf`	string	—	Busca exata por CPF (somente números)
`desde`	string	—	YYYY-MM-DD - Clientes criados a partir desta data
`limit`	number	`50`	Itens por página (máx: 500)
`offset`	number	`0`	Pular N registros (paginação)

Ordenação

Parâmetro	Tipo	Padrão	Descrição
`order_by`	string	`created_at`	Campo: created_at, nome, email, ultimo_login
`order`	string	`desc`	Direção: desc ou asc

Exemplos de Uso

Sincronizar clientes novos

Busca e marca automaticamente como sincronizados:

curl -X GET "https://sua-plataforma.com.br/api/v1/api-clientes?sincronizado=false" \
  -H "X-API-Key: sk_live_SUA_CHAVE_AQUI"

Consultar sem marcar

curl -X GET "https://sua-plataforma.com.br/api/v1/api-clientes?sincronizado=false&marcar_sincronizado=false" \
  -H "X-API-Key: sk_live_SUA_CHAVE_AQUI"

Buscar por CPF

curl -X GET "https://sua-plataforma.com.br/api/v1/api-clientes?cpf=12345678900&marcar_sincronizado=false" \
  -H "X-API-Key: sk_live_SUA_CHAVE_AQUI"

Resposta

200OK

{
  "success": true,
  "data": [
    {
      "id": "uuid...",
      "email": "joao@email.com",
      "nome": "João",
      "sobrenome": "Silva",
      "nome_completo": "João Silva",
      "cpf": "12345678900",
      "telefone": "31999999999",
      "whatsapp": "31999999999",
      "data_nascimento": "1990-05-15",
      "endereco": { "rua": "...", "cidade": "..." },
      "avatar_url": null,
      "ativo": true,
      "ultimo_login": "2026-01-20T14:30:00Z",
      "estatisticas": {
        "total_pedidos": 5,
        "total_vouchers": 12,
        "valor_total_gasto": 1250.00,
        "primeiro_pedido": "2025-06-15T10:00:00Z",
        "ultimo_pedido": "2026-01-02T15:00:00Z"
      },
      "created_at": "2025-06-01T08:00:00Z",
      "updated_at": "2026-01-20T14:30:00Z"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 50,
    "offset": 0,
    "has_more": true,
    "order_by": "created_at",
    "order": "desc",
    "auto_sync": true,
    "marcados_para_sync": 50
  }
}

Fluxo típico de integração

Chame ?sincronizado=false para obter clientes novos (marca automaticamente)
Processe os dados no seu sistema
Na próxima chamada, apenas clientes novos aparecerão

Autenticação

Vouchers