Documentación / Recursos Avançados
Recursos Avançados

Cómo Crear una Agenda (Calendario) Vía API

Crear una Agenda

Resumen

La API de la plataforma eAgenda permite crear agendas (calendarios) de forma programática, configurando horarios, servicios, modos de programación y permisos. Esta guía práctica detalla cómo enviar una solicitud HTTP POST al endpoint /api/v3/calendars/ y procesar la respuesta. Para más detalles, consulte la documentación oficial de la API de eAgenda.

Preparación del Entorno

Antes de comenzar, necesitará:

  • Clave de API: Acceda al panel de eAgenda para obtener su token Bearer.
  • Herramienta para solicitudes HTTP: Use cURL, Postman o bibliotecas como requests (Python) o axios (JavaScript).
  • Configuración del encabezado: La autenticación se realiza mediante Bearer Token. Configure el encabezado Authorization: Bearer y defina Content-Type: application/json.

Consejo: Consulte la sección de autenticación en la documentación de la API para configurar el token correctamente: https://eagenda.com.br/api/v3/documents/#overview.

Definición de los Datos de la Agenda

Para crear una agenda, envíe un objeto JSON en el cuerpo de la solicitud con los siguientes campos:

{
  "calendar_name": "string",
  "slug": "string",
  "is_internal": boolean,
  "service_list": [
    {
      "service_key": "uuid"
    }
  ],
  "time_config": {
    "opening_hours": [
      {
        "week_day": "string",
        "opening_time": "time",
        "closing_time": "time",
        "max_people": integer
      }
    ],
    "slot_interval": "string",
    "duration": "string",
    "minimum_notice": integer,
    "maximum_notice": integer,
    "start_date": "date",
    "end_date": "date"
  },
  "online_meeting_platform": "string",
  "max_people": integer,
  "request_email": boolean,
  "email_required": boolean,
  "request_phone": boolean,
  "phone_required": boolean,
  "max_companions": integer,
  "max_services": integer,
  "count_companions": boolean,
  "appointment_mode": "string",
  "owner_user": "email",
  "account_slug": "string"
}

calendar_name (obligatorio)

  • Descripción: Nombre de la agenda.
  • Restricciones: Mínimo de 1 carácter.
  • Impacto: Identifica la agenda en el sistema.
  • Ejemplo: “Agenda Principal”

slug (opcional)

  • Descripción: Nombre del enlace para la agenda.
  • Restricciones: Máximo de 250 caracteres, patrón ^[-a-zA-Z0-9_]+$.
  • Impacto: Define un identificador amigable para la URL de la agenda.
  • Ejemplo: “agenda-principal”

is_internal (obligatorio)

  • Descripción: Indica si la agenda es de uso interno (solo administradores).
  • Impacto: Restringe el acceso a administradores si es true.
  • Ejemplo: false

service_list (opcional)

  • Descripción: Lista de servicios asociados a la agenda.
  • Estructura: Array de objetos, cada uno con service_key (UUID).
  • Cómo obtener: Use el endpoint de listado de servicios (/api/v3/services/).
  • Impacto: Define los servicios disponibles para programación.
  • Ejemplo:[ { "service_key": "19730681-29f0-4000-848c-34869ad83880" } ]

time_config (obligatorio)

  • Descripción: Configuraciones de horarios y programación.
  • Estructura: Objeto con:
    • opening_hours: Lista de horarios de funcionamiento por día de la semana.
      • week_day: Día de la semana (ej.: “1” para lunes, hasta “7” para domingo).
      • opening_time: Horario de apertura (formato HH:MM:SS).
      • closing_time: Horario de cierre (formato HH:MM:SS).
      • max_people: Número máximo de personas por horario (mín. 0, máx. 2147483647).
      • Ejemplo:[ { "week_day": "1", "opening_time": "08:00:00", "closing_time": "17:00:00", "max_people": 10 } ]
    • slot_interval: Intervalo entre opciones de programación (ej.: “00:15:00” para 15 minutos).
    • duration: Duración predeterminada de la cita (ej.: “00:30:00”).
    • minimum_notice: Tiempo mínimo de aviso para programar (en horas).
    • maximum_notice: Tiempo máximo de aviso para programar (en días).
    • start_date: Fecha de inicio para citas (formato YYYY-MM-DD).
    • end_date: Fecha de finalización para citas (formato YYYY-MM-DD).
  • Ejemplo:{ "opening_hours": [ { "week_day": "1", "opening_time": "08:00:00", "closing_time": "17:00:00", "max_people": 10 } ], "slot_interval": "00:15:00", "duration": "00:30:00", "minimum_notice": 2, "maximum_notice": 30, "start_date": "2025-06-01", "end_date": "2025-12-31" }

online_meeting_platform (opcional)

  • Descripción: Proveedor de videoconferencia.
  • Valores posibles: meet, teams, zoom, other.
  • Impacto: Define la plataforma para reuniones en línea.
  • Ejemplo: “meet”

max_people (obligatorio)

  • Descripción: Número máximo de personas por horario.
  • Impacto: Limita la capacidad de programación.
  • Ejemplo: 10

request_email (opcional)

  • Descripción: Solicitar correo electrónico de contacto.
  • Impacto: Incluye campo de correo electrónico en el formulario de programación si es true.
  • Ejemplo: true

email_required (opcional)

  • Descripción: Correo electrónico obligatorio para programar.
  • Impacto: Exige correo electrónico si es true.
  • Ejemplo: false

request_phone (opcional)

  • Descripción: Solicitar teléfono de contacto.
  • Impacto: Incluye campo de teléfono en el formulario de programación si es true.
  • Ejemplo: true

phone_required (opcional)

  • Descripción: Teléfono obligatorio para programar.
  • Impacto: Exige teléfono si es true.
  • Ejemplo: false

max_companions (opcional)

  • Descripción: Número máximo de acompañantes por cita.
  • Restricciones: Mínimo de 0, predeterminado 0.
  • Impacto: Limita el número de acompañantes.
  • Ejemplo: 2

max_services (opcional)

  • Descripción: Número máximo de servicios por cita.
  • Restricciones: Mínimo de 0, predeterminado 0.
  • Impacto: Limita los servicios seleccionables.
  • Ejemplo: 3

count_companions (opcional)

  • Descripción: Contar acompañantes en el total de personas.
  • Impacto: Incluye acompañantes en el conteo de max_people si es true.
  • Ejemplo: false

appointment_mode (opcional)

  • Descripción: Modo de programación.
  • Valores posibles: hybrid, online, on_site, off_site.
  • Impacto: Define si la cita es presencial, en línea o híbrida.
  • Ejemplo: “hybrid”

owner_user (opcional)

  • Descripción: Correo electrónico del usuario responsable de la agenda.
  • Impacto: Vincula la agenda a un responsable.
  • Ejemplo: “responsavel@example.com”

account_slug (opcional)

  • Descripción: Slug de la cuenta o subcuenta.
  • Restricciones: Mínimo de 1 carácter, patrón ^[-a-zA-Z0-9_]+$.
  • Cómo obtener: Use el endpoint de listado de cuentas.
  • Impacto: Vincula la agenda a una cuenta específica.
  • Ejemplo: “minha-conta”

Nota: Los campos obligatorios son calendar_name, is_internal, time_config y max_people. Los demás son opcionales, pero recomendados para mayor control.

Envío de la Solicitud para Crear una Agenda

Para crear una agenda, envíe una solicitud HTTP POST al endpoint:

https://eagenda.com.br/api/v3/calendars/

Configuración de la Solicitud

  • Método: POST
  • Encabezados:
    • accept: application/json
    • Authorization: Bearer
    • Content-Type: application/json
  • Cuerpo de la solicitud: JSON con los datos de la agenda.

Ejemplo de Solicitud con cURL

curl -X POST https://eagenda.com.br/api/v3/calendars/ \
-H "accept: application/json" \
-H "Authorization: Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999" \
-H "Content-Type: application/json" \
-d '{
  "calendar_name": "Agenda Principal",
  "slug": "agenda-principal",
  "is_internal": false,
  "service_list": [
    {
      "service_key": "19730681-29f0-4000-848c-34869ad83880"
    }
  ],
  "time_config": {
    "opening_hours": [
      {
        "week_day": "1",
        "opening_time": "08:00:00",
        "closing_time": "17:00:00",
        "max_people": 10
      }
    ],
    "slot_interval": "00:15:00",
    "duration": "00:30:00",
    "minimum_notice": 2,
    "maximum_notice": 30,
    "start_date": "2025-06-01",
    "end_date": "2025-12-31"
  },
  "online_meeting_platform": "meet",
  "max_people": 10,
  "request_email": true,
  "email_required": false,
  "request_phone": true,
  "phone_required": false,
  "max_companions": 2,
  "max_services": 3,
  "count_companions": false,
  "appointment_mode": "hybrid",
  "owner_user": "responsavel@example.com",
  "account_slug": "minha-conta"
}'

Ejemplo en Python (usando requests)

import requests

url = "https://eagenda.com.br/api/v3/calendars/"
headers = {
    "accept": "application/json",
    "Authorization": "Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999",
    "Content-Type": "application/json"
}
data = {
    "calendar_name": "Agenda Principal",
    "slug": "agenda-principal",
    "is_internal": False,
    "service_list": [
        {
            "service_key": "19730681-29f0-4000-848c-34869ad83880"
        }
    ],
    "time_config": {
        "opening_hours": [
            {
                "week_day": "1",
                "opening_time": "08:00:00",
                "closing_time": "17:00:00",
                "max_people": 10
            }
        ],
        "slot_interval": "00:15:00",
        "duration": "00:30:00",
        "minimum_notice": 2,
        "maximum_notice": 30,
        "start_date": "2025-06-01",
        "end_date": "2025-12-31"
    },
    "online_meeting_platform": "meet",
    "max_people": 10,
    "request_email": True,
    "email_required": False,
    "request_phone": True,
    "phone_required": False,
    "max_companions": 2,
    "max_services": 3,
    "count_companions": False,
    "appointment_mode": "hybrid",
    "owner_user": "responsavel@example.com",
    "account_slug": "minha-conta"
}

response = requests.post(url, json=data, headers=headers)
print(response.status_code)
print(response.json())

Verificación de la Respuesta

La API devolverá una respuesta con el estado de la creación de la agenda. Verifique los siguientes puntos:

  • Código de estado HTTP:
    • 201 Created: Agenda creada con éxito.
    • 400 Bad Request: Error en los datos enviados (verifique el JSON).
    • 401 Unauthorized: Token inválido o ausente.
  • Cuerpo de la respuesta: Contiene detalles de la agenda creada, como:{ "calendar_key": "19730681-29f0-4000-8d78-94e4d6116180", "calendar_name": "Agenda Principal", "slug": "agenda-principal", "is_active": false, "is_internal": false, "service_list": [ { "service_key": "19730681-29f0-4000-848c-34869ad83880", "service_name": "Consulta Médica" } ], "appointment_link": "https://eagenda.com.br/agenda-principal", "time_config": { "opening_hours": [ { "week_day": "1", "opening_time": "08:00:00", "closing_time": "17:00:00", "max_people": 10 } ], "slot_interval": "00:15:00", "duration": "00:30:00", "minimum_notice": 2, "maximum_notice": 30, "start_date": "2025-06-01", "end_date": "2025-12-31" }, "online_meeting_platform": "meet", "max_people": 10, "request_email": true, "email_required": false, "request_phone": true, "phone_required": false, "max_companions": 2, "max_services": 3, "count_companions": false, "appointment_mode": "hybrid", "owner_user": "responsavel@example.com", "address": { "postal_code": "12345-678", "street": "Rua Exemplo", "neighborhood": "Centro", "number": "123", "complement": "Sala 101", "city": { "name": "São Paulo", "state_name": "São Paulo", "state_code": "SP", "country_code": "BR" } }, "account_slug": "minha-conta" }

La agenda quedará registrada en el sistema y estará lista para recibir citas, respetando las configuraciones definidas.

Conclusión

Con este tutorial, aprendió cómo crear una agenda (calendario) vía API de eAgenda, configurando horarios, servicios y permisos de forma eficiente. Esta integración es ideal para gestionar citas en diferentes contextos, como atenciones presenciales, en línea o híbridas. Para más funcionalidades, como listado o edición de agendas, consulte la documentación completa de la API de eAgenda.

Contáctenos o Conozca Más

Estamos a su disposición para ayudarle. Acceda a nuestros canales oficiales:

📞 WhatsApp : Haga clic aquí para enviarnos un mensaje 🌐 Plataforma eAgenda : Conozca eAgenda 🏢 Nuestra Empresa : Mupi Systems – Soluciones Innovadoras 📧 Correo electrónico : contato@mupisystems.com.br 📚 Tutoriales y Documentación : Acceda a nuestras guías y tutoriales