Lendo respostas pela API

Depois de distribuir a pesquisa, a API devolve o que chegou de duas formas: a lista de respostas (uma linha por pergunta respondida) e o analytics (os números já calculados). Este artigo mostra as duas e como ligá-las ao que você vê no painel.

Todos os endpoints daqui pedem só a chave de API — não são exclusivos do plano Escala. Se ainda não tem a chave, comece por API de pesquisas.

Listar respostas

curl -X GET "https://www.zavvi.com.br/api/v1/surveys/{uuid}/responses" \
  -H "X-API-Key: sua_chave_aqui" \
  -H "Accept: application/json"

A resposta vem paginada, das mais recentes para as mais antigas:

{
  "data": [
    {
      "id": 9871,
      "survey_id": 42,
      "question_id": 118,
      "attendee_id": 5502,
      "response": "9",
      "question": {
        "id": 118,
        "survey_id": 42,
        "type": "rating",
        "text": "De 0 a 10, quanto você nos recomendaria?",
        "position": 1,
        "visibility": true,
        "is_required": true,
        "attributes": { "scale": 10 },
        "choices": [],
        "image": null,
        "created_at": "2026-08-01T10:31:00.000000Z",
        "updated_at": "2026-08-01T10:31:00.000000Z"
      },
      "created_at": "2026-08-16T14:52:11.000000Z",
      "updated_at": "2026-08-16T14:52:11.000000Z"
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "last_page": 7, "per_page": 50, "total": 342 }
}

Três coisas importantes sobre esse formato:

• Cada item é uma resposta a uma pergunta, não um respondente inteiro. Quem respondeu quatro perguntas gera quatro itens.
• attendee_id é o que agrupa. Junte os itens pelo mesmo attendee_id para remontar o questionário de uma pessoa.
• response é sempre texto. Uma nota 9 chega como "9"; converta no seu lado antes de fazer conta.

O bloco question vem junto para você não precisar de uma segunda chamada só para descobrir o texto e o tipo da pergunta.

Paginação

Por padrão são 50 respostas por página. Use per_page para mudar e siga o links.next até ele vir nulo:

curl -X GET "https://www.zavvi.com.br/api/v1/surveys/{uuid}/responses?per_page=100&page=2" \
  -H "X-API-Key: sua_chave_aqui" \
  -H "Accept: application/json"

Não existe webhook

A API não avisa o seu sistema quando chega uma resposta nova — a consulta é sempre iniciada por você. Na prática, agende uma leitura periódica (a cada 15 minutos costuma bastar), guarde o maior id já processado e ignore o que for menor ou igual a ele na próxima rodada. Lembre do limite de 60 requisições por minuto.

Se o que você precisa é ser avisado quando alguém reclama, o caminho certo não é a API: são os alertas do Radar de IA, que mandam e-mail, WhatsApp ou abrem chamado interno.

Ler as métricas prontas

Se você só quer o número consolidado, o endpoint de analytics evita baixar milhares de linhas:

curl -X GET "https://www.zavvi.com.br/api/v1/surveys/{uuid}/analytics" \
  -H "X-API-Key: sua_chave_aqui" \
  -H "Accept: application/json"

{
  "survey_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "Satisfação no Atendimento",
  "total_responses": 342,
  "total_attendees": 405,
  "total_questions": 4,
  "completion_rate": 84.5,
  "questions": [
    {
      "question_id": 118,
      "text": "De 0 a 10, quanto você nos recomendaria?",
      "type": "rating",
      "response_count": 338,
      "average_rating": 8.61,
      "nps": 72
    },
    {
      "question_id": 119,
      "text": "Você voltaria a comprar com a gente?",
      "type": "yes-no",
      "response_count": 330,
      "distribution": { "Sim": 301, "Não": 29 }
    }
  ]
}

O que cada campo significa:

• survey_id — o UUID da pesquisa. title — o título dela.
• total_attendees — quantas pessoas abriram/iniciaram a pesquisa.
• total_responses — o total de respostas registradas na pesquisa.
• total_questions — quantas perguntas a pesquisa tem.
• completion_rate — porcentagem, com uma casa decimal, de quem respondeu todas as perguntas visíveis, sobre o total de pessoas que abriram. Vem null quando ainda não há ninguém ou quando a pesquisa não tem perguntas visíveis.
• questions — um bloco por pergunta, sempre com question_id, text, type e response_count.

Dentro de questions, dois extras aparecem conforme o tipo:

• Perguntas de avaliação (rating) trazem average_rating (média com duas casas) e nps. O nps segue a fórmula clássica na escala de 0 a 10: percentual de notas 9 e 10 menos o percentual de notas de 0 a 6, arredondado para inteiro. Ele só aparece quando há pelo menos uma nota numérica maior que zero.
• Perguntas de escolha (multiple-choices, yes-no, dropdown) trazem distribution: um objeto com a contagem de cada alternativa, da mais escolhida para a menos escolhida.

Os demais tipos (texto curto, texto longo, número, data, e-mail, telefone, slider) entram na lista só com a contagem de respostas — para eles, leia o conteúdo pelo endpoint de respostas.

Se precisar do texto das perguntas

O endpoint de perguntas dá a lista completa, na ordem de exibição, útil para montar as colunas de um relatório antes de percorrer as respostas:

curl -X GET "https://www.zavvi.com.br/api/v1/surveys/{uuid}/questions" \
  -H "X-API-Key: sua_chave_aqui" \
  -H "Accept: application/json"

Registrar respostas do seu próprio formulário

Se a pesquisa é preenchida dentro do seu sistema — um totem, um app, uma tela sua —, dá para gravar as respostas direto:

curl -X POST "https://www.zavvi.com.br/api/v1/surveys/{uuid}/responses" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "responses": [
      { "question_id": 118, "response": "9" },
      { "question_id": 120, "response": "Atendimento excelente!" }
    ]
  }'

Detalhes que fazem diferença:

• Este endpoint é público: não leva o header X-API-Key.
• responses é uma lista, com pelo menos um item, e cada item precisa de question_id (número) e response (texto). Perguntas que não pertencem àquela pesquisa são simplesmente ignoradas.
• A pesquisa precisa estar ativa; se estiver inativa, a resposta é 403 com This survey is not available.
• O limite é de 10 requisições por minuto por IP — bem mais apertado que o resto da API, porque é um endpoint aberto.
• Cada chamada cria um respondente novo e anônimo. Ela não se junta a um convite disparado pela API: se você quer amarrar a resposta a um envio, mande o cliente para o link ?a={attendee_uuid} em vez de usar este endpoint.
• Quando a cota de respostas do plano estoura, a chamada passa a ser recusada.

Cruzando com o painel

Os mesmos dados aparecem em vários lugares, e vale saber qual usar:

• Resultados da pesquisa — indicadores, funil de abandono, gráficos por pergunta e respostas individuais, em tempo real. É a visão mais completa e não exige nenhuma linha de código. Veja Resultados e exportação.
• Exportação CSV/Excel — uma linha por resposta, com os dados de contexto. Para uma análise pontual, costuma ser mais rápido que escrever uma integração.
• API → Envios — a ponte entre o disparo e a resposta: mostra o context mandado, o status do envio e se aquele convite virou pesquisa respondida. A Taxa de Conclusão do painel de API é calculada só sobre os envios feitos pela API, então ela pode ser diferente da completion_rate do analytics, que considera todos os respondentes da pesquisa, tenham vindo da API, do link, do QR Code ou do widget.
• Radar de IA — a leitura qualitativa: causas raiz, severidade e relatórios executivos.
• Central de Atendimento — as notas do cliente ao lado da conversa dele (Pontuação de satisfação).

Uma diferença que confunde: o NPS do analytics é calculado sobre perguntas do tipo avaliação, com a fórmula descrita acima. As telas do painel usam os tipos de pergunta dedicados a NPS, CSAT e CES e podem apresentar os números de outro jeito — se você precisa que um relatório externo bata com o painel na casa decimal, compare os dois antes de publicar. Sobre o que cada métrica mede, veja NPS, CSAT e CES.

Boas práticas

• Guarde o attendee_id (ou o attendee_uuid devolvido no disparo) junto do pedido ou do atendimento no seu banco. É o que transforma "nota 6" em "nota 6 do pedido PED-2026-00142".
• Prefira o analytics para dashboards e a lista de respostas para carga de dados. Baixar 10 mil linhas para calcular uma média é desperdício.
• Respeite os limites: 60 requisições por minuto na leitura, 10 por minuto por IP no envio público.
• Se a pesquisa tem anonimizar respostas ou dias de retenção configurados, isso vale também para a API — respostas antigas somem no prazo definido. Veja Segurança e privacidade.

A referência completa dos endpoints, com todos os campos, está em /docs/api.