Empezar en 5 minutos - API de Craqui

En esta guía haces cuatro pedidos con una clave de prueba: confirmas la clave, lees el horario de la semana, pides la página siguiente y, al final, sabes qué cambia para usar los datos reales. Solo necesitas una terminal con curl.

1. Consigue una clave de prueba

La crea la propietaria del estudio en Craqui:

Configuración → Integraciones → API → Nueva clave.
En Entorno, Prueba. La primera vez, Craqui prepara el estudio de prueba: puede tardar unos segundos.
En Tipo de acceso, Completa sirve para esta guía. Si eliges Restringida, marca al menos los permisos del negocio (business:read) y de las sesiones (sessions:read).
Crear clave, y la copia en ese momento: es la única vez que se muestra.

La clave empieza con crq_test_. Guárdala en una variable de entorno de tu terminal:

export CRAQUI_API_KEY="crq_test_sk_TU_CLAVE"

Trata la clave como una contraseña: no la pegues en un chat, en un repositorio ni en código que corre en el navegador. Si se expone, pide que la revoquen y que creen otra.

2. Confirma la clave

curl -s https://api.craqui.com/v1/business \
  -H "Authorization: Bearer $CRAQUI_API_KEY"

La respuesta es el estudio de prueba. Su nombre termina en ” (prueba)” y livemode es false: todo lo que devuelve una clave de prueba lo dice.

{
  "id": "biz_01hzx8m4k2a7d9q3f5w6y8z0bc",
  "object": "business",
  "livemode": false,
  "name": "Estudio Marea (prueba)",
  "vertical": "wellness",
  "time_zone": "America/Montevideo",
  "currency": "UYU",
  "country": "UY",
  "public_url": null,
  "api_version": "2026-12-01",
  "warnings": []
}

Si en vez de esto recibes un error, su code te dice qué pasó y su type es el link a la página que explica qué hacer. Por ejemplo, invalid_api_key si la clave quedó incompleta al copiarla.

3. Lee el horario

GET /v1/sessions devuelve las sesiones entre dos fechas locales del estudio (local_date[gte] y local_date[lte], como mucho 31 días). Pide pocas por página para ver la paginación:

curl -s -G https://api.craqui.com/v1/sessions \
  -H "Authorization: Bearer $CRAQUI_API_KEY" \
  --data-urlencode "local_date[gte]=2026-12-01" \
  --data-urlencode "local_date[lte]=2026-12-07" \
  --data-urlencode "limit=3"

Usa fechas de esta semana y la que viene: el estudio de prueba tiene sesiones desde una semana atrás hasta dos semanas adelante del día en que se preparó.

La respuesta es una lista. Aquí, recortada a una sesión y a algunos de sus campos:

{
  "object": "list",
  "data": [
    {
      "id": "ses_01j9x2m4k2a7d9q3f5w6y8z0bd",
      "object": "session",
      "livemode": false,
      "class_id": "cls_01j9x2m4k2a7d9q3f5w6y8z0be",
      "local_date": "2026-12-01",
      "local_start_time": "08:00",
      "starts_at": "2026-12-01T08:00:00-03:00",
      "status": "scheduled",
      "capacity": 12,
      "booked_count": 6,
      "available_spots": 6
    }
  ],
  "has_more": true,
  "next_cursor": "eyJr…"
}

4. Pide la página siguiente

has_more: true dice que hay más. Repite el mismo pedido, con los mismos filtros, y agrega starting_after con el next_cursor que recibiste:

curl -s -G https://api.craqui.com/v1/sessions \
  -H "Authorization: Bearer $CRAQUI_API_KEY" \
  --data-urlencode "local_date[gte]=2026-12-01" \
  --data-urlencode "local_date[lte]=2026-12-07" \
  --data-urlencode "limit=3" \
  --data-urlencode "starting_after=EL_NEXT_CURSOR_DE_LA_RESPUESTA"

Sigue así hasta que has_more sea false. Si cambias un filtro a mitad de camino, el cursor deja de servir y recibes invalid_cursor. Más en Paginación.

5. Pasa a producción

Cuando tu código hace lo que quieres con el estudio de prueba:

La propietaria crea una clave con el entorno Producción: empieza con crq_live_.
Cambias la clave en tu sistema. La URL es la misma, las rutas también.
Los ids cambian: los del estudio de prueba no existen en producción. Si guardaste alguno, vuelve a leerlo con la clave nueva.

Siguientes pasos

Claves y permisos

Qué permiso necesita cada ruta y cómo cuidar una clave.

Entorno de prueba

Qué tiene el estudio de prueba y cómo restablecerlo.

Conceptos de un estudio

Clase, sesión, créditos y membresías, para quien no conoce un estudio.

Errores

La forma de un error y la lista de códigos.

​1. Consigue una clave de prueba

​2. Confirma la clave

​3. Lee el horario

​4. Pide la página siguiente

​5. Pasa a producción

​Siguientes pasos

Claves y permisos

Entorno de prueba

Conceptos de un estudio

Errores

1. Consigue una clave de prueba

2. Confirma la clave

3. Lee el horario

4. Pide la página siguiente

5. Pasa a producción

Siguientes pasos