Documentación API - Gestión de Citas

Esta API permite a las aplicaciones externas crear y gestionar citas médicas. Todas las peticiones deben incluir un token JWT en el encabezado Authorization.

Encabezado requerido:
Authorization: Bearer <token_jwt>

Ejemplo de generación en Python:

                    
                        import jwt
                        from datetime import datetime, timedelta
                        SECRET_KEY = "CLAVE_SECRETA"
                        payload = {
                            "sub": "keybe_integration",
                            "exp": datetime.utcnow() + timedelta(days=30),
                            "iat": datetime.utcnow(),
                        }
                        token = jwt.encode(payload, SECRET_KEY, algorithm="HS256")
                        print(token)

1 - Obtener Clínicas

Devuelve el listado de clínicas disponibles para reservar una cita.

Método: POST

URL: /v1/app/clinics

Ejemplo de petición en Python:

                    
                        import requests
                        url = “https://tuservidor.com/v1/app/clinics”
                        token = “TU_TOKEN_JWT_AQUI”
                        headers = {
                            “Authorization”: f”Bearer {token}”,
                            “Content-Type”: “application/json”
                        }
                        response = requests.post(url, headers=headers)
                        data = response.json()
                        print(data)

Ejemplo de petición en cURL:

                    
                        curl -X POST http://vime.local:8069/v1/app/clinics \
                        -H "Authorization: Bearer V1m3"

Respuesta exitosa:

                    
                        {
                            "success": true,
                            "data": {
                            "count": "1",
                            "clinics": [
                                    {
                                        "id": "vime-coapa-141784",
                                        "name": "Vime Coapa",
                                    }
                                ]
                            }
                        }

Respuesta de error:

                    
                        {
                            "success": false,
                            "error": "Unauthorized",
                            "message": "Missing or invalid token header",
                        }

2 - Buscar Disponibilidad de Clínica

Devuelve los horarios disponibles para una clínica específica en una fecha determinada.

Método: POST

URL: /v1/app/clinic_availability

Ejemplo de petición en Python:

                    
                        import requests
                        import json
                        url = “https://tuservidor.com/v1/app/clinic_availability”
                        token = “TU_TOKEN_JWT_AQUI”
                        headers = {
                            “Authorization”: f”Bearer {token}”,
                            “Content-Type”: “application/json”
                        }
                        payload = {
                            “clinic_id”: “vime-coapa-141784”,
                            “date”: “2025-10-20”
                        }
                        response = requests.post(url, headers=headers, data=json.dumps(payload))
                        data = response.json()
                        print(data)

Ejemplo de petición en cURL:

                    
                        curl -X POST "https://tuservidor.com/v1/app/clinic_availability" \
                        -H "Authorization: Bearer TU_TOKEN_JWT_AQUI" \
                        -H "Content-Type: application/json" \
                        -d '{
                        "clinic_id": "vime-coapa-141784",
                        "date": "2025-10-20"
                        }'

Respuesta exitosa:

                    
                        {
                            "success": true,
                            "data": {
                                "clinic_id": "vime-coapa-141784",
                                "clinic_name": "Vime Coapa",
                                "date": "2025-10-20",
                                "available_slots": [
                                    {"utc_datetime": "2025-10-20 18:00:00", "tz_datetime": "2025-10-20 12:00:00", "tz_time": "12:00"}
                                ],
                            },
                        }

Respuestas de error:

                    
                        {
                            "success": false,
                            "error": "Unauthorized",
                            "message": "Missing or invalid token header",
                        }

3 - Crear Cita

Permite crear una cita en una clínica específica, generar el cliente (si no existe) y crear el enlace de pago asociado.

Método: POST

URL: /v1/app/create_appointment

Ejemplo de petición en Python:

                    
                        import requests
                        import json
                        url = “https://tuservidor.com/v1/app/create_appointment”
                        token = “TU_TOKEN_JWT_AQUI”
                        headers = {
                        “Authorization”: f”Bearer {token}”,
                        “Content-Type”: “application/json”
                        }
                        payload = {
                            “clinic_id”: “vime-coapa-141784”,
                            “date”: “2025-10-20 09:00:00”,
                            “customer”: {
                                “name”: “Juan Pérez”,
                                “email”: “juan.perez@example.com”,
                                “phone”: “5512345678”
                            }
                        }
                        response = requests.post(url, headers=headers, data=json.dumps(payload))
                        data = response.json()
                        print(data)

Ejemplo de petición en cURL:

                    
                        curl -X POST "https://tuservidor.com/v1/app/create_appointment" \
                        -H "Authorization: Bearer TU_TOKEN_JWT_AQUI" \
                        -H "Content-Type: application/json" \
                        -d '{
                        "clinic_id": "vime-coapa-141784",
                        "date": "2025-10-20 09:00:00",
                        "customer": {
                        "name": "Juan Pérez",
                        "email": "juan.perez@example.com",
                        "phone": "5512345678"
                        }
                        }'

Respuesta exitosa:

                    
                        {
                            "success": true,
                            "data": {
                                "appointment_id": "uuid-de-la-cita",
                                "quotation_id": "uuid-de-la-orden",
                                "clinic_id": "vime-coapa-141784",
                                "customer_id": "uuid-del-cliente",
                                "payment": {
                                    "reference": {
                                        "cie_reference": "2380722",
                                        "beneficiary": "DIET LINE LATIN AMERICA SAPI DE CV",
                                        "clabe": "012914002023807223",
                                        "personal_reference": "UNIQUE_REF_123"
                                    },
                                    "link": "https://tuservidor.com/payment-link"
                                }
                            },
                            "message": "Cita creada exitosamente para Juan Pérez en Vime Coapa el 2025-10-20 09:00:00 (America/Mexico_City)"
                        }

Respuestas de error:

                    
                        {
                        "success": false,
                        "error": "Unauthorized",
                        "message": "Missing or invalid token header",
                        }