Acceso API

Si su clínica ya usa otro sistema —de gestión, de facturación, o una hoja de cálculo— puede conectarlo con Pingclínica en vez de copiar datos a mano.

Con una clave API su sistema puede:

• leer las citas para mostrarlas en su propia agenda o en un reporte;
• importar y mantener al día su lista de pacientes y doctores.

Se configura en Configuración → Acceso API.

El cuestionario de salud nunca se entrega por esta vía. Es el único dato clínico que guarda Pingclínica y no está disponible con una clave API, sin importar los permisos que le dé.

Crear una clave

1. Entre a Configuración → Acceso API y toque Nueva clave.
2. Póngale un nombre que reconozca después (ej. «Sistema de gestión»).
3. Marque solo los permisos que ese sistema necesita.
4. Opcionalmente, fije una fecha de vencimiento.

Al crearla verá la clave una sola vez. Guárdela en ese momento: no volvemos a mostrarla. Si la pierde, cree una nueva y elimine la anterior.

Una clave se ve así:

pc_x7Kd9mQr2vBnL4pTz8wYcH3jF6sA1eR5uN0iO

Trátela como una contraseña. Debe vivir en su servidor, nunca en el navegador ni en una app móvil: cualquiera que la vea puede leer los datos de su clínica.

Permisos

Cada clave lleva solo los permisos que usted marque.

Eliminar es un permiso aparte de crear y editar, a propósito: así una clave que solo importa datos no puede borrar su registro si el programa que la usa tiene un error.

Si una clave intenta algo para lo que no tiene permiso, recibe un error 403 y no pasa nada.

Cómo se usa

La clave va en la cabecera Authorization de cada llamada:

curl https://api.pingclinica.com/api/public/v1/whoami \
  -H "Authorization: Bearer pc_su_clave_aqui"

Nunca la ponga en la dirección (?api_key=…): quedaría registrada en los archivos de cada servidor por el que pase. Si lo intenta, la rechazamos.

Para comprobar que una clave funciona, use /whoami. Le devuelve su clínica, su zona horaria y los permisos de esa clave:

{
  "clinic": { "id": "…", "name": "Clínica Vista", "timezone": "America/Guayaquil" },
  "scopes": ["appointments:read", "patients:write"],
  "expires_at": null
}

Leer citas

curl "https://api.pingclinica.com/api/public/v1/appointments?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer pc_su_clave_aqui"

Respuesta:

{
  "data": [
    {
      "id": "8f14e45f-…",
      "scheduled_at": "2026-09-15T14:00:00+00:00",
      "scheduled_at_local": "2026-09-15T09:00:00-05:00",
      "duration_minutes": 30,
      "procedure_type": "consultation",
      "status": "confirmed",
      "patient_name": "Ana Torres",
      "patient_phone": "593991112233",
      "patient_id": "3c6e0b8a-…",
      "provider_name": "Dra. Vega",
      "provider_id": "1b6453892-…",
      "created_at": "2026-09-01T18:22:10+00:00",
      "updated_at": "2026-09-02T11:05:44+00:00"
    }
  ],
  "has_more": false,
  "next_offset": null
}

Cada cita trae la hora dos veces: scheduled_at en UTC, para que su sistema haga cálculos sin ambigüedad, y scheduled_at_local en la zona de su clínica, para mostrarla tal como la vive su equipo.

Es la misma forma que reciben los avisos por HTTPS, así que si ya procesa avisos, no necesita escribir un segundo lector.

Filtros

Sincronizar sin repetir trabajo

Para traer solo lo que cambió desde la última vez, use updated_since:

1. Pida ?updated_since=<la última marca que guardó>.
2. Recorra las páginas con next_offset hasta que has_more sea false.
3. Guarde el updated_at más alto que vio y úselo la próxima vez.

Con updated_since ordenamos por fecha de modificación, no por fecha de cita. Eso importa: si alguien modifica una cita mientras usted está recorriendo páginas, esa cita se va al final en vez de mover las páginas que ya leyó, así no se le escapa ninguna.

Importar pacientes y doctores

Para cargar una lista existente, mande todo junto:

curl -X POST https://api.pingclinica.com/api/public/v1/patients/bulk \
  -H "Authorization: Bearer pc_su_clave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "name": "Ana Torres", "phone": "0991112233", "external_id": "PAC-001" },
      { "name": "Beto Paz", "phone": "0994445566", "external_id": "PAC-002" }
    ]
  }'

La respuesta le dice qué pasó fila por fila:

{
  "summary": { "created": 1, "updated": 0, "failed": 1 },
  "results": [
    { "index": 0, "status": "created", "id": "3c6e0b8a-…" },
    { "index": 1, "status": "error", "error": "invalid_phone" }
  ]
}

Una fila con un error no cancela las demás. Corrija esa fila y vuelva a mandarla.

Repetir el envío es seguro

Use external_id: el identificador que ese paciente o doctor ya tiene en su sistema. Cuando lo manda, reconocemos el registro y lo actualizamos en vez de crear un duplicado. Así puede correr la importación todas las noches sin acumular repetidos.

• Pacientes: si no manda external_id, usamos el teléfono. Un 0991112233 y un 593991112233 son el mismo paciente para nosotros.
• Doctores: no hay forma de reconocerlos sin external_id —dos doctores pueden llamarse igual—, así que sin él siempre se crea uno nuevo.

Horarios de los doctores

Puede importar el horario semanal:

{
  "name": "Dra. Vega",
  "external_id": "EMP-7",
  "schedule": {
    "mon": [{ "start": "09:00", "end": "13:00" }, { "start": "14:00", "end": "18:00" }],
    "fri": [{ "start": "09:00", "end": "12:00" }]
  }
}

Los días son mon, tue, wed, thu, fri, sat, sun. Las horas van en formato de 24 horas con dos dígitos (09:00, no 9:00). Un día que no aparece es un día que no atiende.

Validamos el horario al recibirlo y le decimos qué está mal, en vez de guardarlo y dejar que su agenda deje de mostrar turnos sin explicación.

Eliminar

• Pacientes: se borran del registro. Sus citas pasadas se conservan con el nombre y teléfono con que se agendaron.
• Doctores: se desactivan, no se borran. Un doctor con citas no se puede borrar sin borrar su historial, así que lo sacamos de la agenda y dejamos su historia intacta. Es lo mismo que hace el panel.

Límite de uso

Cada clave admite 60 llamadas por minuto. Si se pasa, recibe un 429 con la cabecera Retry-After; espere y reintente.

Un envío masivo cuenta como una sola llamada, sin importar cuántas filas lleve (hasta 500). Importar mil pacientes son dos llamadas, no mil.

Cambiar una clave

No hay «renovar»: para cambiar una clave, cree la nueva, actualice su sistema, y recién entonces elimine la vieja. Durante ese rato ambas funcionan, así que no se corta el servicio.

Eliminar una clave tiene efecto inmediato: la siguiente llamada que la use recibe un 401. Si sospecha que una clave se filtró, elimínela sin dudar — puede crear otra en segundos.

Errores