API e webhooks do Marcai.

Começar

export MARCAI_API_KEY="mk_live_…"

curl "https://api-production-ca96.up.railway.app/api/v1/services" \
  -H "x-api-key: $MARCAI_API_KEY"

Permissões das chaves

Limites, paginação e erros

{ "error": { "code": "forbidden", "message": "A chave não tem permissão para criar marcações." } }

Referência da API

curl "https://api-production-ca96.up.railway.app/api/v1/me" \
  -H "x-api-key: $MARCAI_API_KEY"

curl "https://api-production-ca96.up.railway.app/api/v1/services" \
  -H "x-api-key: $MARCAI_API_KEY"

curl "https://api-production-ca96.up.railway.app/api/v1/staff" \
  -H "x-api-key: $MARCAI_API_KEY"

curl "https://api-production-ca96.up.railway.app/api/v1/availability?service_id=<service_id>&from=<from>" \
  -H "x-api-key: $MARCAI_API_KEY"

curl "https://api-production-ca96.up.railway.app/api/v1/bookings" \
  -H "x-api-key: $MARCAI_API_KEY"

curl -X POST "https://api-production-ca96.up.railway.app/api/v1/bookings" \
  -H "x-api-key: $MARCAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <uuid>" \
  -d '{ ... }'

curl "https://api-production-ca96.up.railway.app/api/v1/bookings/<id>" \
  -H "x-api-key: $MARCAI_API_KEY"

curl -X PATCH "https://api-production-ca96.up.railway.app/api/v1/bookings/<id>" \
  -H "x-api-key: $MARCAI_API_KEY"

curl "https://api-production-ca96.up.railway.app/api/v1/clients" \
  -H "x-api-key: $MARCAI_API_KEY"

Webhooks

O pedido

{
  "id": "evt_01hx…",
  "type": "booking.created",
  "created_at": "2026-10-11T10:00:00.000Z",
  "data": {
    "id": "…",
    "status": "confirmed",
    "previous_status": null,
    "start_at": "2026-10-12T09:00:00.000Z",
    "end_at": "2026-10-12T09:30:00.000Z",
    "price": 1500,
    "service_id": "…",
    "staff_id": "…",
    "client_id": "…",
    "source": "PUBLIC_SITE",
    "rescheduled_from_id": null,
    "change": "created"
  }
}

Verificar a assinatura

import { createHmac, timingSafeEqual } from 'node:crypto';
import express from 'express';

const SECRET = process.env.MARCAI_WEBHOOK_SECRET; // whsec_…, mostrado uma só vez no painel

function verify(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  const received = parts.v1 ?? '';
  return (
    expected.length === received.length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(received))
  );
}

const app = express();

// Usa o corpo em bruto: se o converteres para JSON antes, a assinatura deixa de bater.
app.post('/marcai', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8');
  if (!verify(rawBody, req.header('Marcai-Signature') ?? '', SECRET)) {
    return res.sendStatus(400);
  }
  const event = JSON.parse(rawBody);
  // Ignora o que já processaste (event.id) e responde logo; trata o resto depois.
  res.sendStatus(200);
});

app.listen(3000);

Depois de gerares um segredo novo, o anterior deixa de assinar: troca-o no teu servidor logo a seguir.

Entrega e novas tentativas

• Entrega com sucesso = resposta 2xx em menos de 5 segundos. Responde depressa e processa depois.
• Se falhar, o Marcai volta a tentar até 10 vezes em cerca de 24 horas (30 s, 2 min, 10 min, 30 min, 1 h, 2 h, 4 h, 6 h e 10 h).
• O mesmo evento pode chegar mais do que uma vez (tentativas, reenvio manual): ignora os ids que já viste.
• A ordem não é garantida entre eventos diferentes: usa created_at.
• Se 5 entregas seguidas esgotarem as tentativas, o endereço é desativado e o dono do negócio recebe um email. Reativa-o no painel e reenvia o que falhou.
• O endereço tem de ser https:// e público. Redirecionamentos não são seguidos.
• Os avisos só levam ids, estados e valores — nunca nomes nem contactos. Para o resto, lê a API com o id recebido.