Avaliações do restaurante e do Clube

Use GET /v1/ratings para consultar as avaliações do restaurante, incluindo todas as origens. Para consultar somente as avaliações atuais do Clube integradas ao Takeat, use o filtro channel=clube nesta mesma rota. Todas as consultas retornam o mesmo objeto organizado e exigem a permissão ratings:read para OAuth.

Credencial e permissões

Troque sua chave por um access token em /oauth/token, conforme o guia de autenticação. Envie o token como Bearer.

A rota também aceita sessão autenticada do próprio restaurante, limitada ao tenant assinado. Para integrações com várias lojas, informe um restaurant_id autorizado. Chaves tk_ precisam ser trocadas por tokens antes da consulta.

Para adicionar ratings:read a uma chave existente, edite suas permissões e obtenha um novo token. Apps OAuth precisam incluir o escopo na definição do app e passar novamente pelo consentimento do restaurante; refresh não amplia acesso. As descrições de consentimento informam que a consulta pode incluir nome e telefone do cliente, quando disponíveis. A permissão ratings:read é exigida para qualquer canal, inclusive clube; clube:read é usada nas consultas de clientes do Clube.

Filtros e paginação

curl "$TAKEAT_API_URL/v1/ratings?channel=clube&start_date=2026-10-01&end_date=2026-10-19&page=1&per_page=100" \
  -H "Authorization: Bearer $TAKEAT_ACCESS_TOKEN"

As avaliações são ordenadas por created_at DESC, id DESC. Ao avançar, aplique pagination.next aos parâmetros da chamada original, preservando período, restaurante e canal. Cada página usa um snapshot consistente para lista e resumo; inserções entre requisições podem deslocar páginas. A leitura pode refletir atraso da réplica do banco.

Como interpretar o retorno

Exemplo de resposta com channel=clube, uma avaliação nesta página e três no período:

{
  "data": [
    {
      "id": 41,
      "score": 5,
      "comment": "Ótimo atendimento!",
      "source": {
        "channel": "clube"
      },
      "customer": {
        "id": 9,
        "name": "Cliente exemplo",
        "phone": null
      },
      "criteria": [
        {
          "name": "Atendimento",
          "score": 5
        },
        {
          "name": "Comida",
          "score": 4
        }
      ],
      "context": {
        "table": null,
        "table_session": null,
        "clube_purchase_id": 123
      },
      "created_at": "2026-10-10T15:00:00.000Z",
      "updated_at": "2026-10-10T15:00:00.000Z"
    }
  ],
  "pagination": {
    "count": 1,
    "limit": 1,
    "total": 3,
    "has_more": true,
    "next": {
      "page": 2,
      "per_page": 1
    }
  },
  "meta": {
    "restaurant_id": 2,
    "period": {
      "start_date": "2026-10-01",
      "end_date": "2026-10-19",
      "timezone": "UTC"
    },
    "channel": "clube",
    "summary": {
      "total": 3,
      "average_score": 4.33
    }
  }
}

• score: nota geral armazenada, normalmente de 1 a 5; valores legados são preservados.
• criteria: critérios individuais e suas notas. Critérios antigos sem nota têm score: null; zero é preservado.
• customer: somente ID, nome e telefone; null quando não há cliente associado.
• context.table_session: ID interno e número da comanda (session_number), quando vinculada.
• context.clube_purchase_id: ID da compra no Clube, distinto de uma comanda Takeat.
• meta.summary: quantidade e média sobre todas as correspondências do período e canal, não apenas a página.
• pagination: count é o tamanho desta página, total é o total filtrado e next: null encerra a navegação.

Sem avaliações, a resposta é 200 com data: [], total zero e average_score: null. Campos opcionais permanecem presentes com null; não há dados completos de contas. Uma página além do fim retorna data: [] e mantém o resumo do período.

Avaliações do Clube e erros

O filtro channel=clube consulta somente avaliações atuais já gravadas no Takeat. O histórico antigo mantido exclusivamente no banco do api-clube não faz parte desta consulta. Avaliações já gravadas continuam consultáveis mesmo que a configuração do Clube não esteja ativa, sem chamadas externas ao serviço do Clube.

Entradas inválidas, períodos invertidos ou superiores a 92 dias recebem 400; token ausente ou inválido recebe 401; falta de escopo ou restaurante sem acesso recebe 403. Erros seguem { statusCode, message, key } e incluem X-Error-Id.