---
title: "Primeiros passos · API e MCP · Agendria"
description: "Da primeira leitura ao primeiro agendamento no negócio de teste, em cinco chamadas."
last_updated: 2026-10-10
canonical: "https://agendria.com.br/desenvolvedores/primeiros-passos"
---

# Primeiros passos · API e MCP · Agendria

[Desenvolvedores](/desenvolvedores)

[Referência](/desenvolvedores/referencia)

## 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 `currency` BRL.
- Datas seguem ISO 8601, e os horários livres usam o fuso do negócio.
- Prefere explorar clicando? A [referência interativa](/desenvolvedores/referencia) 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"]`
```

Guarde o manage_token

Ele aparece uma única vez, na resposta da criação. É o que permite consultar, cancelar e remarcar essa reserva depois. Trate como uma senha.

## 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

1.   Entenda os limites
  [Limites e erros](/desenvolvedores/limites-e-erros) mostra o que fazer com um 429 e com cada motivo de erro.
2.   Conecte um assistente
  O [servidor MCP](/desenvolvedores/mcp) faz tudo isso por você no ChatGPT ou no Claude.

## Sitemap

Veja o [mapa do site](https://agendria.com.br/sitemap.md) com todas as páginas em Markdown.
