Início rápido

Este guia usa uma chave de teste (wg_test_...). Chaves de teste funcionam contra uma cópia sandbox do seu workspace: nenhuma mensagem de WhatsApp é enviada e nenhum pagamento real é feito.

1. Gere uma chave de teste

No painel, vá em Desenvolvedores → Chaves de API → Nova chave, escolha Teste e marque os escopos slots:read, bookings:write e config:read. A chave aparece uma única vez.

export WAGEND_KEY="wg_test_xxxxxxxx_xxxxxxxxxxxxxxxxxxxx"

2. Veja quem você é

curl https://api.wagend.app/v1/me -H "Authorization: Bearer $WAGEND_KEY"

{
  "workspace": { "id": "ws_9f2c", "name": "Barbearia Centro", "timezone": "America/Sao_Paulo", "locale": "pt", "currency": "BRL" },
  "scopes": ["slots:read", "bookings:write", "config:read"],
  "mode": "test"
}

O workspace sempre vem da chave. Você nunca envia um id de workspace.

3. Liste os serviços

curl https://api.wagend.app/v1/services -H "Authorization: Bearer $WAGEND_KEY"

{
  "data": [
    { "id": "svc_corte", "name": "Corte", "duration_min": 30, "price_cents": 5000, "currency": "BRL",
      "requirements": [{ "resource_group_id": "grp_barbers", "units": 1 }] }
  ]
}

4. Busque horários disponíveis

curl "https://api.wagend.app/v1/slots?service_id=svc_corte&from=2026-10-15T08:00:00-03:00&to=2026-10-15T13:00:00-03:00" \
  -H "Authorization: Bearer $WAGEND_KEY"

{
  "data": [
    { "start": "2026-10-15T09:00:00-03:00", "end": "2026-10-15T09:30:00-03:00", "resource_ids": ["res_juan"] },
    { "start": "2026-10-15T09:45:00-03:00", "end": "2026-10-15T10:15:00-03:00", "resource_ids": ["res_juan"] }
  ],
  "unavailable_reason": null
}

5. Faça a pré-reserva

A pré-reserva (hold) segura o horário por 10 minutos enquanto você coleta os dados do cliente. Sempre envie um Idempotency-Key para que reenvios sejam seguros.

curl -X POST https://api.wagend.app/v1/holds \
  -H "Authorization: Bearer $WAGEND_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "service_id": "svc_corte", "start": "2026-10-15T09:45:00-03:00", "resource_ids": ["res_juan"] }'

{ "id": "bkg_7Qx1", "status": "held", "expires_at": "2026-10-14T15:30:00-03:00", "start": "2026-10-15T09:45:00-03:00" }

6. Confirme

curl -X POST https://api.wagend.app/v1/holds/bkg_7Qx1/confirm \
  -H "Authorization: Bearer $WAGEND_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "customer": { "name": "Carlos", "phone": "+5521999990000", "locale": "pt" } }'

{ "id": "bkg_7Qx1", "status": "confirmed", "start": "2026-10-15T09:45:00-03:00", "source": "api" }

Se o serviço exige sinal via Pix, o status fica pending_payment e a resposta traz o código Pix. Vira confirmed quando o pagamento chega.

O mesmo fluxo em JavaScript

const api = (path: string, init: RequestInit = {}) =>
  fetch(`https://api.wagend.app/v1${path}`, {
    ...init,
    headers: { Authorization: `Bearer ${process.env.WAGEND_KEY}`, 'Content-Type': 'application/json', ...init.headers },
  }).then((r) => r.json())

const { data: slots } = await api(`/slots?service_id=svc_corte&from=${from}&to=${to}`)
const hold = await api('/holds', {
  method: 'POST',
  headers: { 'Idempotency-Key': crypto.randomUUID() },
  body: JSON.stringify({ service_id: 'svc_corte', start: slots[0].start }),
})
const booking = await api(`/holds/${hold.id}/confirm`, {
  method: 'POST',
  headers: { 'Idempotency-Key': crypto.randomUUID() },
  body: JSON.stringify({ customer: { name: 'Carlos', phone: '+5521999990000' } }),
})

Próximos passos

• Reaja a agendamentos com webhooks.
• Veja todos os endpoints na referência.