API e webhooks

Autenticação

Envie a chave de API no cabeçalho Authorization de cada requisição. A organização é a da chave, e a chave age em nome do membro que a criou enquanto ele fizer parte da organização. Chaves expiradas ou revogadas são recusadas.

Authorization: Bearer vumi_live_…

Todas as rotas ficam em /api/business/v1.

Permissões

Cada operação exige uma permissão da chave; sem ela, a resposta é 403 com o código API_KEY_SCOPE_MISSING.

Paginação

As listas aceitam limit (quantos itens por página) e cursor (onde continuar) e respondem com os itens em data, o cursor da próxima página em nextCursor (null na última) e o total filtrado em total.

curl "https://vumi.com.br/api/business/v1/contacts?limit=50&cursor=eyJ…" \
  -H "Authorization: Bearer vumi_live_…"

{
  "data": [{ "id": "…", "name": "…" }],
  "nextCursor": "eyJ…",
  "total": 132
}

Repetição segura

Toda escrita aceita o cabeçalho Idempotency-Key. Repetir a mesma requisição com a mesma chave em até um dia devolve a primeira resposta, sem repetir a operação; a mesma chave com outra requisição é recusada.

curl -X POST "https://vumi.com.br/api/business/v1/orders" \
  -H "Authorization: Bearer vumi_live_…" \
  -H "Idempotency-Key: 9f1c2d3e-order-4521" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Limite de requisições

Cada chave tem um limite de requisições por minuto, que depende do plano. Acima dele, a resposta é 429 com o cabeçalho Retry-After, em segundos.

Erros

Os erros respondem com um código estável, nunca com um texto para exibir; message é só uma descrição técnica e metadata traz os valores de cada código. Os principais:

{ "code": "API_KEY_SCOPE_MISSING", "message": "…", "metadata": { "scope": "orders:write" } }

Webhooks

Cada evento é enviado por POST, em JSON, a todos os webhooks ativos que o assinam. O corpo é sempre o mesmo envelope, com os dados do evento em data:

{
  "id": "5b0d6c1e-…",
  "type": "order.created",
  "createdAt": "2026-10-01T12:00:00.000Z",
  "organizationID": "…",
  "data": { … }
}

Cada entrega traz três cabeçalhos:

• X-Webhook-ID: o ID do evento, igual em todas as tentativas e reenvios, para descartar repetições;
• X-Webhook-Timestamp: o horário da tentativa em segundos Unix, para recusar entregas antigas;
• X-Signature-256: sha256= seguido do HMAC-SHA256 em hexadecimal, com o segredo do webhook, de ${timestamp}.${body} sobre os bytes exatos recebidos.

Verifique a assinatura antes de usar o evento: calcule-a com o segredo do webhook (whsec_…) sobre os bytes exatos do corpo, antes de interpretar o JSON, compare em tempo constante e recuse horários com mais de cinco minutos de diferença. Em Node.js:

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

function verifyWebhook(headers, rawBody, secret) {
    const timestamp = headers["x-webhook-timestamp"];
    const signature = headers["x-signature-256"] ?? "";
    if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
        return false;
    }
    const expected = "sha256=" + createHmac("sha256", secret)
        .update(`${timestamp}.${rawBody}`)
        .digest("hex");
    const received = Buffer.from(signature);
    return received.length === expected.length && timingSafeEqual(received, Buffer.from(expected));
}

Responda com qualquer status 2xx. Outras respostas e falhas de conexão são repetidas com intervalos crescentes por 24 horas; um webhook que falha todas as entregas por um dia é desativado, e os proprietários e administradores são avisados.

Eventos

Referência

Todas as operações, com a permissão que cada uma exige. O documento OpenAPI completo, com os campos de cada requisição e resposta, pode ser importado em ferramentas como Postman ou Insomnia.