API pública e servidor MCP da Agendria

A Agendria é uma plataforma brasileira de agendamento online para negócios de horário marcado, como barbearias, salões, estética, pet, lava-jatos, tatuagem, saúde e aulas. A API pública e o servidor MCP deixam qualquer aplicativo ou assistente de IA buscar esses negócios, ver serviços, preços e horários livres e agendar em nome de uma pessoa, sem conta e sem chave de acesso.

Especificação OpenAPI

A especificação completa, em OpenAPI 3.1, é gerada dos mesmos contratos que a API valida: https://agendria.com.br/api/v1/openapi.json. A base dos endpoints é https://agendria.com.br/api/v1. Valores em dinheiro chegam em centavos (amount inteiro, currency BRL). Datas seguem ISO 8601, e os horários livres são calculados no fuso do negócio.

Autenticação

Endpoints públicos (busca, perfil, serviços, profissionais, horários e criação de agendamento) não pedem autenticação. A criação devolve um manage_token uma única vez. Esse token vale para um agendamento e vai no cabeçalho X-Booking-Token para consultar, cancelar, remarcar ou gerar novo Pix. Ele não dá acesso a nenhum outro dado do negócio nem de outros clientes.

O painel do dono (agenda completa, clientes, caixa, relatórios) usa login com token JWT. Ele não faz parte da API pública nem do MCP.

Limites e boas práticas

• Criar agendamento, cancelar e remarcar: 20 requisições por minuto por IP e negócio. Novo Pix: 10 por minuto.
• Servidor MCP: 60 requisições por minuto por IP e 5 agendamentos confirmados a cada 10 minutos por IP.
• Envie Idempotency-Key (um UUID por tentativa) nos POST. Repetir a mesma chave com o mesmo corpo devolve a resposta original, sem agendar duas vezes.
• Erros seguem { error: { code, message, details } }. A mensagem vem em português, pronta para mostrar. Com 429, espere e tente de novo.
• Leituras públicas usam cache curto (60 s; horários livres, 15 s). Confirme o horário logo antes de agendar.

Exemplos com curl

curl "https://agendria.com.br/api/v1/public/discovery/search?vertical=barbershop&city=S%C3%A3o%20Paulo"

SLUG=barbearia-exemplo
curl "https://agendria.com.br/api/v1/public/shops/$SLUG/services"
curl "https://agendria.com.br/api/v1/public/shops/$SLUG/availability?service_id=SERVICE_ID&date_from=2026-10-10&days=3"

curl -X POST "https://agendria.com.br/api/v1/public/shops/$SLUG/bookings" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"service_id":"SERVICE_ID","start_at":"2026-10-10T13:00:00.000Z","guest_name":"Maria","guest_phone":"11988887777"}'

curl "https://agendria.com.br/api/v1/public/shops/$SLUG/bookings/BOOKING_ID" -H "X-Booking-Token: MANAGE_TOKEN"
curl -X POST "https://agendria.com.br/api/v1/public/shops/$SLUG/bookings/BOOKING_ID:cancel" \
  -H "X-Booking-Token: MANAGE_TOKEN" -H "Content-Type: application/json" -d '{"reason":"Imprevisto"}'

Exemplo em JavaScript

const base = "https://agendria.com.br/api/v1/public";
const slug = "barbearia-exemplo";

const { data: services } = await fetch(`${base}/shops/${slug}/services`).then((r) => r.json());
const service = services[0];

const availability = await fetch(
  `${base}/shops/${slug}/availability?service_id=${service.id}&days=7`,
).then((r) => r.json());
const slot = availability.days.flatMap((d) => d.slots)[0];

const res = await fetch(`${base}/shops/${slug}/bookings`, {
  method: "POST",
  headers: { "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({
    service_id: service.id,
    start_at: slot.start_at,
    staff_id: slot.staff_ids[0],
    guest_name: "Maria",
    guest_phone: "11988887777",
  }),
});
const booking = await res.json();

booking.manage_token só aparece nesta resposta: guarde-o. booking.payment.pix_copy_paste vem preenchido quando o negócio pede sinal por Pix.

Servidor MCP para assistentes de IA

O servidor Model Context Protocol da Agendria usa o transporte Streamable HTTP em https://agendria.com.br/mcp, sem autenticação. Ele tem estas ferramentas:

Confirmação obrigatória. Chamado sem confirm, create_booking só simula: devolve um resumo e um quote_id. O agendamento só acontece numa segunda chamada com confirm: true, o mesmo quote_id e os mesmos dados. O assistente deve mostrar o resumo e esperar o sim do cliente antes dessa chamada. A resposta traz um booking_token e o link de gestão. Se o negócio pedir sinal, traz também o Pix copia e cola.

Como conectar

• Claude (web, desktop e celular): Configurações, Conectores, Adicionar conector personalizado, URL https://agendria.com.br/mcp.
• ChatGPT: Configurações, Apps e conectores, ative o modo desenvolvedor e crie um conector com a URL https://agendria.com.br/mcp, sem autenticação.
• Claude Code: claude mcp add --transport http agendria https://agendria.com.br/mcp
• Instalação local (stdio), em qualquer cliente MCP:

{
  "mcpServers": {
    "agendria": { "command": "npx", "args": ["-y", "@agendria/mcp"] }
  }
}

Descoberta por IA

Resumo para modelos de linguagem: /llms.txt e /llms-full.txt. Catálogo de servidores MCP do domínio: /.well-known/ai-catalog.json. Server Card: https://agendria.com.br/mcp/server-card.

Dados pessoais

Nome e celular do cliente vão só para o negócio escolhido, para confirmar e lembrar o horário, conforme a Política de Privacidade e a LGPD. Envie apenas os dados da própria pessoa que está agendando.

Suporte

Dúvidas, integrações ou um limite maior: [email protected].