Disparando pesquisas pela API

Este é o uso mais comum da API: o seu sistema termina um atendimento, fecha um pedido ou dá baixa numa entrega e, na mesma hora, dispara a pesquisa para aquele cliente — com o nome dele e os dados do pedido dentro da mensagem.

Os endpoints de disparo são exclusivos do plano Escala. Em outros planos eles respondem 403 com Este recurso é exclusivo do plano Escala. Faça upgrade para acessar.

Antes de começar, tenha em mãos a sua chave e o UUID da pesquisa — veja API de pesquisas.

1. Prepare a pesquisa

1. Crie a pesquisa normalmente e ative ela. Pesquisa inativa não abre para quem recebe o convite.
2. Abra a pesquisa e, no bloco de tipo de pesquisa, marque Pesquisa API ("Envio via API com tags dinâmicas"). A opção só aparece no plano Escala; no plano padrão fica marcada Pesquisa Padrão.
3. Se quiser personalizar textos por destinatário, use tags dinâmicas — veja mais abaixo.

2. Envio individual

curl -X POST "https://www.zavvi.com.br/api/v1/surveys/{uuid}/send" \
  -H "X-API-Key: sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "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}}?"
  }'

Os campos:

• channel — obrigatório, email ou whatsapp.
• recipient.name — obrigatório, até 255 caracteres.
• recipient.email — obrigatório quando o canal é email.
• recipient.phone — obrigatório quando o canal é whatsapp, em formato internacional com o + na frente, de 10 a 15 dígitos (ex.: +5511999999999). Fora desse formato, a API responde 422 com "O telefone deve estar no formato internacional (ex: +5511999999999)."
• context — opcional. Um objeto de pares chave/valor; cada valor é texto de até 500 caracteres.
• subject — opcional, até 255 caracteres. É o assunto do e-mail; no WhatsApp ele não é usado. Sem subject, o e-mail sai com o assunto padrão "Queremos ouvir sua opinião" seguido do título da pesquisa.

O envio é síncrono: a API só responde depois de tentar entregar. Em caso de sucesso, 201:

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

Guarde o attendee_uuid: é o identificador daquele respondente específico. Ele aparece no link da pesquisa e é o que amarra a resposta ao pedido do seu sistema.

Se a entrega falhar, a resposta é 422 com message: "Falha ao enviar a pesquisa." e um campo error com o motivo técnico. O registro do envio fica salvo com status falha e pode ser reenviado pelo painel.

3. Envio em lote

Para mandar vários convites de uma vez, use /send/bulk. Cada requisição aceita até 500 destinatários e um canal só.

curl -X POST "https://www.zavvi.com.br/api/v1/surveys/{uuid}/send/bulk" \
  -H "X-API-Key: sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "channel": "email",
    "subject": "{{NOME_CLIENTE}}, avalie seu pedido",
    "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" }
      }
    ]
  }'

Aqui o subject é um só para o lote inteiro (as tags são resolvidas por destinatário). Cada item de recipients tem name obrigatório, email ou phone conforme o canal, e um context próprio.

A resposta é imediata, 202, porque o processamento acontece em segundo plano:

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

O status: "queued" significa "aceito e na fila" — não significa entregue. O batch_id identifica o lote. Se você mandar mais de 500 destinatários, a API responde 422 com "O máximo é 500 destinatários por requisição."; quebre a lista em blocos.

4. Tags dinâmicas

Tags deixam a pesquisa personalizada para cada pessoa. Você escreve o marcador {{NOME_DA_TAG}} no texto e manda o valor correspondente no context do disparo.

Onde as tags são substituídas:

• Mensagem de boas-vindas da pesquisa;
• Assunto do e-mail (o campo subject do disparo);
• Texto das perguntas, nas pesquisas em modo conversacional.

Um exemplo. Na mensagem de boas-vindas você escreve:

{{NOME_CLIENTE}}, obrigado por comprar com a gente! Pedido {{NRO_PEDIDO}}.

E no disparo manda:

"context": {
  "NOME_CLIENTE": "Carlos Eduardo",
  "NRO_PEDIDO": "PED-2026-00142"
}

O cliente vê: "Carlos Eduardo, obrigado por comprar com a gente! Pedido PED-2026-00142."

Regras que valem a pena saber:

• O nome da tag aceita letras, números e underscore, sem espaços: {{NOME_CLIENTE}}, {{PEDIDO_2}}.
• As tags são sensíveis a maiúsculas e minúsculas: {{NOME}} e {{nome}} são tags diferentes.
• Se você não enviar context nenhum e a pesquisa for do tipo Pesquisa API, os marcadores são apagados do texto — o cliente não vê {{NOME_CLIENTE}} na tela.
• Mas se você enviar um context e esquecer uma tag, o marcador daquela tag continua aparecendo no texto. Mande sempre todas as tags que usou na pesquisa, nem que seja com valor vazio.

5. O que acontece depois do disparo

1. A Zavvi cria um respondente para aquele convite (é o attendee_uuid) e guarda o context junto dele.
2. O convite sai pelo canal escolhido.
3. O link que chega ao cliente é o link público da pesquisa com o respondente na URL: https://www.zavvi.com.br/s/{uuid-da-pesquisa}?a={attendee_uuid}. É esse ?a= que faz as tags serem substituídas e a resposta ser amarrada ao envio.
4. Quando o cliente abre o link, a Zavvi registra a visualização; quando ele responde, a resposta entra em Resultados como qualquer outra e é analisada pelo Radar de IA, se estiver ativo.

Sobre cada canal:

• E-mail — sai do endereço de pesquisas da Zavvi, com o remetente identificado como "Pesquisa de Satisfação" seguido do nome da sua empresa.
• WhatsApp — o convite é uma mensagem de texto com a saudação, os dados do context e o link. O WhatsApp do disparo por API usa a integração Twilio, configurada à parte pela nossa equipe; ele não usa o número da Central de Atendimento. Se essa integração não estiver configurada na conta, o envio é gravado com status falha e a mensagem explicando o que falta. Se você precisa disparar por WhatsApp, fale com o suporte antes de colocar a integração em produção.

6. Acompanhe no painel

Todo envio feito pela API fica registrado em API → Envios (/app/api/sends), com data, pesquisa, destinatário, canal, status e o Context que você mandou. Dá para filtrar por pesquisa, canal, status e período, e os envios com falha têm o botão Reenviar.

Na aba Dashboard (/app/api) ficam os números consolidados: Total de Envios, Sucesso, Falhas, Taxa de Conclusão (quantos dos convites viraram pesquisa respondida), o gráfico dos últimos 30 dias e a comparação API vs Manual.

7. QR Code por API

Se em vez de disparar você quiser imprimir a pesquisa, dá para pegar o QR Code direto da API (também exclusivo do plano Escala):

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"

Parâmetros de query, ambos opcionais:

• format — png (padrão) ou svg. Qualquer outro valor devolve 422 com "Formato inválido. Use png ou svg."
• size — em pixels, entre 100 e 1000; o padrão é 300. Valores fora da faixa são ajustados para o limite mais próximo.

A resposta é JSON:

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

No formato png, o campo qrcode já vem como data URI pronto para usar num img. No svg, vem o desenho do QR Code. Repare que esse QR Code aponta para o link geral da pesquisa, sem respondente identificado — é o certo para material impresso, mas não serve para amarrar a resposta a um pedido.

Dicas

• Dispare logo depois da experiência. A taxa de resposta cai muito de um dia para o outro.
• Use o attendee_uuid como ponte: guarde-o junto do pedido no seu banco e você saberá exatamente qual venda gerou qual nota.
• Trate o 422 no seu código. E-mail digitado errado e telefone fora do formato internacional são a causa da maior parte das falhas.
• Em lote, não mande a mesma pessoa duas vezes no mesmo dia — cada item gera um convite.

Os detalhes de cada parâmetro estão na referência completa em /docs/api. Para ler o que voltou, veja Lendo respostas pela API.