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

Cómo Actualizar o Cancelar una Cita Vía API

Actualizar o Cancelar una Cita

Resumen

La API de la plataforma eAgenda permite actualizar o cancelar una cita de forma programática, ajustando el estado o eliminando compromisos existentes. Esta guía práctica detalla cómo enviar solicitudes HTTP PATCH para actualizar (/api/v3/appointments/{appointment_key}/) y DELETE para cancelar (/api/v3/appointments/{appointment_key}/) una cita, además de procesar las respuestas. 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, para la actualización, defina Content-Type: application/json.
  • Clave de la cita (appointment_key): Obtenga el UUID de la cita a actualizar o cancelar, generalmente devuelto al crear o listar citas.

Consejo: Consulte la sección de autenticación en la documentación de la API para configurar el token correctamente.

Actualizar una Cita

Para actualizar una cita, envíe una solicitud HTTP PATCH al endpoint /api/v3/appointments/{appointment_key}/, modificando el estado u otros parámetros.

Definición de los Datos para Actualización

Envíe un objeto JSON en el cuerpo de la solicitud con los siguientes campos:

{
  "status": "string",
  "send_email": boolean,
  "account_slug": "string"
}

status (opcional)

  • Descripción: Nuevo estado de la cita.
  • Valores posibles: ATTENDED, CANCELED, CANCELED_CLIENT, CANCELED_GOOGLE, CONFIRMED, IN_PROGRESS, NO_SHOW, PENDING, PENDING_COMPANIONS, PENDING_FORM, PENDING_PAYMENT.
  • Impacto: Cambia el estado de la cita.
  • Ejemplo: “CONFIRMED”

send_email (opcional)

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

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 actualización a una cuenta específica.
  • Ejemplo: “minha-conta”

Nota: Se debe enviar al menos un campo para actualizar la cita.

Envío de la Solicitud para Actualizar

Para actualizar una cita, envíe una solicitud HTTP PATCH al endpoint:

https://eagenda.com.br/api/v3/appointments/{appointment_key}/

Configuración de la Solicitud

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

Ejemplo de Solicitud con cURL

curl -X PATCH https://eagenda.com.br/api/v3/appointments/19730681-29a0-4000-8ddf-025c8f2d1401/ \
-H "accept: application/json" \
-H "Authorization: Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999" \
-H "Content-Type: application/json" \
-d '{
  "status": "CONFIRMED",
  "send_email": true,
  "account_slug": "minha-conta"
}'

Ejemplo en Python (usando requests)

import requests

url = "https://eagenda.com.br/api/v3/appointments/19730681-29a0-4000-8ddf-025c8f2d1401/"
headers = {
    "accept": "application/json",
    "Authorization": "Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999",
    "Content-Type": "application/json"
}
data = {
    "status": "CONFIRMED",
    "send_email": True,
    "account_slug": "minha-conta"
}

response = requests.patch(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 actualización. Verifique los siguientes puntos:

  • Código de estado HTTP:
    • 200 OK: Cita actualizada con éxito.
    • 400 Bad Request: Error en los datos enviados (verifique el JSON).
    • 401 Unauthorized: Token inválido o ausente.
    • 404 Not Found: appointment_key inválido.
  • Cuerpo de la respuesta: Contiene los detalles actualizados de la cita, como:
{
  "appointment_key": "19730681-29a0-4000-8ddf-025c8f2d1401",
  "search_code": "A001",
  "status": "CONFIRMED",
  "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": "minha-conta"
}

La cita será actualizada en el sistema, reflejando los cambios enviados.

Cancelar una Cita

Para cancelar una cita, envíe una solicitud HTTP DELETE al endpoint /api/v3/appointments/{appointment_key}/.

Definición de los Parámetros para Cancelación

appointment_key (obligatorio)

  • Descripción: Clave UUID de la cita.
  • Impacto: Identifica la cita a cancelar.
  • Cómo obtenerla: Obtenida al crear o listar citas.
  • Ejemplo: 19730681-29a0-4000-8ddf-025c8f2d1401

send_email (opcional)

  • Descripción: Envía correo electrónico de notificación de cancelación.
  • Impacto: Notifica a los participantes si es true.
  • Ejemplo: true

Envío de la Solicitud para Cancelar

Para cancelar una cita, envíe una solicitud HTTP DELETE al endpoint:

https://eagenda.com.br/api/v3/appointments/{appointment_key}/

Configuración de la Solicitud

  • Método: DELETE
  • Encabezados:
    • accept: application/json
    • Authorization: Bearer
  • Query-string: Parámetro send_email (ej.: ?send_email=true).

Ejemplo de Solicitud con cURL

curl -X DELETE "https://eagenda.com.br/api/v3/appointments/19730681-29a0-4000-8ddf-025c8f2d1401/?send_email=true" \
-H "accept: application/json" \
-H "Authorization: Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999"

Ejemplo en Python (usando requests)

import requests

url = "https://eagenda.com.br/api/v3/appointments/19730681-29a0-4000-8ddf-025c8f2d1401/"
headers = {
    "accept": "application/json",
    "Authorization": "Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999"
}
params = {
    "send_email": True
}

response = requests.delete(url, headers=headers, params=params)
print(response.status_code)
print(response.json())

Verificación de la Respuesta

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

  • Código de estado HTTP:
    • 200 OK: Cita cancelada con éxito.
    • 401 Unauthorized: Token inválido o ausente.
    • 404 Not Found: appointment_key inválido.
  • Cuerpo de la respuesta: Contiene los detalles de la cita cancelada, con el estado actualizado a CANCELED, como:
{
  "appointment_key": "19730681-29a0-4000-8ddf-025c8f2d1401",
  "search_code": "A001",
  "status": "CANCELED",
  "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á marcada como cancelada en el sistema, y los participantes serán notificados si send_email es true.

Conclusión

Con este tutorial, aprendió cómo actualizar o cancelar una cita vía API de eAgenda, utilizando los endpoints PATCH y DELETE para gestionar compromisos de forma eficiente. Estas integraciones son ideales para automatizar la administración de citas, ajustando estados o eliminando compromisos según sea necesario. Para más funcionalidades, como crear o listar 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