Vozea
EntrarCadastrar

Para desenvolvedores.

API e webhooks

Tudo o que entra na Vozea pode sair para o seu sistema: uma API REST com chave, e webhooks assinados a cada depoimento recebido, aprovado ou publicado. Make, n8n e Zapier funcionam sem código.

Começar em dois minutos

  1. Crie uma chave em Configurações › API (a chave aparece uma vez; guarde).
  2. Chame a API com o cabeçalho Authorization: Bearer vz_…
  3. Para receber eventos, cadastre a URL do seu sistema em Configurações › Webhooks e confira a assinatura.
curl https://vozea.io/api/v1/testimonials?limit=5 \
  -H 'Authorization: Bearer vz_SUA_CHAVE'

Autenticação

Toda requisição leva a chave da empresa no cabeçalho Authorization, como Bearer. Cada chave pertence a uma empresa; revogar em Configurações vale na hora. Até 5 chaves ativas por conta.

Erros e limites

Erro é sempre JSON com código e mensagem, e details por campo quando é validação. Limite de 120 requisições por minuto por chave: acima disso, 429 com Retry-After.

{
  "error": {
    "code": "validation_error",
    "message": "Invalid testimonial.",
    "details": {
      "text": "required, 10 to 2000 characters"
    }
  }
}

Endpoints

Base: https://vozea.io/api/v1

get/testimonials— List testimonials

Newest first. Paginate with `cursor`.

Parâmetros

Respostas

post/testimonials— Create a testimonial

A ready testimonial you already have (from your CRM, a form, a survey). It enters as origin `added`; emits `testimonial.received` (and `approved`/`published` when approve is true and the plan allows).

Corpo

{
  "author_name": "Maria Souza",
  "text": "Atendimento excelente, resolveram tudo no mesmo dia.",
  "rating": 5,
  "channel": "whatsapp",
  "tags": [
    "loja"
  ],
  "approve": true
}

Respostas

get/testimonials/{id}— Get a testimonial

Parâmetros

Respostas

post/requests— Request a testimonial from a customer

Same rules as a sale or the spreadsheet: channel by plan (e-mail goes out automatically on paid plans; WhatsApp appears in the day's list), monthly quota, one open request per contact.

Corpo

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

Respostas

get/requests/{id}— Get a request

The state of a request: use it to confirm an integration works without opening Vozea (right after the 201, `state` is `scheduled`).

Parâmetros

Respostas

delete/requests/{id}— Cancel a pending request

Cancels a request that has not been answered yet (scheduled or sent): the customer is not asked and gets no reminders. Call it on refund, chargeback or order cancellation — never ask for a testimonial from someone who got their money back. `id` is the one returned by POST /requests; keep it with the sale.

Parâmetros

Respostas

get/pages— List public pages

Respostas

get/widgets— List widgets

Respostas

Eventos

Três eventos, com o mesmo objeto de depoimento da API. O payload tem version desde o primeiro dia: mudar um campo é subir a versão, nunca renomear em silêncio. Importações em lote (sync do Google, planilha) só chegam ao seu webhook se o destino marcar “incluir importados”.

Exemplo de payload

{
  "id": "evt_5f9k2m4x9p7q",
  "type": "testimonial.received",
  "version": 1,
  "created_at": "2026-09-16T18:00:00.000Z",
  "company": {
    "id": "c_a1b2c3d4e5",
    "name": "Átria",
    "slug": "atria",
    "country": "BR",
    "language": "pt-BR"
  },
  "testimonial": {
    "id": "t_8k2m4x9p7q",
    "author": {
      "name": "Maria Souza",
      "meta": "cliente desde 2024",
      "photo_url": null
    },
    "text": "Atendimento excelente, resolveram tudo no mesmo dia.",
    "rating": 5,
    "kind": "text",
    "status": "approved",
    "origin": {
      "kind": "collected",
      "platform": null
    },
    "channel": "vozea",
    "tags": [
      "loja"
    ],
    "captured": {
      "url": null,
      "title": null,
      "at": null
    },
    "authored_at": null,
    "created_at": "2026-09-16T18:00:00.000Z",
    "approved_at": "2026-09-16T18:00:05.000Z",
    "urls": {
      "app": "https://vozea.io/app/tratar?q=t_8k2m4x9p7q",
      "public_page": "https://vozea.io/atria",
      "source": null
    }
  }
}

Webhooks e assinatura

Cada entrega é um POST com o evento em JSON e quatro cabeçalhos. Confira a assinatura com o segredo do destino (HMAC-SHA256 sobre timestamp.corpo) e recuse timestamps fora de 5 minutos — é o que barra replay. Responda 2xx em até 10 segundos; senão a Vozea tenta de novo em 1 min, 5 min, 30 min, 2 h e 12 h, e desliga o destino depois de dez falhas seguidas (você é avisado). Uma importação grande não vira rajada: no máximo 60 entregas por minuto por destino.

Cabeçalhos

Verificar em Node.js

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyVozea({ secret, header, timestamp, body }) {
  const m = /^v1=([a-f0-9]{64})$/.exec(header ?? "");
  if (!m) return false;
  const ts = Number(timestamp);
  if (!Number.isInteger(ts) || Math.abs(Date.now() / 1000 - ts) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${ts}.${body}`).digest("hex");
  const a = Buffer.from(expected, "hex"), b = Buffer.from(m[1], "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

// Express: use o corpo cru (express.raw), nunca o JSON já parseado.
app.post("/vozea", express.raw({ type: "application/json" }), (req, res) => {
  const ok = verifyVozea({ secret: process.env.VOZEA_WEBHOOK_SECRET, header: req.get("x-vozea-signature"), timestamp: req.get("x-vozea-timestamp"), body: req.body.toString() });
  if (!ok) return res.status(401).end();
  const event = JSON.parse(req.body);
  res.status(200).end();
});

Make, n8n e Zapier

n8n

  1. No n8n, um nó Webhook (POST) recebe os eventos: cole a URL dele em Configurações › Webhooks.
  2. Para ler ou criar, um nó HTTP Request com Header Auth: Authorization = Bearer vz_…
  3. Importe o openapi.json no nó HTTP Request para ter os endpoints prontos.

Make

  1. No Make, um módulo Webhooks › Custom webhook recebe os eventos.
  2. Para a API, HTTP › Make a request com o cabeçalho Authorization.
  3. O corpo dos eventos já vem em JSON: mapeie os campos direto.

Zapier

O app da Vozea no diretório do Zapier vem depois; até lá, Webhooks by Zapier funciona com a mesma URL e a mesma API.

OpenAPI

O spec completo, em OpenAPI 3.1, para importar em qualquer ferramenta: /api/v1/openapi.json