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

Pregúntale a la IA

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