Receitas

Receitas de API

Todas usam $WAGEND_KEY como no início rápido.

Criar um cliente e agendar de uma vez

Precisa de customers:write e bookings:write. O telefone é o identificador único do cliente: se já existir, a API responde 409 customer_exists.

curl -X POST https://api.wagend.app/v1/customers \
  -H "Authorization: Bearer $WAGEND_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Marina", "phone": "+5521988887777", "locale": "pt", "tags": ["vip"],
        "address": { "street": "Rua das Flores", "number": "120", "city": "Rio de Janeiro", "formatted": "Rua das Flores 120, Rio de Janeiro" } }'

curl -X POST https://api.wagend.app/v1/bookings \
  -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",
        "customer": { "name": "Marina", "phone": "+5521988887777" } }'

POST /bookings faz a pré-reserva e a confirmação em uma única chamada.

Ler o que é para hoje

Precisa de bookings:read. GET /work-items é a mesma consulta usada pela tela Hoje.

curl "https://api.wagend.app/v1/work-items?view=today&limit=50" \
  -H "Authorization: Bearer $WAGEND_KEY"

# Só o que ninguém pegou ainda
curl "https://api.wagend.app/v1/work-items?unassigned=true&limit=50" \
  -H "Authorization: Bearer $WAGEND_KEY"

Cada tarefa traz seu stage e suas available_actions.

Atribuir e fechar uma entrega com ações

Precisa de bookings:write. As ações têm o nome dado pela configuração de etapas do negócio (com o modelo de entregas: atribuir, soltar, iniciar, concluir, nao_estava). Consulte-as em GET /stage-config ou em available_actions da tarefa.

# Atribuir a entrega a um entregador (resource_id é o recurso do entregador)
curl -X POST https://api.wagend.app/v1/bookings/$TASK_ID/actions/atribuir \
  -H "Authorization: Bearer $WAGEND_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "data": {}, "resource_id": "'$COURIER_ID'" }'

# Fechá-la como concluída
curl -X POST https://api.wagend.app/v1/bookings/$TASK_ID/actions/concluir \
  -H "Authorization: Bearer $WAGEND_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "data": {} }'

Se duas pessoas pegam a mesma tarefa ao mesmo tempo, uma ganha e a outra recebe 409 already_claimed. A ação "Aceitar entrega" (aceitar) é para a equipe pelo painel ou Telegram: pega a tarefa com o recurso de quem a executa.

Receber avisos por webhook

Registre um endpoint (veja Webhooks) e verifique a assinatura antes de processar. Exemplo mínimo com Express:

import express from 'express'
import { verifyWagend } from './verify' // a função da página de Webhooks

const app = express()
app.post('/wagend', express.raw({ type: 'application/json' }), (req, res) => {
  const raw = req.body.toString('utf8')
  if (!verifyWagend(raw, req.header('Wagend-Signature') ?? '', process.env.WAGEND_WEBHOOK_SECRET!)) {
    return res.sendStatus(400)
  }
  const event = JSON.parse(raw)
  if (event.type === 'booking.confirmed') console.log('Nova reserva', event.data.booking.id)
  res.sendStatus(200) // responda 2xx rápido; duplicados são descartados por event.id
})
app.listen(3000)

Modelos por negócio

Cada receita corresponde a um modelo pronto que você escolhe no onboarding.

Barbearia

Cada barbeiro é um recurso staff exclusive com seu próprio horário. Um grupo, customer_choice com round_robin como alternativa.

{
  "name": "Corte",
  "duration_min": 30,
  "step_min": 15,
  "buffer_after_min": 5,
  "price_cents": 5000,
  "requirements": [{ "resource_group_id": "grp_barbers", "units": 1 }]
}

Estética

Profissionais, máquinas e cabines são recursos separados. O serviço exige os três ao mesmo tempo, então o mais escasso (geralmente a máquina) limita a agenda.

{
  "name": "Depilação a laser",
  "duration_min": 45,
  "buffer_after_min": 10,
  "price_cents": 18000,
  "deposit_cents": 5000,
  "requirements": [
    { "resource_group_id": "grp_professionals", "units": 1 },
    { "resource_group_id": "grp_lasers", "units": 1 },
    { "resource_group_id": "grp_rooms", "units": 1 }
  ]
}

Clínica

Médico mais consultório, por unidade (um workspace por unidade). Dados de saúde são sensíveis: o assistente nunca pergunta sintomas, e o formulário coleta só o necessário para agendar.

{
  "name": "Consulta",
  "duration_min": 30,
  "buffer_after_min": 10,
  "intake_form": { "type": "object", "properties": { "convenio": { "type": "string" } } },
  "requirements": [
    { "resource_group_id": "grp_doctors", "units": 1 },
    { "resource_group_id": "grp_offices", "units": 1 }
  ]
}

Restaurante

O salão é um recurso pooled com 40 unidades (lugares) por turno. A duração cresce com o tamanho do grupo, e grupos grandes pagam sinal.

{
  "name": "Mesa",
  "step_min": 30,
  "duration_by_units": [
    { "max_units": 2, "duration_min": 90 },
    { "max_units": 4, "duration_min": 120 },
    { "max_units": 20, "duration_min": 150 }
  ],
  "requirements": [{ "resource_group_id": "grp_dining_room", "units": "party_size" }]
}

O modo mesas (mesas específicas com tamanho mínimo e máximo, e combinações) está no roadmap.

Entregas

Cada zona é um recurso pooled com capacidade por janela de 2 horas. A zona é escolhida pelo CEP, e uma regra de corte fecha as janelas do mesmo dia ao meio-dia.

{
  "name": "Entrega",
  "window_mode": true,
  "duration_min": 120,
  "cutoff_rule": { "same_day_until": "12:00" },
  "intake_form": { "type": "object", "required": ["address", "cep"] },
  "requirements": [{ "resource_group_id": "grp_zones", "units": 1, "select_by": "cep" }]
}