API de pesquisas — primeiros passos

A API da Zavvi permite que o seu sistema converse com as pesquisas de satisfação: criar pesquisas, montar perguntas, disparar convites, ler respostas e consultar métricas — tudo por requisições HTTP, sem ninguém precisar entrar no painel.

O caso mais comum é este: seu ERP fecha um pedido, chama a API e o cliente recebe a pesquisa alguns minutos depois, já personalizada com o número do pedido.

Quem tem acesso

A tela que gera as chaves fica em API → API Keys e é liberada para o plano Escala. Em qualquer outro plano, a área API do painel mostra a tela "Integre via API" com o convite para upgrade, e não há como criar uma chave.

Dentro da API, os endpoints se dividem em dois grupos:

• Com chave de API — pesquisas, perguntas, respostas e analytics.
• Exclusivos do plano Escala — disparo de pesquisas (individual e em lote) e QR Code. Se a conta não estiver no Escala, esses endpoints devolvem 403 com a mensagem Este recurso é exclusivo do plano Escala. Faça upgrade para acessar. e o campo plan_required: "enterprise".

1. Gere sua chave

1. No painel, abra API (menu lateral) e vá até a aba API Keys, em /app/api/keys.
2. Clique em Criar Nova Chave.
3. Preencha o Nome — obrigatório. Use algo que identifique o sistema que vai usar a chave, como "Integração CRM".
4. Expiração é opcional. Se você preencher, precisa ser uma data futura; depois dela a chave para de funcionar sozinha. Deixe em branco para uma chave sem prazo.
5. Clique em Criar.

A chave aparece uma única vez, no aviso "Chave criada! Copie agora, ela não será exibida novamente.", com um botão Copiar. Guarde-a em um cofre de segredos ou nas variáveis de ambiente do seu sistema. Na tabela, a chave só aparece mascarada nos primeiros caracteres.

São 48 caracteres hexadecimais. Cada chave pertence a um usuário, e tudo o que a API faz acontece em nome desse usuário — as pesquisas que ele enxerga, os limites do plano dele.

Gerenciando as chaves

Na tabela de API Keys você vê o nome, a chave mascarada, o Último Uso e o status:

• Desativar deixa a chave inválida sem apagá-la; Ativar devolve o acesso.
• Excluir remove a chave de vez (a ação pede confirmação e não pode ser desfeita).

Você pode ter várias chaves ativas ao mesmo tempo. Vale a pena criar uma por integração: se precisar revogar uma, as outras continuam funcionando.

2. Autentique

Toda requisição autenticada vai com a chave no header X-API-Key. Não existe chave por query string, nem token OAuth, nem usuário e senha.

Erros de autenticação que você pode receber:

• 401 API key required. Use header X-API-Key. — você não mandou o header.
• 401 Invalid or expired API key. — a chave não existe, foi desativada ou passou da data de expiração.
• 403 Account email not verified. — o e-mail da conta dona da chave ainda não foi confirmado.

3. URL base

https://www.zavvi.com.br/api/v1

Todos os caminhos deste artigo e dos próximos são relativos a essa base. As pesquisas são identificadas pelo UUID — o mesmo código que aparece no link público https://www.zavvi.com.br/s/{uuid}, e não pelo número sequencial que você vê em algumas telas.

4. Seu primeiro request

Liste as pesquisas da conta:

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

A resposta vem paginada, com uma lista em data:

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "Satisfação no Atendimento",
      "status": "published",
      "url": "https://www.zavvi.com.br/s/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "questions_count": 4,
      "responses_count": 342,
      "created_at": "2026-08-01T10:30:00.000000Z"
    }
  ]
}

O campo id é o UUID que você vai usar em todos os outros endpoints. status é published quando a pesquisa está ativa e draft quando está inativa — pesquisa inativa não abre para o respondente, então ative antes de começar a disparar.

Por padrão vêm 15 pesquisas por página; use per_page para pedir mais (o teto é 100):

curl -X GET "https://www.zavvi.com.br/api/v1/surveys?per_page=50" \
  -H "X-API-Key: sua_chave_aqui" \
  -H "Accept: application/json"

Limites de uso

• 60 requisições por minuto nos endpoints autenticados. Ao estourar, a API responde 429.
• Os limites do plano continuam valendo: criar pesquisa pela API respeita a mesma cota de pesquisas do painel, e criar pergunta respeita a cota de perguntas por pesquisa. Quando a cota acaba, a resposta é 403.

Códigos de status

Código	Quando acontece
200	Sucesso
201	Recurso criado (ex.: disparo individual)
202	Aceito e enfileirado (envio em lote)
204	Removido com sucesso, sem corpo de resposta
401	Chave ausente, inválida, inativa ou expirada
403	Sem permissão, cota do plano estourada ou recurso exclusivo do Escala
404	Pesquisa ou pergunta não encontrada
422	Falha de validação nos dados enviados
429	Limite de requisições por minuto excedido

Boas práticas

• Nunca coloque a chave no front-end. Ela dá acesso total à conta; chame a API a partir do seu servidor.
• Uma chave por integração, com nome descritivo. Fica muito mais fácil revogar depois.
• Se desconfiar de vazamento, desative a chave no painel e crie outra — a troca leva menos de um minuto.
• Confira o Último Uso de vez em quando: chave sem uso há meses é chave para excluir.

Próximos passos

• Disparando pesquisas pela API — o fluxo mais usado, com tags dinâmicas.
• Lendo respostas pela API — respostas, analytics e como cruzar com o painel.

A referência técnica completa, com todos os endpoints, parâmetros e formatos de resposta, está em /docs/api.