Guía de uso de la API v3
Cómo trabajar con la API v3 de Clau.io usando una API key con permisos, paso a paso, con las reglas de negocio que hay que conocer.
La API v3 se activa por negocio. Para usarla necesita una API key con permisos creada desde el dashboard (Configuración → API Keys → API keys con permisos). Si su negocio aún no la tiene habilitada, contacte a soporte.
Esta guía está pensada tanto para integradores como para agentes de IA que ejecuten la API a partir de su referencia. Cada endpoint de la referencia Ext v3 describe sus parámetros, su cuerpo con ejemplo y el scope que exige.
Para usar estas operaciones desde un asistente de IA, consulta el MCP de Clau, la configuración por cliente y los flujos de clientes, puntos y reportes.
1. Empiece por GET /me
GET /meSolo necesita la key: incluye el APPID de su negocio (ck_<APPID>_...), así que no hace falta el header APPID. Devuelve el tenant, los scopes de la key y sus límites. Con eso sabe qué endpoints puede usar antes de intentar nada. Un 403 con meta.requiredScope indica exactamente qué scope falta.
curl 'https://api3.clau.io/ext/v3/me' -H 'apikey: ck_...'2. Identifique al cliente
Casi todas las acciones reciben el uid del cliente en la ruta. Para obtenerlo:
GET /clientes/buscar?email=...(otelefono,numId,extId): devuelveuserId, que es eluid.GET /clientes?since=...&fields=extended: recorrido completo con cursor, para sincronizaciones.
3. Reglas que conviene saber
| Tema | Regla |
|---|---|
| Puntos | Se expresan en la unidad pública, la misma que ve el cliente y el dashboard. Un valor negativo resta. Hay un límite por llamada. |
| Fechas | YYYY-MM-DD significa el día completo en la zona horaria del negocio. Los rangos inicio/fin son inclusivos. |
| Montos | En unidades monetarias, salvo el registro de compras (POST /compras), que usa centavos como el POS. |
| Escrituras | POST, PUT, PATCH y DELETE exigen el header Idempotency-Key (8 a 128 caracteres, por ejemplo un UUID). Repetir la misma operación con la misma key devuelve la respuesta original; cambiar el cuerpo con la misma key responde 409. |
| Acciones de grupo | Primero cree el grupo (POST /segmentos/evaluar, /segmentos/lista o /segmentos/predefinido), después use /grupos/{grupoId}/.... Ejecute siempre con dryRun: true antes de aplicar: devuelve cuántos clientes afecta y el costo estimado. |
| Reportes | GET /reportes/catalogo lista datasets, campos y métricas; POST /reportes/ejecutar corre el reporte (hasta 5000 filas de forma síncrona). Con async: true responde 202 y el resultado se consulta en GET /reportes/jobs/{jobId} hasta que deje de responder 202. |
| Cursor de clientes | La entrega es "al menos una vez": un cliente modificado durante el recorrido puede aparecer de nuevo. Procese por firebase_uid de forma idempotente. |
| Errores del negocio | Un 422 trae el codigoRespuesta y el msj originales del dashboard con meta.legacy: true. Léalos tal cual: explican la regla que no se cumplió. |
| Ayuda | Cualquier endpoint responde su ayuda en texto plano con ?help=true. |
4. Flujos típicos
Compensar a un cliente con puntos
GET /clientes/[email protected]→userId.POST /clientes/{uid}/puntoscon{ "puntos": 150, "motivo": "Compensación ticket 4412" }y unIdempotency-Key.GET /clientes/{uid}/puntospara confirmar el asiento.
Premiar a un segmento
POST /segmentos/evaluarcon el filtro (por ejemplo nivel ≥ 3 y etiqueta VIP) →grupoId.POST /grupos/{grupoId}/regaloscon{ "regaloId": 45, "dryRun": true }para ver el alcance.- Repita sin
dryRunpara aplicar. LuegoPOST /grupos/{grupoId}/notificacionespara avisar.
Sacar un reporte de puntos del mes
GET /reportes/catalogo→ campos del datasetlealtad.POST /reportes/ejecutarconconfig={ "type": "lealtad", "fields": [...], "filters": [{ "field": "loyalty.points_date", "operator": "between", "value": ["2026-08-01", "2026-08-31"] }] }.- Si respondió
202, consulteGET /reportes/jobs/{jobId}.
Crear una automatización
GET /tareas/catalogo→ ids de disparadores, condiciones y acciones.POST /tareascondatos(nombre,trigger.triggerId,acciones[].accionIdy sus parámetros).POST /tareas/{tareaId}/statuscon{ "status": 1 }para activarla.
5. Límites
Cada key tiene límites por minuto para lecturas, escrituras y acciones de grupo. Al excederlos la respuesta es 429 con Retry-After. Las respuestas incluyen X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset.
Updated 3 days ago