Primeros pasos

1Obtener una clave de API

Kuida emite las claves para cada organización: no hay alta autoservicio. Pídala a desarrolladores@kuida.ar o a su contacto comercial, indicando qué sistema la va a usar. La clave se entrega una sola vez; Kuida guarda solo un hash y no puede volver a mostrarla.

Guárdela como variable de entorno del servidor que hace los pedidos, nunca en código que corra en un navegador o en una aplicación móvil:

export KUIDA_API_KEY="kd_test_…"

Las claves kd_live_ operan sobre pacientes reales: crear un turno con una de ellas programa recordatorios reales por WhatsApp. Para desarrollar, use una clave kd_test_. Más detalle en Autenticación.

2Usar la URL base con www

Todos los pedidos van a https://www.kuida.ar/api seguido de la versión y el recurso, por ejemplo https://www.kuida.ar/api/v1/patients.

3Instalar un SDK

Los SDKs agregan la clave y la versión a cada pedido, generan la Idempotency-Key de los POST, reintentan los errores transitorios y convierten los errores en excepciones. También se puede usar HTTP directo: todos los ejemplos tienen su versión en curl.

npm install @kuida/sdk

Código fuente y documentación de cada uno: github.com/Kuida-ar/kuida-sdks.

4Verificar la conexión

GET /v1/account devuelve la organización dueña de la clave, sus líneas de servicio y los permisos de la clave. No modifica nada.

curl https://www.kuida.ar/api/v1/account \
  -H "Authorization: Bearer kd_test_…"

{
  "id": "org_cm1a2b3c4d5e6f7g8h9i0j",
  "object": "account",
  "name": "Institución Demo",
  "type": "clinic",
  "timeZone": "America/Argentina/Buenos_Aires",
  "serviceLines": [
    "follow_up"
  ],
  "livemode": false,
  "apiKey": {
    "name": "Sistema de turnos",
    "prefix": "kd_test_0a1b2c3d4e5f",
    "scopes": [
      "patients:read",
      "patients:write"
    ]
  }
}

Si responde 401, la clave está mal copiada o fue revocada; ver errores de autenticación.

5Crear un paciente

El teléfono con WhatsApp es la identidad del paciente en Kuida y es obligatorio. Si ya existe un paciente con ese teléfono o ese DNI, la respuesta devuelve el existente y completa los datos que le faltaban, sin pisar los cargados. externalId guarda el id del paciente en su sistema. Crear un paciente no le envía ningún mensaje.

curl https://www.kuida.ar/api/v1/patients \
  -H "Authorization: Bearer kd_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+54 9 342 555 0000",
  "fullName": "Paciente Demo",
  "dni": "11111111",
  "externalId": "HC-1234"
}'

{
  "id": "pat_cm1a2b3c4d5e6f7g8h9i0j",
  "object": "patient",
  "fullName": "Paciente Demo",
  "phone": "+5493425550000",
  "email": "paciente.demo@example.com",
  "dni": "11111111",
  "externalId": "HC-1234",
  "dateOfBirth": null,
  "stage": "pending_follow_up",
  "optedOut": false,
  "createdAt": "2026-10-01T17:30:00.000Z",
  "updatedAt": "2026-10-01T17:30:00.000Z"
}

6Cargar un turno

Un turno se asocia a un paciente por su id de Kuida (pat_…) o por los mismos datos con que lo conoce su sistema; en el segundo caso Kuida lo busca y, si no existe, lo crea. Al guardarse, Kuida programa los recordatorios por WhatsApp que la institución tiene configurados.

curl https://www.kuida.ar/api/v1/appointments \
  -H "Authorization: Bearer kd_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "patient": {
    "phone": "+54 9 342 555 0000",
    "fullName": "Paciente Demo"
  },
  "doctor": {
    "externalId": "MED-12",
    "fullName": "Dra. Demo"
  },
  "startAt": "2026-10-05T10:30:00-03:00",
  "type": "Control",
  "externalId": "turno-123"
}'

{
  "id": "apt_cm1a2b3c4d5e6f7g8h9i0j",
  "object": "appointment",
  "patient": "pat_cm1a2b3c4d5e6f7g8h9i0j",
  "doctor": "doc_cm1a2b3c4d5e6f7g8h9i0j",
  "startAt": "2026-10-01T17:30:00.000Z",
  "status": "confirmed",
  "type": "Control",
  "externalId": "turno-123",
  "source": "api",
  "cancelledAt": null,
  "createdAt": "2026-10-01T17:30:00.000Z",
  "updatedAt": "2026-10-01T17:30:00.000Z"
}

Con externalId, reenviar el mismo turno devuelve el existente. Para reprogramarlo o cancelarlo se usan PATCH /v1/appointments/{id} y POST /v1/appointments/{id}/cancel.