Neste tutorial, você vai aprender o fluxo completo para criar um agendamento via API: desde a consulta de agendas e horários até a confirmação do agendamento.

Fluxo de agendamento

O processo segue 4 etapas:

Listar agendas — Obter as agendas disponíveis
Listar serviços — Ver os serviços oferecidos
Consultar horários — Verificar disponibilidade
Criar o agendamento — Enviar os dados do agendamento

Passo 1: Listar agendas

Primeiro, obtenha a lista de agendas da sua conta:

curl -X GET "https://eagenda.com.br/api/v3/calendars/?is_active=true" \
  -H "Authorization: Basic SEU_TOKEN"

Resposta:

{
  "count": 2,
  "results": [
    {
      "calendar_key": "abc12345-1234-5678-9abc-def012345678",
      "name": "Consultório Dr. Silva",
      "slug": "consultorio-dr-silva",
      "is_active": true,
      "appointment_mode": "hybrid"
    }
  ]
}

Guarde o calendar_key — você vai precisar dele nos próximos passos.

Passo 2: Listar serviços

Consulte os serviços disponíveis para agendamento:

curl -X GET "https://eagenda.com.br/api/v3/services/" \
  -H "Authorization: Basic SEU_TOKEN"

Resposta:

{
  "count": 3,
  "results": [
    {
      "service_key": "srv12345-1234-5678-9abc-def012345678",
      "name": "Consulta Inicial",
      "duration": 60,
      "price": "150.00",
      "is_active": true
    }
  ]
}

Guarde o service_key dos serviços desejados.

Passo 3: Consultar horários disponíveis

Com o calendar_key e service_keys, consulte os horários disponíveis para um dia específico:

curl -X GET "https://eagenda.com.br/api/v3/available-date-times/?calendar_key=abc12345-1234-5678-9abc-def012345678&day=2026-06-10&service_keys=srv12345-1234-5678-9abc-def012345678" \
  -H "Authorization: Basic SEU_TOKEN"

Resposta:

{
  "count": 8,
  "results": [
    {
      "start_date": "2026-06-10T09:00:00-03:00",
      "end_date": "2026-06-10T10:00:00-03:00",
      "vacancies_available": 1
    },
    {
      "start_date": "2026-06-10T10:00:00-03:00",
      "end_date": "2026-06-10T11:00:00-03:00",
      "vacancies_available": 1
    }
  ]
}

Dica: Use o parâmetro action_new_appointment=client para ver apenas horários disponíveis considerando as restrições para agendamento por clientes.

Passo 4: Criar o agendamento

Com todas as informações, crie o agendamento:

curl -X POST "https://eagenda.com.br/api/v3/appointments/" \
  -H "Authorization: Basic SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "calendar_key": "abc12345-1234-5678-9abc-def012345678",
    "start_date": "2026-06-10T09:00:00-03:00",
    "service_keys": ["srv12345-1234-5678-9abc-def012345678"],
    "person": {
      "full_name": "João da Silva",
      "email": "joao@exemplo.com",
      "phone": "+5511999990000"
    }
  }'

Resposta (201 Created):

{
  "appointment_key": "apt12345-1234-5678-9abc-def012345678",
  "search_code": "AGD-2026-001234",
  "status": "CONFIRMED",
  "start_date": "2026-06-10T09:00:00-03:00",
  "end_date": "2026-06-10T10:00:00-03:00",
  "calendar": {
    "calendar_key": "abc12345-1234-5678-9abc-def012345678",
    "name": "Consultório Dr. Silva"
  },
  "person": {
    "person_key": "prs12345-1234-5678-9abc-def012345678",
    "full_name": "João da Silva",
    "email": "joao@exemplo.com"
  },
  "services": [
    {
      "service_key": "srv12345-1234-5678-9abc-def012345678",
      "name": "Consulta Inicial"
    }
  ]
}

Exemplo completo em Python

import requests

BASE_URL = "https://eagenda.com.br/api/v3"
AUTH = ("meu@email.com", "minha_senha")

# 1. Listar agendas ativas
calendars = requests.get(
    f"{BASE_URL}/calendars/",
    auth=AUTH,
    params={"is_active": True}
).json()

calendar_key = calendars["results"][0]["calendar_key"]

# 2. Listar serviços
services = requests.get(f"{BASE_URL}/services/", auth=AUTH).json()
service_key = services["results"][0]["service_key"]

# 3. Consultar horários disponíveis
slots = requests.get(
    f"{BASE_URL}/available-date-times/",
    auth=AUTH,
    params={
        "calendar_key": calendar_key,
        "day": "2026-06-10",
        "service_keys": service_key,
    }
).json()

start_date = slots["results"][0]["start_date"]

# 4. Criar o agendamento
appointment = requests.post(
    f"{BASE_URL}/appointments/",
    auth=AUTH,
    json={
        "calendar_key": calendar_key,
        "start_date": start_date,
        "service_keys": [service_key],
        "person": {
            "full_name": "João da Silva",
            "email": "joao@exemplo.com",
            "phone": "+5511999990000",
        },
    }
).json()

print(f"Agendamento criado: {appointment['search_code']}")
print(f"Status: {appointment['status']}")

Possíveis erros

Código	Causa	Solução
`400`	Dados inválidos ou incompletos	Verifique os campos obrigatórios
`400`	Horário não disponível	Consulte os horários disponíveis novamente
`401`	Não autenticado	Verifique suas credenciais
`403`	Sem permissão	Verifique as permissões da conta