Central de ajuda · Ligar vendas

Como ligar o seu sistema à Vozea

Para ERP, PDV ou sistema próprio. A Vozea é a ferramenta que a empresa usa para pedir, organizar e publicar depoimentos de clientes. Esta integração faz um trabalho só: quando uma venda for concluída no sistema da empresa, chamar a Vozea para ela pedir o depoimento ao cliente — a Vozea decide quando pedir, por qual canal, e cuida dos lembretes. Este guia é para quem cuida do sistema e nunca ouviu falar da Vozea.

Leva uns 30 minutos · conferido na documentação oficial em 19/9/2026

O que você precisa

Uma chave de acesso da conta da empresa na Vozea. Quem administra a conta cria em Configurações › API (dê o nome do seu sistema) e manda por um canal seguro — ela nunca vai numa mensagem junto com este link.
Um ponto no seu sistema que sabe quando a venda foi concluída (pagamento confirmado): um webhook nativo, um gatilho no banco, um job agendado ou uma automação.
Os dados do cliente na venda: nome e pelo menos um contato — telefone com DDD (WhatsApp) ou e-mail; de preferência também o produto e a data da compra.

Passo a passo

Decida quando disparar
Só a partir de agora e só quando a venda estiver concluída (pagamento confirmado). Nunca mande o histórico: venda com mais de 30 dias é recusada (422 too_old) — clientes antigos a empresa pede pela Vozea, em Enviar para uma lista. Não dispare em pedido criado, boleto ou Pix gerado, carrinho ou pedido cancelado. Uma chamada por venda: guarde no seu sistema que a venda X já foi enviada, e não reenvie em retry a não ser em erro de rede ou resposta 5xx.
Atenção: Chamar cedo demais (antes do pagamento) faz a Vozea pedir depoimento a quem não comprou.
Monte a chamada
POST https://vozea.io/api/v1/requests, com o cabeçalho Authorization: Bearer vz_SUA_CHAVE e Content-Type: application/json. O corpo é um JSON com os campos da seção "A chamada", abaixo — name é obrigatório; mande email ou phone, ou os dois. Não invente campos além dos listados.
Trate a resposta
201 = Queued. A resposta traz id, channel, sends_at — guarde o id junto da venda: é com ele que se cancela o pedido se a venda for desfeita. 422 = a Vozea entendeu e recusou; details.reason diz por quê (no_channel, duplicate, over_quota, too_old) — não repita a chamada. 401 = chave errada ou revogada. 429 = mais de 120 chamadas por minuto nessa chave; espere o Retry-After.
Teste com uma venda de mentira
Rode o curl da seção "A chamada" com um nome de teste e o seu próprio telefone ou e-mail. Depois ligue o disparo real e acompanhe a primeira venda de verdade.

A chamada

Gerado do openapi.json: se a API mudar, esta seção muda junto.

POST https://vozea.io/api/v1/requests

Autenticação

Authorization: Bearer vz_SUA_CHAVE
Content-Type: application/json

Campos do corpo

nameobrigatório: string [2–80]
email: string (email)
phone: string — Brazilian number with area code; WhatsApp.
product: string [0–120]
purchased_at: string (date)
channel: string (auto | email | whatsapp) — auto = e-mail when the plan sends e-mail automatically, else WhatsApp.

Exemplo de corpo

{
  "name": "Maria Souza",
  "phone": "11999990000",
  "product": "Bolo de festa",
  "purchased_at": "2026-09-15"
}

Exemplo com curl

curl -X POST https://vozea.io/api/v1/requests \
  -H "Authorization: Bearer vz_SUA_CHAVE" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Maria Souza",
  "phone": "11999990000",
  "product": "Bolo de festa",
  "purchased_at": "2026-09-15"
}'

Resposta

201 — Queued. Campos: id (string), channel (string (email | whatsapp)), sends_at (string (date-time)).

Cancelar um pedido (venda desfeita)

DELETE https://vozea.io/api/v1/requests/{id}

curl -X DELETE https://vozea.io/api/v1/requests/iv_ID_DO_PEDIDO \
  -H "Authorization: Bearer vz_SUA_CHAVE"

200 — cancelado; chamar de novo é seguro — devolve 200 de novo, com already_canceled = true. 409 — o cliente já respondeu (details.reason = answered): o depoimento fica, não há o que cancelar. 404 — esse id não é desta conta.

Regras que importam

Uma venda, um pedido: A Vozea não abre dois pedidos para o mesmo contato enquanto o primeiro está aberto (422, details.reason = duplicate). Mesmo assim, a idempotência é sua: marque a venda como enviada e não reenvie em retry, a não ser em erro de rede ou 5xx.
Reembolso ou cancelamento: Se a venda for desfeita (reembolso, chargeback, cancelamento), chame DELETE https://vozea.io/api/v1/requests/{id} com a mesma chave: o pedido pendente é cancelado e o cliente não recebe nada — nunca peça depoimento a quem devolveu. O id é o da resposta 201. Quem já respondeu não muda (409, details.reason = answered): registre e siga. Cancelar duas vezes não é erro — chamar de novo é seguro — devolve 200 com already_canceled = true.
Cota do plano: Cada plano tem uma cota de pedidos por mês. Estourou, a Vozea responde 422 com details.reason = over_quota até o mês virar (ou até a conta mudar de plano). Trate como recusa, não como erro para retry.
Sem contato utilizável: Sem e-mail nem telefone válido a Vozea responde 422 com details.reason = no_channel. Mande o telefone com DDD; o e-mail só dispara sozinho nos planos pagos.

Como testar

Rode o curl da seção "A chamada" com um nome de teste e o seu próprio telefone ou e-mail. A resposta deve ser 201, com o id do pedido.
Confira sem abrir a Vozea: GET /v1/requests/{id} com a mesma chave devolve o pedido com state = scheduled (depois: sent, answered ou canceled). Na Vozea, ele aparece em Coletar › Pedidos › Na fila.
Repita a mesma chamada: a resposta deve ser 422 com details.reason = duplicate — é a proteção contra pedidos repetidos funcionando.
Cancele o pedido de teste com DELETE /v1/requests/{id} (200), para ninguém receber um pedido de mentira.

Depois de ligar

Cada chamada aceita vira um pedido que sai 7 dias depois da compra — quem administra a conta ajusta o prazo em Coletar › Pedidos.
Por e-mail o pedido sai sozinho a partir do plano Essencial. Por WhatsApp a Vozea monta a mensagem e o pedido entra na lista do dia, para a empresa mandar com um toque.
Quem responde não recebe mais nada; quem não responde recebe até dois lembretes.
Alternativa sem chave: o webhook de entrada de vendas. Em Coletar › Vendas › Uso outro sistema › Criar a conexão nasce uma URL única da conta que aceita o JSON da venda em português ou inglês (nome, email, telefone, produto, valor, data, id). É o caminho das ferramentas de automação.

Problemas comuns

401: A chave está errada, vazia ou foi revogada. Confira o cabeçalho Authorization: Bearer vz_… (sem aspas, sem espaço a mais) e peça uma chave nova a quem administra a conta, em Configurações › API.
422 com details.reason = no_channel: A venda veio sem contato utilizável. Mande phone (com DDD) ou email — ou os dois.
422 com details.reason = duplicate: Esse cliente já tem um pedido aberto. Não é erro: registre e siga.
422 com details.reason = too_old: A compra tem mais de 30 dias. A integração só pede depoimento de venda recente — nunca mande o histórico. Clientes antigos, a empresa pede pela Vozea em Coletar › Formulários › Enviar para uma lista.
422 com details (campo a campo): Um campo veio fora do formato: name com 2 a 80 caracteres, purchased_at como AAAA-MM-DD, channel como auto, email ou whatsapp. A resposta diz qual.
409 ao cancelar: O cliente já respondeu (details.reason = answered): o depoimento fica e não há o que cancelar. Não é erro: registre e siga. Cancelar um pedido já cancelado não dá 409 — devolve 200 com already_canceled = true.
429: Mais de 120 chamadas por minuto na mesma chave. Espere os segundos do cabeçalho Retry-After e continue.
201, mas o pedido não apareceu na Vozea: Confira se a chave é da conta certa (o prefixo dela aparece em Configurações › API) e olhe Coletar › Pedidos › Na fila — o pedido fica lá até a data de envio.

Fontes

Os nomes de menus, botões e campos deste manual foram conferidos em:

Ficou com dúvida? Escreva para contato@vozea.io.