Zavvi API

Retorna as pesquisas do usuário autenticado, das mais recentes para as mais antigas. O resultado é paginado: use per_page (padrão 15, máximo 100) e page na query string. A resposta traz também os blocos links e meta da paginação.

Resposta

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-...",
      "title": "Satisfacao no Atendimento",
      "status": "published",
      "url": "https://www.zavvi.com.br/s/a1b2c3d4-e5f6-...",
      "questions_count": 8,
      "responses_count": 342,
      "created_at": "2026-01-15T10:30:00Z"
    }
  ]
}

Retorna os detalhes de uma pesquisa específica. A lista de questões não vem neste endpoint — o objeto traz apenas os contadores questions_count e responses_count, além de identificação, textos e cores. Para obter as questões, use GET /surveys/{uuid}/questions.

Resposta

{
  "data": {
    "id": "a1b2c3d4-e5f6-...",
    "title": "Satisfacao no Atendimento",
    "status": "published",
    "url": "https://www.zavvi.com.br/s/a1b2c3d4-e5f6-...",
    "welcome_message": "Ola! Leva 1 minuto.",
    "goodbye_text": "Obrigado pela participacao!",
    "redirect_url": null,
    "visibility": true,
    "is_template": false,
    "notify_new_responses": true,
    "color": "#7c3aed",
    "question_color": "#ffffff",
    "answer_color": "#ffffff",
    "button_color": "#7c3aed",
    "button_text_color": "#ffffff",
    "background_color": "#0b0b12",
    "logo": null,
    "questions_count": 8,
    "responses_count": 342,
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-20T09:00:00Z"
  }
}

Cria uma nova pesquisa. Requer assinatura ativa e limite de pesquisas não atingido. Envie sempre welcome_message e goodbye_text junto com o título: as duas colunas não aceitam valor nulo no banco e a criação só com title falha.

Parâmetros

Atualiza uma pesquisa existente. Apenas o dono pode atualizar.

Remove permanentemente uma pesquisa e todas as suas questões e respostas.

Cria uma copia da pesquisa com todas as questões. A copia inicia como rascunho com zero respostas.

Retorna todas as questões da pesquisa ordenadas por posição (sem paginação). O campo choices só é preenchido para os tipos multiple-choices, yes-no, dropdown e slider; nos demais tipos ele vem null.

Resposta

{
  "data": [
    {
      "id": 1,
      "survey_id": 7,
      "type": "rating",
      "text": "De 0 a 10, quanto voce recomendaria?",
      "position": 1,
      "visibility": true,
      "is_required": true,
      "attributes": { "scale": 10 },
      "choices": null,
      "image": null
    }
  ]
}

Adiciona uma questão à pesquisa. Requer limite de questões não atingido.

Parâmetros

Atualiza uma questão existente. A rota é rasa: use o ID numérico da questão direto em /api/v1/questions/{id}, sem o UUID da pesquisa. Os campos aceitos são os mesmos da criação, todos opcionais (text e type não podem ser enviados vazios).

Remove uma questão. Assim como no update, a rota é rasa e usa apenas o ID numérico da questão. Retorna 204 sem corpo.

Retorna as respostas de uma pesquisa uma linha por questão respondida — não vêm agrupadas por respondente. Para reconstruir o questionário de cada pessoa, agrupe as linhas pelo campo attendee_id, que identifica o respondente. Cada linha já traz a questão correspondente embutida em question.

O resultado é paginado e ordenado da resposta mais recente para a mais antiga: use per_page (padrão 50) e page na query string.

Resposta

{
  "data": [
    {
      "id": 981,
      "survey_id": 7,
      "question_id": 1,
      "attendee_id": 4512,
      "response": "9",
      "question": {
        "id": 1,
        "type": "rating",
        "text": "De 0 a 10, quanto voce recomendaria?"
      },
      "created_at": "2026-03-18T14:30:00Z",
      "updated_at": "2026-03-18T14:30:00Z"
    }
  ],
  "links": { "..." },
  "meta": { "..." }
}

Submete respostas para uma pesquisa. Rate limit: 10 requisições/minuto por IP. A pesquisa precisa estar publicada — caso contrário a API responde 403 com "This survey is not available.". Cada chamada cria um novo respondente com todas as respostas enviadas no corpo.

Parâmetros

Exemplo

{
  "responses": [
    { "question_id": 1, "response": "9" },
    { "question_id": 2, "response": "Atendimento excelente!" },
    { "question_id": 3, "response": "Sim" }
  ]
}

Resposta

{
  "data": [
    {
      "id": 981,
      "survey_id": 7,
      "question_id": 1,
      "attendee_id": 4512,
      "response": "9",
      "created_at": "2026-03-18T14:30:00Z",
      "updated_at": "2026-03-18T14:30:00Z"
    }
  ]
}

Retorna os totais da pesquisa, a taxa de conclusão e um detalhamento por questão. A resposta não é embrulhada em data — os campos vêm na raiz do JSON. Não existe um bloco scores com nps/csat/ces: o único indicador calculado é o NPS por questão, e apenas para questões do tipo rating.

Campos da raiz

Campos de cada item de questions

Resposta

{
  "survey_id": "a1b2c3d4-e5f6-...",
  "title": "Satisfacao no Atendimento",
  "total_responses": 342,
  "total_attendees": 405,
  "total_questions": 8,
  "completion_rate": 84.5,
  "questions": [
    {
      "question_id": 1,
      "text": "De 0 a 10, quanto voce recomendaria?",
      "type": "rating",
      "response_count": 120,
      "average_rating": 8.74,
      "nps": 72
    },
    {
      "question_id": 2,
      "text": "Voce voltaria a comprar?",
      "type": "yes-no",
      "response_count": 118,
      "distribution": { "Sim": 101, "Nao": 17 }
    }
  ]
}

Retorna todos os planos disponíveis com preços e limites.

Resposta

{
  "data": [
    {
      "id": 1,
      "title": "Gratuito",
      "price": 0,
      "interval": "monthly",
      "is_free": true,
      "limits": {
        "survey_count": 3,
        "question_count_per_survey": 10,
        "response_count_per_survey": 100
      }
    },
    {
      "id": 2,
      "title": "Starter",
      "price": 49.00,
      "is_free": false,
      "limits": { "..." }
    }
  ]
}

Tags dinamicas permitem personalizar o texto da pesquisa para cada destinatario. Use placeholders no formato {{NOME_DA_TAG}} nos campos da pesquisa, e envie os valores correspondentes no campo context da API.

Como Funciona

{
  "channel": "email",
  "recipient": {
    "name": "Joao Silva",
    "email": "joao@email.com"
  },
  "context": {
    "NOME_CLIENTE": "Joao Silva",
    "NRO_PEDIDO": "PED-2026-00142"
  },
  "subject": "{{NOME_CLIENTE}}, como foi seu pedido {{NRO_PEDIDO}}?"
}

Onde as tags funcionam

Regras

• Tags usam o formato {{NOME_TAG}} — apenas letras, numeros e underscore entre as chaves (sem espacos, acentos ou hifens)
• As tags sao livres: voce pode usar qualquer nome que quiser
• Se uma tag nao tiver valor no context, ela permanece no texto exatamente como foi escrita — o destinatario ve {{NOME_TAG}}. Envie sempre todas as tags usadas na pesquisa, mesmo que com string vazia
• A unica situacao em que as tags somem do texto e quando o acesso nao tem nenhum context associado e a pesquisa e do tipo Pesquisa API: ai todas as tags sao apagadas de uma vez. Em pesquisas comuns sem context, elas continuam visiveis
• Os valores do context precisam ser strings de ate 500 caracteres — numeros e objetos aninhados sao recusados com 422
• As tags sao case-sensitive: NOME e nome sao tags diferentes
• Cada destinatario recebe um link unico com seus dados personalizados

Tags no Envio em Massa

No endpoint de envio em massa (POST /send/bulk), cada destinatario pode ter seu proprio context:

{
  "channel": "email",
  "subject": "{{NOME_CLIENTE}}, avalie seu pedido",
  "recipients": [
    {
      "name": "Joao Silva",
      "email": "joao@email.com",
      "context": {
        "NOME_CLIENTE": "Joao Silva",
        "NRO_PEDIDO": "PED-001"
      }
    },
    {
      "name": "Maria Santos",
      "email": "maria@email.com",
      "context": {
        "NOME_CLIENTE": "Maria Santos",
        "NRO_PEDIDO": "PED-002"
      }
    }
  ]
}

Painel de Acompanhamento

Todos os envios via API sao rastreados e podem ser acompanhados no painel API do dashboard, incluindo:

• Status de cada envio (pendente, enviado, entregue, falha)
• Dados do context enviado para cada destinatario
• Taxa de conclusao (quem abriu e respondeu a pesquisa)
• Possibilidade de reenvio para envios que falharam

Envia uma pesquisa para um destinatário por e-mail ou WhatsApp. Use o campo context para passar valores das tags dinamicas configuradas na pesquisa. O envio é síncrono.

Parâmetros

Exemplo

{
  "channel": "email",
  "recipient": {
    "name": "Carlos Eduardo",
    "email": "carlos@email.com"
  },
  "context": {
    "NOME_CLIENTE": "Carlos Eduardo",
    "NRO_PEDIDO": "PED-2026-00142"
  },
  "subject": "{{NOME_CLIENTE}}, como foi seu pedido {{NRO_PEDIDO}}?"
}

Resposta

{
  "data": {
    "id": 123,
    "channel": "email",
    "recipient": "carlos@email.com",
    "status": "sent",
    "sent_at": "2026-03-18T14:30:00Z",
    "attendee_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Status

Envia pesquisas para múltiplos destinatários de uma vez. Os envios são enfileirados e processados em background. Máximo de 500 destinatários por requisição. Um canal por request.

Parâmetros

Exemplo

{
  "channel": "email",
  "subject": "Como foi sua experiência?",
  "recipients": [
    {
      "name": "Carlos Eduardo",
      "email": "carlos@email.com",
      "context": { "NOME_CLIENTE": "Carlos Eduardo", "NRO_PEDIDO": "PED-001" }
    },
    {
      "name": "Maria Silva",
      "email": "maria@email.com",
      "context": { "NOME_CLIENTE": "Maria Silva", "NRO_PEDIDO": "PED-002" }
    }
  ]
}

Resposta

{
  "data": {
    "batch_id": "batch_abc123xyz456",
    "channel": "email",
    "total": 2,
    "status": "queued",
    "message": "2 envios foram enfileirados para processamento."
  }
}

Status

Retorna o QR Code da pesquisa em formato PNG (base64) ou SVG.

Query Params

Exemplo

curl -X GET https://www.zavvi.com.br/api/v1/surveys/{uuid}/qrcode?format=png&size=400 \
  -H "X-API-Key: sua_chave_aqui" \
  -H "Accept: application/json"

Resposta

{
  "data": {
    "survey_id": "a1b2c3d4-e5f6-...",
    "survey_url": "https://www.zavvi.com.br/s/a1b2c3d4-e5f6-...",
    "format": "png",
    "size": 400,
    "qrcode": "data:image/png;base64,iVBORw0KGgo..."
  }
}

Status