Clientes e Clube

GET /v1/clients lista os buyers vinculados ao restaurante autorizado, inclusive vínculos importados e clientes sem compras. O id é o ID Takeat e permanece igual após o cadastro no Clube. A rota não inclui pessoas existentes somente no Clube e não mescla buyers que compartilham telefone.

Permissão e consulta

Selecione explicitamente clients:read, na categoria Relacionamento. Chaves e instalações existentes não recebem essa permissão automaticamente. Para API keys, atualize as permissões da chave e emita um novo access token; para apps OAuth, configure o escopo, obtenha novo consentimento da loja e emita os tokens correspondentes. O escopo clube:read sozinho não libera esta rota.

Use Authorization: Bearer $ACCESS_TOKEN. Sessões autenticadas do restaurante também são aceitas, limitadas à loja assinada. Chaves tk_ não são enviadas diretamente ao endpoint. O token interno do Clube nunca é informado pelo integrador.

curl "$TAKEAT_API_URL/v1/clients?page=1&per_page=100&registered_in_clube=true&restaurant_id=$RESTAURANT_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

O filtro de cadastro considera somente vínculos e clientes ativos no Clube daquela loja, antes da contagem e da paginação. A ordenação é id crescente. Continue até page = total_pages. Página excedente retorna clients: [] com os totais preservados; base vazia retorna total_pages: 0. Não há snapshot entre requisições de páginas diferentes.

{
  "page": 1, "per_page": 100, "total": 1, "total_pages": 1,
  "clients": [{
    "id": 42, "name": "Cliente exemplo", "phone": "5527999990001", "email": null,
    "registered_in_clube": true, "cashback": "12.30",
    "cashback_expires_at": "2026-11-20T15:00:00.000Z",
    "purchases_count": 2, "last_purchase_at": "2026-10-20T15:00:00.000Z", "total_spent": "70.50",
    "clube": {
      "id": 900, "name": "Nome no Clube", "email": null, "birthday": "1995-06-18",
      "gender": null, "registered_at": "2026-09-01T12:00:00.000Z", "points": null
    }
  }]
}

Identidade e saldo

name, phone e email da raiz vêm do buyer. O telefone é normalizado como dígitos com DDI 55; aceita DDD+número de 10/11 dígitos ou esse número já prefixado. Não se infere DDD ou nono dígito, nem se usa telefone intermediário de marketplace. Telefone ausente ou fora do formato resulta em null e não é consultado no Clube.

clube.id identifica o cadastro no serviço do Clube. Seus demais campos são próprios desse cadastro; campos ausentes são null. registered_at é a criação do vínculo com a loja, birthday é YYYY-MM-DD, e points preserva string ou null.

O cashback pode existir mesmo para um buyer ainda não cadastrado. A API considera compras, resgates, validade e limite da loja; para cadastrados, o saldo recalculado não excede o saldo armazenado. Saldo consumido ou expirado é "0.00" com expiração null; saldo positivo traz a expiração. Sem Clube, no modelo de pontos ou sem telefone consultável, cashback e expiração são null. Sem Clube configurado, a listagem continua disponível com registered_in_clube: false e clube: null.

Como interpretar as compras

As métricas vêm das vendas Takeat da loja autorizada, e não do histórico financeiro do Clube:

• Uma compra por buyer e sessão finished/completed; também conta delivery com pedido delivered/finished, mesmo com sessão aberta. Pedidos cancelados são excluídos; pendentes ou em preparo não qualificam uma sessão aberta.
• O buyer do pedido tem precedência; sem ele, usa-se o buyer da conta individual. Uma mesa compartilhada não atribui seu total inteiro a cada pessoa.
• total_spent soma cada order_baskets.total_price válido uma vez. Não acrescenta pagamentos, frete ou taxas armazenados separadamente.
• last_purchase_at usa o início da sessão, com criação como fallback. Sem compras: quantidade zero, data null e total "0.00".

Erros e compatibilidade

Uma falha do Clube não é disfarçada como ausência de cadastro ou saldo. A resposta falha integralmente. Use X-Error-Id para suporte, sem compartilhar tokens ou dados pessoais.

GET /v1/clube/clients continua com seu contrato e escopo clube:read. Sua população pode diferir desta rota. Comparações devem usar a mesma loja e momento de referência, considerando clientes exclusivos do Clube e deliveries entregues ainda abertos.

Baixar coleção Postman desta rota. A referência, os documentos Markdown e a busca de documentação pelo MCP derivam deste guia e do OpenAPI V1; a ferramenta de dados get_clients é descrita abaixo.

Consulta pelo MCP

A ferramenta get_clients usa o mesmo serviço e os mesmos campos de cliente da rota REST. Exige clients:read, além de menu:read para a conexão MCP. Credenciais e consentimentos existentes não recebem a permissão automaticamente; revise os escopos e reconecte quando necessário.

{
  "name": "get_clients",
  "arguments": {
    "restaurant_id": 85,
    "page": 1,
    "per_page": 25,
    "registered_in_clube": false
  }
}

No MCP, per_page tem padrão 25 e máximo 50. A resposta usa { data, pagination }: os clientes ficam em data; pagination contém count, limit, total, has_more e next. Continue com pagination.next, preservando restaurant_id e registered_in_clube, até has_more: false. Informe quando uma análise cobrir apenas parte dos clientes. Esses limites não alteram a paginação REST.

O filtro é booleano: false lista clientes sem cadastro ativo no Clube; true lista cadastrados; omita para ambos. A consulta funciona sem Clube configurado e não inclui pessoas existentes somente no Clube. Para a população do programa de fidelidade, use get_clube_clients, que mantém seu contrato independente.