Primeiros passos
Da primeira leitura ao primeiro agendamento no negócio de teste, em cinco chamadas.
Atualizado em 10 de outubro de 2026
Antes de começar
A API pública não pede conta nem chave. Todas as chamadas abaixo usam a base https://agendria.com.br/api/v1 e o negócio de teste sandbox-agendria. As reservas dele são reais, mas ficam isoladas: não ocupam horário de ninguém, não mandam mensagem e não geram Pix nem cobrança.
- Dinheiro chega em centavos, com
currencyBRL. - Datas seguem ISO 8601, e os horários livres usam o fuso do negócio.
- Prefere explorar clicando? A referência interativa deixa montar e enviar cada chamada.
1. Ler o negócio
Leituras não mudam nada. Comece pelos serviços: o id de um deles entra nas próximas chamadas.
curl "https://agendria.com.br/api/v1/public/shops/sandbox-agendria/services"const base = "https://agendria.com.br/api/v1/public";
const res = await fetch(`${base}/shops/sandbox-agendria/services`);
const { data: services } = await res.json();
console.log(services.map((s) => s.name));import requests
base = "https://agendria.com.br/api/v1/public"
services = requests.get(f"{base}/shops/sandbox-agendria/services").json()["data"]
print([s["name"] for s in services])2. Ver horários livres
Informe o serviço e quantos dias olhar (de 1 a 31). Cada horário traz start_at e os profissionais livres em staff_ids.
curl "https://agendria.com.br/api/v1/public/shops/sandbox-agendria/availability?service_id=SERVICE_ID&days=3"const url = new URL(`https://agendria.com.br/api/v1/public/shops/sandbox-agendria/availability`);
url.search = new URLSearchParams({ service_id: service.id, days: "3" });
const availability = await fetch(url).then((r) => r.json());
const slot = availability.days.flatMap((d) => d.slots)[0];availability = requests.get(
f"{base}/shops/sandbox-agendria/availability",
params={"service_id": service["id"], "days": 3},
).json()
slot = next(s for d in availability["days"] for s in d["slots"])3. Simular
bookings:quote confere horário, profissional e preço sem reservar nada e devolve um quote_id válido por 15 minutos. Mostre o resumo para a pessoa antes de seguir.
curl -X POST "https://agendria.com.br/api/v1/public/shops/sandbox-agendria/bookings:quote" \
-H "Content-Type: application/json" \
-d '{"service_id":"SERVICE_ID","start_at":"2026-10-12T13:00:00.000Z","guest_name":"Maria","guest_phone":"11988887777"}'const body = {
service_id: service.id,
start_at: slot.start_at,
staff_id: slot.staff_ids[0],
guest_name: "Maria",
guest_phone: "11988887777",
};
const quote = await fetch(`${base}/shops/sandbox-agendria/bookings:quote`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body),
}).then((r) => r.json());body = {
"service_id": service["id"],
"start_at": slot["start_at"],
"staff_id": slot["staff_ids"][0],
"guest_name": "Maria",
"guest_phone": "11988887777",
}
quote = requests.post(f"{base}/shops/sandbox-agendria/bookings:quote", json=body).json()4. Agendar
Depois do sim, envie os mesmos campos com o quote_id. Usar o quote_id também como Idempotency-Key evita reserva duplicada se a chamada for repetida.
curl -X POST "https://agendria.com.br/api/v1/public/shops/sandbox-agendria/bookings" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: QUOTE_ID" \
-d '{"service_id":"SERVICE_ID","start_at":"2026-10-12T13:00:00.000Z","guest_name":"Maria","guest_phone":"11988887777","quote_id":"QUOTE_ID"}'const res = await fetch(`${base}/shops/sandbox-agendria/bookings`, {
method: "POST",
headers: { "Content-Type": "application/json", "Idempotency-Key": quote.quote_id },
body: JSON.stringify({ ...body, quote_id: quote.quote_id }),
});
const booking = await res.json();
const manageToken = booking.manage_token;res = requests.post(
f"{base}/shops/sandbox-agendria/bookings",
json={**body, "quote_id": quote["quote_id"]},
headers={"Idempotency-Key": quote["quote_id"]},
)
booking = res.json()
manage_token = booking["manage_token"]5. Consultar e cancelar
Com o token no cabeçalho X-Booking-Token, você consulta a reserva (e o Pix, quando houver sinal), cancela ou remarca.
curl "https://agendria.com.br/api/v1/public/shops/sandbox-agendria/bookings/BOOKING_ID" \
-H "X-Booking-Token: MANAGE_TOKEN"
curl -X POST "https://agendria.com.br/api/v1/public/shops/sandbox-agendria/bookings/BOOKING_ID:cancel" \
-H "X-Booking-Token: MANAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"reason":"Imprevisto"}'const headers = { "X-Booking-Token": manageToken };
const current = await fetch(`${base}/shops/sandbox-agendria/bookings/${booking.id}`, { headers }).then((r) => r.json());
await fetch(`${base}/shops/sandbox-agendria/bookings/${booking.id}:cancel`, {
method: "POST",
headers: { ...headers, "Content-Type": "application/json" },
body: JSON.stringify({ reason: "Imprevisto" }),
});headers = {"X-Booking-Token": manage_token}
current = requests.get(f"{base}/shops/sandbox-agendria/bookings/{booking['id']}", headers=headers).json()
requests.post(
f"{base}/shops/sandbox-agendria/bookings/{booking['id']}:cancel",
json={"reason": "Imprevisto"},
headers=headers,
)Próximos passos
Entenda os limites
Limites e erros mostra o que fazer com um 429 e com cada motivo de erro.
Conecte um assistente
O servidor MCP faz tudo isso por você no ChatGPT ou no Claude.