Liga o teu sistema, ou um assistente de IA, à agenda do salão

Permissões de uma chave

• catalog:readver lojas, serviços e equipa
• availability:readver horas livres
• bookings:readler marcações
• bookings:writemarcar e cancelar
• customers:readler clientes
• customers:writecriar clientes

Erros

Sempre no mesmo formato. O que conta é o code, que não muda; a mensagem é para pessoas.

{
  "error": {
    "code": "slot_taken",
    "message": "That time has just been taken.",
    "details": {}
  }
}

Códigos de erro

• invalid_request400Pedido inválido; details.field diz qual o campo.
• unauthenticated401Chave em falta, errada, revogada ou expirada.
• account_closed403A conta do salão está fechada.
• not_in_plan403O plano do salão não inclui a API.
• forbidden_scope403A chave não tem a permissão necessária.
• forbidden_shop403A chave está limitada a outra loja.
• not_found404Não existe, ou não é deste salão.
• method_not_allowed405Método não permitido neste endereço.
• conflict409O estado atual não permite a operação.
• idempotency_conflict409A mesma Idempotency-Key foi usada com outro pedido.
• idempotency_in_progress409Um pedido igual ainda está a ser tratado.
• slot_unavailable409A hora não está disponível.
• slot_taken409A hora acabou de ser ocupada.
• customer_exists409Já existe um cliente com esse telemóvel (details.customer_id).
• customer_blocked409O salão não aceita marcações deste cliente.
• booking_limit409O cliente atingiu o limite de marcações.
• booking_closed409O salão não aceita marcações online agora.
• coupon_refused422O cupão não pode ser usado.
• out_of_area422Fora da zona de visitas ao domicílio.
• rate_limited429Limite de pedidos por minuto atingido; vê Retry-After.
• internal500Erro do nosso lado; tenta de novo.
• unavailable503Serviço temporariamente indisponível; tenta de novo.

Avisos disponíveis

• booking.createdMarcação criada: Uma marcação nova, por qualquer canal (também as que esperam sinal ou aprovação).
• booking.confirmedMarcação confirmada: Uma marcação que esperava sinal ou aprovação passou a confirmada.
• booking.rescheduledMarcação mudada de hora: A hora (ou o profissional) de uma marcação mudou.
• booking.cancelledMarcação cancelada: Uma marcação foi cancelada pelo cliente, pela equipa ou por falta de sinal.
• booking.completedMarcação concluída: A equipa marcou a marcação como feita.
• booking.no_showCliente faltou: A equipa marcou que o cliente faltou.
• customer.createdCliente novo: Um cliente novo na ficha do salão (por marcação, conversa, importação ou à mão).

O que recebes

O corpo é um JSON com o aviso e, em data, o mesmo JSON que a API envia nas respostas (a marcação ou o cliente, lidos no momento do envio).

POST /your/endpoint HTTP/1.1
Content-Type: application/json
X-Webhook-Event: booking.created
X-Webhook-Id: 7f0c1d52-…
X-Webhook-Signature: t=1792000000,v1=5257a869…

{
  "id": "7f0c1d52-…",
  "type": "booking.created",
  "created_at": "2026-11-02T09:00:00.000Z",
  "account_id": "…",
  "data": { "id": "…", "status": "confirmed", "starts_at": "…", "customer": { … } }
}

Cabeçalhos: X-Webhook-Event (o tipo), X-Webhook-Id (igual em todas as tentativas: usa-o para ignorar repetições) e X-Webhook-Signature.

Verificar a assinatura

O segredo (começa por whsec_) aparece uma vez, quando crias o endereço. A assinatura é o HMAC-SHA256 de «t.corpo», com t em segundos. Calcula-a sobre o corpo tal como chegou e recusa avisos antigos.

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

// rawBody: the body exactly as received (a string), not parsed and re-written
export function verify(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (!(age <= toleranceSeconds)) return false;
  const expected = createHmac("sha256", secret).update(parts.t + "." + rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 ?? "");
  return a.length === b.length && timingSafeEqual(a, b);
}

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str, tolerance_seconds: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > tolerance_seconds:
        return False
    signed = parts["t"].encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Entrega e repetições

Responde com 2xx em menos de 10 segundos. Qualquer outra resposta, ou demora, repete o aviso: espera 30 segundos, a dobrar até 3600, no máximo 8 tentativas. Depois de 10 falhas seguidas o endereço desliga-se sozinho e o painel diz porquê.

Não há garantia de ordem: usa o updated_at da marcação para saber qual é a mais recente.

Só chamamos endereços https públicos: endereços privados são recusados e não seguimos redirecionamentos.

Em «Enviar teste», o painel manda um aviso ping para veres a ligação a funcionar.

Ferramentas

• list_shopscatalog:readThe shops (places) of the salon this key can use, with their ids and time zones.
• list_servicescatalog:readThe services that can be booked online in a shop (id, name, duration, price in cents, variants, add-ons) and the people who do them. Call this first to get the ids.
• check_availabilityavailability:readFree start times for one or more services between two dates (YYYY-MM-DD, in the shop's time zone). Returns slots with starts_at (UTC) and the person for each service. Always check before booking.
• create_bookingbookings:writeMake a booking at a start time taken from check_availability. Give customer_id (an existing customer) or customer (name and/or phone; an existing customer with that phone is reused). If the salon asks for a deposit, the booking waits for it and the answer has deposit.pay_url to give the customer. Use the same idempotency_key when retrying.
• list_bookingsbookings:readBookings, oldest start first. Filter by dates (ISO 8601 with offset), status or customer.
• get_bookingbookings:readOne booking by id.
• cancel_bookingbookings:writeCancel a booking that is still open.
• find_customerscustomers:readCustomers of the salon by exact phone, exact email or part of the name.
• create_customercustomers:writeCreate a customer (a name and/or a phone number is required). Fails with customer_exists if the phone number is already a customer.

A chave só vê as ferramentas das suas permissões. Um erro dentro de uma ferramenta volta como resultado, para o assistente se corrigir.