Como Crear una Cita Vía API en Minha Agenda Virtual

Pregúntale a la IA

Crear una Cita Vía API Minha Agenda Virtual

Resumen

La API de la plataforma Minha Agenda Virtual 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 Minha Agenda Virtual.

Preparación del Entorno

Antes de comenzar, necesitará:

  • Clave de API: Acceda al panel de Minha Agenda Virtual 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": "+5511942529100", "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://minhaagendavirtual.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://minhaagendavirtual.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://minhaagendavirtual.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 Minha Agenda Virtual, 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 Minha Agenda Virtual.

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 Minha Agenda Virtual : Conozca Minha Agenda Virtual 🏢 Nuestra Empresa : Mupi Systems – Soluciones Innovadoras 📧 Correo electrónico : contato@mupisystems.com.br 📚 Tutoriales y Documentación : Acceda a nuestras guías y tutoriales