Guía
Autenticación
Cada pedido se autentica con una clave de API de la organización, enviada como token Bearer.
El header Authorization
La clave va en el header Authorization de todos los pedidos, por HTTPS. Un pedido sin clave responde 401 con el código api_key_missing.
Authorization: Bearer kd_live_1a2b3c4d5e6f_…curl https://www.kuida.ar/api/v1/account \
-H "Authorization: Bearer kd_test_…"Formato y entornos
Una clave tiene la forma kd_<entorno>_<prefijo>_<secreto>. El prefijo identifica la clave y se puede mostrar en registros; el secreto no se muestra nunca más después de la entrega.
kd_live_- EntornoProducción. Opera sobre los pacientes reales de la organización y envía mensajes reales por WhatsApp.
kd_test_- EntornoEmitida fuera de producción, para desarrollo y pruebas.
El campo livemode de GET /v1/account y de cada webhook indica en qué entorno se está operando.
Cómo se obtiene una clave
Kuida emite las claves: no hay alta autoservicio. Se piden a desarrolladores@kuida.ar o al contacto comercial, con el nombre del sistema que la va a usar. Se recomienda una clave por sistema integrado, para poder revocar una sin afectar a las demás.
La clave es un secreto del servidor
Guárdela en una variable de entorno o en el gestor de secretos del servidor. Nunca en el código fuente, en un repositorio, en una aplicación móvil ni en código que corra en el navegador. Quien tenga la clave puede leer y modificar los pacientes de la organización.
Permisos
Cada operación exige un permiso con la forma <recurso>:read o <recurso>:write. Una clave nueva incluye todos los permisos. Si la clave no tiene el que corresponde, la respuesta es 403 con el código scope_missing. Los permisos de la clave en uso aparecen en apiKey.scopes de GET /v1/account.
events:write- Operacionesevents.create
events:read- Operacionesevents.retrieveevents.list
patients:read- Operacionespatients.retrievepatients.list
patients:write- Operacionespatients.createpatients.update
doctors:read- Operacionesdoctors.listdoctors.retrieve
appointments:read- Operacionesappointments.retrieveappointments.list
appointments:write- Operacionesappointments.createappointments.updateappointments.cancel
visits:read- Operacionesvisits.retrievevisits.list
visits:write- Operacionesvisits.create
intake_requests:read- Operacionesintake_requests.retrieveintake_requests.list
intake_requests:write- Operacionesintake_requests.create
treatments:read- Operacionestreatments.retrievetreatments.list
treatments:write- Operacionestreatments.create
webhooks:read- Operacioneswebhook_endpoints.retrievewebhook_endpoints.listwebhook_deliveries.listwebhook_deliveries.retrieve
webhooks:write- Operacioneswebhook_endpoints.createwebhook_endpoints.updatewebhook_endpoints.deletewebhook_endpoints.ping
- cualquier clave válida
- Operacionesaccount.retrieve
Algunas operaciones exigen además que la organización tenga contratada una línea de servicio; la referencia lo indica en cada una. Sin ella, la respuesta es 403 con service_not_contracted.
Rotación
Para cambiar una clave sin cortar la integración:
- Pedir a Kuida una clave nueva para el mismo sistema.
- Configurarla en el servidor y verificarla con
GET /v1/account. - Pedir la revocación de la clave anterior.
Las dos claves funcionan en paralelo hasta que se revoca la anterior.
Revocación y vencimiento
Una clave revocada deja de funcionar de inmediato: los pedidos responden 401 con api_key_revoked. Si se sospecha que una clave se filtró, escriba a desarrolladores@kuida.ar para revocarla y emitir otra. Una clave con fecha de vencimiento responde api_key_expired después de esa fecha.