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

Como Crear una Cita Vía API en eAgenda

Crear una Cita Vía API eAgenda

Resumen

La API de la plataforma eAgenda permite crear una cita de forma programática, configurando detalles como agenda, servicios, participantes y horarios. Esta guía práctica detalla cómo enviar una solicitud HTTP POST al endpoint /api/v3/appointments/ 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 Cita

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

{
  "status": "string",
  "calendar_key": "uuid",
  "service_list": [
    {
      "service_key": "uuid"
    }
  ],
  "tag_list": [
    {
      "tag_key": "uuid"
    }
  ],
  "owner_user": {
    "email": "email"
  },
  "attendees": [
    {
      "name": "string",
      "email": "email",
      "phone": "string",
      "identification_code": "string",
      "identification_type": "string"
    }
  ],
  "start": {
    "dateTime": "date-time"
  },
  "description": "string",
  "verify_limits": boolean,
  "send_email": boolean,
  "include_flows": boolean,
  "account_slug": "string"
}

status (opcional)

  • Descripción: Estado inicial de la cita.
  • Valores posibles: ATTENDED, CANCELED, CANCELED_CLIENT, CANCELED_GOOGLE, CONFIRMED, IN_PROGRESS, NO_SHOW, PENDING, PENDING_COMPANIONS, PENDING_FORM, PENDING_PAYMENT.
  • Impacto: Define el estado de la cita; el valor predeterminado es PENDING si no se informa.
  • Ejemplo: “PENDING”

calendar_key (obligatorio)

  • Descripción: Clave UUID de la agenda.
  • Impacto: Vincula la cita a una agenda específica.
  • Cómo obtenerla: Use el endpoint de listado de agendas (/api/v3/calendars/).
  • Ejemplo: “1973125a-ab10-4000-8674-eef17b31e080”

service_list (opcional)

  • Descripción: Lista de servicios asociados a la cita.
  • Estructura: Array de objetos, cada uno con service_key (UUID).
  • Cómo obtenerla: Use el endpoint de listado de servicios (/api/v3/services/).
  • Impacto: Especifica los servicios a realizar.
  • Ejemplo:[ { "service_key": "19730681-2aa0-4000-84b6-2bc54b4ace01" } ]

tag_list (opcional)

  • Descripción: Lista de etiquetas asociadas a la cita.
  • Estructura: Array de objetos, cada uno con tag_key (UUID).
  • Cómo obtenerla: Use el endpoint de listado de etiquetas.
  • Impacto: Permite categorizar la cita.
  • Ejemplo:[ { "tag_key": "a1b2c3d4-e5f6-7890-1234-567890abcdef" } ]

owner_user (opcional)

  • Descripción: Usuario responsable de la cita.
  • Estructura: Objeto con email.
  • Impacto: Vincula la cita a un responsable.
  • Ejemplo:{ "email": "responsable@example.com" }

attendees (obligatorio)

  • Descripción: Lista de participantes de la cita.
  • Estructura: Array de objetos, cada uno con:
    • name (obligatorio): Nombre del participante (1 a 200 caracteres).
    • email (opcional): Correo electrónico del participante.
    • phone (opcional): Teléfono en formato E.164.
    • identification_code (opcional): Documento de identificación.
    • identification_type (opcional): Tipo de documento (ej.: br_cpf, ar_dni).
  • Impacto: Define quién participará en la cita.
  • Ejemplo:[ { "name": "João Silva", "email": "joao.silva@example.com", "phone": "+5511999999999", "identification_code": "123.456.789-00", "identification_type": "br_cpf" } ]

start (obligatorio)

  • Descripción: Fecha y hora de inicio de la cita.
  • Estructura: Objeto con dateTime (formato ISO 8601).
  • Impacto: Define el horario de la cita.
  • Ejemplo:{ "dateTime": "2025-06-01T10:00:00Z" }

description (opcional)

  • Descripción: Descripción de la cita.
  • Restricciones: Mínimo de 1 carácter.
  • Impacto: Agrega información contextual.
  • Ejemplo: “Consulta de rutina”

verify_limits (opcional)

  • Descripción: Verifica los límites de citas configurados.
  • Impacto: Garantiza el cumplimiento de las reglas de la agenda si es true.
  • Ejemplo: true

send_email (opcional)

  • Descripción: Envía correo electrónico de confirmación de la cita.
  • Impacto: Notifica a los participantes si es true.
  • Ejemplo: false

include_flows (opcional)

  • Descripción: Incluye la cita en las reglas de notificación (si el estado es CONFIRMED).
  • Impacto: Activa flujos de notificación si es true.
  • Ejemplo: false

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 obtenerlo: Use el endpoint de listado de cuentas.
  • Impacto: Vincula la cita a una cuenta específica.
  • Ejemplo: “minha-conta”

Nota: Los campos obligatorios son calendar_key, attendees y start. Los demás son opcionales, pero se recomiendan para mayor control.

Ejemplo Básico:

{
  "status": "PENDING",
  "calendar_key": "1973125a-ab10-4000-8674-eef17b31e080",
  "attendees": [
    {
      "name": "João Silva",
      "email": "joao.silva@example.com"
    }
  ],
  "start": {
    "dateTime": "2025-06-01T10:00:00Z"
  }
}

Envío de la Solicitud para Crear una Cita

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

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

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 cita.

Ejemplo de Solicitud con cURL

curl -X POST https://eagenda.com.br/api/v3/appointments/ \
-H "accept: application/json" \
-H "Authorization: Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999" \
-H "Content-Type: application/json" \
-d '{
  "status": "PENDING",
  "calendar_key": "1973125a-ab10-4000-8674-eef17b31e080",
  "attendees": [
    {
      "name": "João Silva",
      "email": "joao.silva@example.com"
    }
  ],
  "start": {
    "dateTime": "2025-06-01T10:00:00Z"
  }
}'

Ejemplo en Python (usando requests)

import requests

url = "https://eagenda.com.br/api/v3/appointments/"
headers = {
    "accept": "application/json",
    "Authorization": "Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999",
    "Content-Type": "application/json"
}
data = {
    "status": "PENDING",
    "calendar_key": "1973125a-ab10-4000-8674-eef17b31e080",
    "attendees": [
        {
            "name": "João Silva",
            "email": "joao.silva@example.com"
        }
    ],
    "start": {
        "dateTime": "2025-06-01T10:00:00Z"
    }
}

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 cita. Verifique los siguientes puntos:

  • Código de estado HTTP:
    • 201 Created: Cita 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 los detalles de la cita creada, como:
{
  "appointment_key": "19730681-29a0-4000-8ddf-025c8f2d1401",
  "search_code": "A001",
  "status": "PENDING",
  "calendar": {
    "calendar_key": "1973125a-ab10-4000-8674-eef17b31e080",
    "calendar_name": "Agenda Principal"
  },
  "service_list": [],
  "tag_list": [],
  "attendees": [
    {
      "person_key": "19730681-29a0-4000-8584-d036c75a2f80",
      "name": "João Silva",
      "email": "joao.silva@example.com",
      "phone": null,
      "identification_code": null,
      "identification_type": null
    }
  ],
  "owner_user": null,
  "start": {
    "dateTime": "2025-06-01T10:00:00Z",
    "timeZone": "UTC"
  },
  "end": {
    "dateTime": "2025-06-01T10:30:00Z",
    "timeZone": "UTC"
  },
  "description": null,
  "questionnaires": [],
  "created_at": {
    "dateTime": "2025-06-01T09:58:00Z",
    "timeZone": "UTC"
  },
  "location": null,
  "conference_data": null,
  "account_slug": null
}

La cita quedará registrada en el sistema, respetando las configuraciones de la agenda y los datos proporcionados. Use el appointment_key para gestionar la cita en otras solicitudes.

Conclusión

Con este tutorial, aprendió cómo crear una cita vía API de eAgenda, configurando participantes, horarios y otros detalles de forma eficiente. Esta integración es ideal para automatizar la creación de citas, optimizando la gestión de compromisos. Para más funcionalidades, como listado de horarios disponibles o edición de citas, 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