Listar respostas da pesquisa

Esta rota permite consultar as respostas da pesquisa de satisfação de um estabelecimento, com filtros por período, por pesquisa e paginação.

Cada resposta vem com a pergunta e a resposta já casadas: além do que o cliente respondeu, o retorno traz o título da pergunta, se ela era obrigatória, a posição dela na pesquisa e, quando faz sentido, a escala usada e as opções que estavam disponíveis. Assim é possível mapear o feedback no seu CRM sem consultar a configuração da pesquisa à parte.

Parâmetros

Todos opcionais, enviados na query string.

Parâmetro	Descrição
startDate	Data inicial, no formato YYYY-MM-DD. Padrão: hoje.
endDate	Data final, no formato YYYY-MM-DD. Padrão: hoje.
surveyId	Restringe o resultado a uma pesquisa específica.
page	Página desejada. Padrão: 1.
perPage	Itens por página. Padrão e máximo: 100.

O intervalo entre startDate e endDate não pode passar de 31 dias, e endDate precisa ser maior ou igual a startDate.

O estabelecimento é identificado pelo token de autenticação — não existe parâmetro de loja.

Tipos de pergunta

Cada item de questions traz id, title, type, required e order, mais um bloco aninhado com o nome do tipo. Só o bloco correspondente ao type da pergunta aparece.

O id é o da pergunta, não o da resposta, e é por ele que você relaciona a mesma pergunta entre respostas diferentes.

NPS

Nota de 0 a 10, com justificativa opcional.

{
  "id": "64a1",
  "title": "O quanto você recomendaria?",
  "type": "NPS",
  "required": true,
  "order": 0,
  "nps": {
    "explanationEnabled": true,
    "rate": 9,
    "explanation": "Atendimento ótimo"
  }
}

explanationEnabled diz se a pesquisa pedia a justificativa; explanation vem null quando o cliente não escreveu nada.

OPEN_TEXT

Resposta escrita livremente.

{
  "id": "64a2",
  "title": "Deixe seu comentário",
  "type": "OPEN_TEXT",
  "required": false,
  "order": 1,
  "openText": { "content": "Demorou um pouco na entrega do prato" }
}

RATING

Uma ou mais características avaliadas de 1 a 5.

{
  "id": "64a3",
  "title": "Avalie nosso restaurante",
  "type": "RATING",
  "required": true,
  "order": 2,
  "rating": {
    "scale": "EMOJI",
    "characteristics": [
      { "id": "64b1", "name": "Atendimento", "rate": 5 },
      { "id": "64b2", "name": "Comida", "rate": 4 }
    ]
  }
}

scale indica como a escala foi apresentada ao cliente — EMOJI ou NUMERIC. Em ambos os casos rate é sempre um número de 1 a 5: emoji é uma forma de exibição, não um valor diferente.

MULTIPLE_CHOICE

Seleção entre opções pré-definidas, com campo livre opcional.

{
  "id": "64a4",
  "title": "Como nos conheceu?",
  "type": "MULTIPLE_CHOICE",
  "required": false,
  "order": 3,
  "multipleChoice": {
    "maxSelection": 2,
    "otherEnabled": true,
    "availableOptions": [
      { "id": "64c1", "name": "Instagram" },
      { "id": "64c2", "name": "Indicação" }
    ],
    "selectedOptions": [{ "id": "64c1", "name": "Instagram" }],
    "otherContent": "Passei em frente"
  }
}

availableOptions são todas as opções que a pesquisa oferecia e selectedOptions as que o cliente marcou. otherContent só vem preenchido quando a pesquisa permitia a opção livre e o cliente a usou.

CUSTOMER_DATA

Dado de identificação pedido ao cliente.

{
  "id": "64a5",
  "title": "Seu CPF",
  "type": "CUSTOMER_DATA",
  "required": true,
  "order": 4,
  "customerData": { "field": "CPF", "value": "12345678900" }
}

Exemplo de resposta

{
  "pagination": { "total": 245, "totalPages": 3, "page": 1 },
  "data": [
    {
      "id": "66f0a1c2e4b0d3f1a2b3c4d5",
      "survey": {
        "id": "6a7381b692b87b1fe00c9760",
        "title": "Pesquisa de satisfação",
        "available": true
      },
      "channel": "QRCODE",
      "answeredAt": "2026-09-10T20:14:00.000Z",
      "table": { "code": "12", "waiterName": "João" },
      "questions": [
        {
          "id": "64a1",
          "title": "O quanto você recomendaria?",
          "type": "NPS",
          "required": true,
          "order": 0,
          "nps": {
            "explanationEnabled": true,
            "rate": 9,
            "explanation": "Atendimento ótimo"
          }
        }
      ]
    }
  ]
}

channel identifica por onde a resposta foi coletada: QRCODE, TABLET, TOTEM, SELF_SERVICE, DELIVERY ou POS.

O bloco table só aparece quando a resposta veio de uma mesa; code e waiterName aparecem individualmente, conforme a informação exista.

Campos que podem vir nulos

Uma pesquisa pode ser editada depois que as respostas já foram coletadas. Quando a pergunta respondida não existe mais na pesquisa atual, o título e a resposta continuam disponíveis, mas o que só existia na configuração vem nulo:

• required e order vêm null;
• type vem null e, nesse caso, nenhum bloco de tipo é publicado;
• em RATING e MULTIPLE_CHOICE, scale, maxSelection e availableOptions refletem a mesma limitação.

Trate esses campos como opcionais na sua integração: a resposta em si nunca se perde.

Códigos de resposta

Código	Quando acontece
200	Consulta bem-sucedida. Loja sem pesquisa ou período sem resposta devolve data: [] e total: 0 — não é erro.
400	Intervalo maior que 31 dias, endDate anterior a startDate ou data fora do formato YYYY-MM-DD.
401	Token da loja ausente ou inválido, ou assinatura sem a funcionalidade de integrações.
429	Limite de requisições excedido. Veja Limites de uso.
500	Falha ao consultar o serviço de pesquisas.

Documentação da API

Para informações detalhadas sobre parâmetros, payload e exemplos de resposta, consulte a documentação técnica completa.