Descripción General de la API de Agentes

Introducción a la API de Agentes para operaciones de fidelización máquina a máquina.

La API de Agentes permite que sistemas externos operen tu plataforma de fidelización sin una interfaz de usuario. Los sistemas POS otorgan puntos por compra, los asistentes de IA revisan saldos y sugieren recompensas, y las herramientas de automatización activan acciones de fidelidad desde eventos externos — todo a través de una única API REST sin estado.

Qué Hace

Arquitectura de un vistazo

Principios clave de diseño:

• Sin estado — Sin sesiones, sin cookies, sin CSRF. Cada solicitud es independiente.
• Basado en JSON — Todas las solicitudes y respuestas son JSON.
• Mismas reglas de negocio — La API aplica exactamente las mismas validaciones, límites y permisos que el panel interactivo.
• Cero-UI — Sin configuración regional en la URL. El idioma es opcional a través del encabezado Accept-Language.
• Auditado — Cada solicitud se registra en los Registros de Actividad con completa trazabilidad.

Es una Herramienta, No una IA

La API de Agentes no incluye una IA — es una interfaz estructurada que los agentes de IA (o cualquier otro sistema) pueden llamar como una herramienta. Se ubica junto a la búsqueda web, operaciones de archivos y consultas de base de datos como algo sobre lo que actúa un agente autónomo.

Piensa en los agentes de IA de hoy — herramientas como Claude (Anthropic), Operator de OpenAI, Perplexity, Google Gemini o modelos alojados como DeepSeek y Qwen — como el lado del "cerebro" de este diagrama. La API de Agentes está en el lado de las "herramientas". Este espacio evoluciona rápidamente; para cuando leas esto, pueden haber surgido nuevos actores. A la API no le importa qué agente se conecte — habla HTTP y JSON puros.

Ya sea que estés conectando un asistente de IA, un sistema POS o un canal de automatización, la arquitectura sigue siendo la misma:

No se necesita una clave de proveedor de LLM en el lado de la plataforma. La API de Agentes solo ve el encabezado X-Agent-Key y el cuerpo de la solicitud JSON. Todo funciona idénticamente — un comando curl es un "agente" tan válido como un asistente de IA autónomo complejo.

Qué está listo para agentes hoy:

• Recuperación de errores estructurada — cada respuesta incluye un campo retry_strategy para que los agentes manejen errores autónomamente.
• Claves que se auto-identifican — el endpoint /health devuelve el rol de la clave, alcances y límites, permitiendo a los agentes entender sus propios permisos.
• Referencia completa de endpoints — documenta cada ruta, parámetro y campo de respuesta.
• Especificación OpenAPI 3.0 — Disponible en /api/agent/docs.json para importar en Swagger UI o Postman.
• Endpoint de descubrimiento de herramientas — GET /api/agent/v1/tools devuelve definiciones de herramientas legibles por máquina, con el formato que tu framework de agentes requiere.

Inicio Rápido

FEATURE_AGENT_API=true

rl_agent_a8f3k2m1x9v4b7n2p5q8r1t6w3y0z4d7f0h3j6l9...

curl -X GET https://tu-dominio.com/api/agent/v1/health \
  -H "X-Agent-Key: rl_agent_a8f3k2m1x9v4b7n2p5q8r1t6w3y0z4d7f0h3j6l9..."

{
  "error": false,
  "data": {
    "status": "ok",
    "key": {
      "name": "POS Terminal 1",
      "prefix": "rl_agent_a8f3k2m1",
      "role": "partner",
      "scopes": ["read", "write:transactions"],
      "rate_limit": 60,
      "expires_at": null
    },
    "owner": {
      "id": "9e1a...",
      "name": "Coffee Corner",
      "type": "partner"
    }
  }
}

URL Base

Todas las solicitudes de la API de Agentes utilizan:

Sin prefijo de configuración regional. Sin token de sesión. Solo la clave.

Estado Actual y Hoja de Ruta

Enviado — Cobertura Completa de API

Todos los endpoints a través de los tres roles están en vivo y listos para producción:

Enviado — Herramientas Nativas de Agente

Autenticación

Cómo funcionan las claves de la API de Agentes, modelo de seguridad y flujo de autenticación.

La API de Agentes utiliza claves de API de larga duración en lugar de tokens de inicio de sesión. Cada clave es autosuficiente — contiene la identidad, el rol y los permisos necesarios para autenticar una solicitud.

Cómo Funciona

Cada solicitud debe incluir la clave en el encabezado X-Agent-Key:

curl -X GET https://tu-dominio.com/api/agent/v1/health \
  -H "X-Agent-Key: rl_agent_a8f3k2m1x9v4b7n2..."

El flujo de autenticación:

• Extraer la clave del encabezado X-Agent-Key
• Detectar el rol de la clave desde el prefijo (rl_admin_, rl_agent_, rl_member_)
• Buscar claves candidatas por prefijo (consulta de base de datos indexada — rápida)
• Verificar la clave sin procesar contra el hash bcrypt almacenado
• Comprobar que la clave esté activa y no haya expirado
• Comprobar que la cuenta del propietario de la clave esté activa
• Vincular la clave y el propietario a la solicitud para uso en etapas posteriores

Formato de Clave

Las claves siguen un formato predecible:

rl_agent_a8f3k2m1x9v4b7n2p5q8r1t6w3y0z4d7f0h3j6l9m2o5r8u1w4z7c0e3...
└──────┘ └──────┘ └─────────────────────────────────────────────────────┘
  rol    prefijo                  secreto aleatorio

El prefijo es la única parte almacenada en texto plano. Permite búsquedas rápidas sin escanear toda la tabla. El resto tiene un hash con bcrypt — incluso con acceso a la base de datos, la clave no puede ser reconstruida.

Roles de Clave

Cada clave pertenece a un tipo de propietario:

Los tres tipos de clave están disponibles.

Modelo de Seguridad

Visualización Única

Cuando se crea una clave, la clave completa se muestra exactamente una vez. Después de cerrar el cuadro de diálogo, solo es visible el prefijo. No hay forma de recuperar la clave completa — si se pierde, crea una nueva.

Hash Bcrypt

Las claves se almacenan como hashes bcrypt (el mismo algoritmo utilizado para las contraseñas). Esto significa:

• Las fugas de base de datos no exponen las claves.
• Ni siquiera los administradores pueden ver la clave completa.
• Cada verificación de clave toma ~100ms (factor de carga incorporado de bcrypt).

Límite de Tasa (Rate Limiting)

Cada clave tiene un límite de tasa configurable (solicitudes por minuto, por defecto: 60). El límite se aplica por clave utilizando una ventana fija de 1 minuto — dos claves propiedad del mismo socio tienen límites separados.

Cada respuesta incluye encabezados de límite de tasa para que los clientes puedan regular el ritmo proactivamente:

X-RateLimit-Limit: 60          ← máximas solicitudes por ventana
X-RateLimit-Remaining: 42      ← solicitudes restantes en la ventana actual
X-RateLimit-Reset: 1741260000  ← marca de tiempo Unix de cuándo se reinicia la ventana

Cuando se excede el límite, la API devuelve HTTP 429 con un encabezado adicional Retry-After:

{
  "error": true,
  "code": "RATE_LIMITED",
  "message": "Too many requests. Please slow down.",
  "retry_strategy": "backoff",
  "details": {
    "limit": 60,
    "window_seconds": 60,
    "retry_after_seconds": 23
  }
}

Expiración

Las claves pueden tener opcionalmente una fecha de expiración. Las claves expiradas son rechazadas en la autenticación. Esto es útil para:

• Integraciones temporales.
• Acceso de API por tiempo limitado.
• Rotación de claves programada.

Comprobación de Actividad del Propietario

Incluso con una clave válida, si la cuenta del propietario está desactivada (por ejemplo, cuenta de socio deshabilitada por el administrador), la clave es rechazada. Esto asegura que la revocación de la clave a nivel de cuenta sea inmediata.

Errores de Autenticación

Todos los errores de autenticación siguen la estructura de error estándar:

Ejemplo de respuesta de error:

{
  "error": true,
  "code": "AUTH_KEY_REVOKED",
  "message": "This agent key has been revoked.",
  "retry_strategy": "no_retry"
}

Consulta el Manejo de Errores para ver el formato completo de la estructura de error.

Mejores Prácticas

Primera Llamada

Realiza tu primera llamada autenticada a la API de Agentes y elige el modelo de clave adecuado para tu integración.

Esta guía permite configurar una nueva integración desde cero hasta su primera solicitud exitosa. Se centra en el contrato de producción real: prefijos de clave, formato de encabezado, sobres de respuesta y las primeras comprobaciones que debe realizar una integración antes de comenzar a otorgar puntos o canjear recompensas.

1. Elije el tipo de clave correcto

Utiliza la clave más restrictiva que se ajuste a la tarea.

Si tu sistema necesita realizar operaciones financieras o de programas de fidelización en nombre de una empresa, utiliza una clave de socio. Si solo necesitas leer o actualizar la billetera de un miembro, utiliza una clave de miembro. No utilices una clave de socio cuando una clave de miembro sea suficiente.

2. Habilitar la función

La API de Agentes está restringida por funcionalidades.

• Establece FEATURE_AGENT_API=true en tu entorno.
• Para las integraciones con socios, habilita el permiso de API de Agentes del socio en la interfaz de administración.
• Crea la clave en el área correspondiente del panel de control.

Si la función está deshabilitada para un socio, los endpoints del socio devuelven:

{
  "error": true,
  "code": "FEATURE_DISABLED",
  "message": "Agent API access is not enabled for this partner.",
  "retry_strategy": "contact_support"
}

3. Almacena la clave correctamente

Cada solicitud envía la clave en el encabezado X-Agent-Key.

X-Agent-Key: rl_agent_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0
X-Agent-Key: rl_member_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8
X-Agent-Key: rl_admin_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0

Datos importantes:

• El prefijo de rol es parte de la clave sin procesar: rl_agent_, rl_member_, o rl_admin_.
• La parte secreta aleatoria tiene 40 caracteres.
• La clave completa se muestra una sola vez en el momento de la creación.
• La clave completa no se puede recuperar posteriormente. En caso de pérdida, crea una nueva clave y revoca la anterior.

4. Primero, haz un chequeo de estado

Antes de llamar a cualquier endpoint de negocio, llama a GET /api/agent/v1/health.

GET /api/agent/v1/health HTTP/1.1
Host: tu-dominio.com
Accept: application/json
X-Agent-Key: rl_agent_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0

Respuesta exitosa:

{
  "error": false,
  "data": {
    "status": "ok",
    "key": {
      "name": "POS Terminal 1",
      "prefix": "rl_agent_A1b2C3d4",
      "role": "partner",
      "scopes": ["read", "write:transactions", "write:rewards"],
      "rate_limit": 60,
      "expires_at": null,
      "created_at": "2026-03-08T16:00:00+00:00",
      "last_used_at": "2026-03-08T16:10:00+00:00"
    },
    "owner": {
      "id": "019cce5d-bd7e-73ec-b4ce-9dc6f7f73ed8",
      "name": "Coffee Corner",
      "type": "partner"
    }
  }
}

Utiliza esta respuesta para verificar:

• La clave se autentica correctamente.
• El rol es correcto.
• Los alcances coinciden con tu integración.
• El límite de tasa es apropiado.

5. Comprender el patrón de respuesta principal

Las respuestas de éxito utilizan un sobre JSON estable:

{
  "error": false,
  "data": {
    "id": "resource-id"
  }
}

Las respuestas paginadas añaden un objeto pagination:

{
  "error": false,
  "data": [],
  "pagination": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 25,
    "total": 81
  }
}

Comportamiento de paginación predeterminado:

• per_page por defecto es 25.
• per_page está limitado a 100.

Convenciones de localización:

• Los campos de recursos, como el uso de miembros, utilizan códigos de configuración regional instalados como en_US o es_ES.
• El encabezado Accept-Language utiliza etiquetas de lenguaje HTTP normales como en-US o es-ES.

6. Manejar errores mediante retry_strategy

Todos los errores son legibles por máquina.

{
  "error": true,
  "code": "AUTH_INSUFFICIENT_SCOPE",
  "message": "This key does not have the required scope.",
  "retry_strategy": "no_retry",
  "details": {
    "required_scope": "write:transactions"
  }
}

Utiliza retry_strategy para decidir qué hacer:

Consulta la sección de Gestión de errores para ver la matriz completa.

7. Elije los alcances antes de realizar el envío

No crees claves amplias por defecto. Comienza con el conjunto de ámbitos útiles más pequeño.

Puntos de partida típicos:

Habilitación y Gestión de Claves

Cómo crear, configurar y revocar claves de la API de Agentes.

Las claves de agente se administran mediante el panel del socio. Los administradores controlan qué socios pueden usar la API de Agentes, y los socios crean y revocan sus propias claves.

Requisitos Previos

Antes de que un socio pueda crear claves de agente:

• Indicador de característica habilitado — Agrega FEATURE_AGENT_API=true a tu archivo .env. La API de Agentes está desactivada de forma predeterminada.
• El administrador habilita la API de Agentes — El permiso de API de Agentes debe estar activado para el socio.
• El socio tiene al menos un club — La mayoría de los endpoints de agente operan en el contexto de un club.

Habilitar Acceso a la API de Agentes

Como Administrador:

• Navega hasta Socios en la barra lateral del administrador.
• Haz clic en el nombre del socio para editar su cuenta.
• Cambia a la pestaña Permisos.
• Habilita el permiso de la API de Agentes.
• Opcionalmente, establece un Límite de Claves de Agente (cuántas claves puede crear este socio; -1 para ilimitado).
• Haz clic en Guardar.

Una vez habilitado, el socio verá Claves de Agente en Integraciones en su barra lateral.

Creación de una Clave

Como Socio:

• Navega a Integraciones → Claves de Agente en la barra lateral.
• Haz clic en Crear.
• Rellena:
  • Nombre — Una etiqueta descriptiva (por ejemplo, "Terminal POS Centro", "Integración Zapier").
  • Alcances — Elige un ajuste preestablecido de nivel de permiso.
  • Expira En — Fecha de caducidad opcional.
• Haz clic en Guardar.

Visualización Única de Clave

Después de guardar, un cuadro de diálogo muestra la clave completa:

rl_agent_a8f3k2m1x9v4b7n2p5q8r1t6w3y0z4d7f0h3j6l9m2o5r8u1w4z7c0e3...

Preajustes de Nivel de Permiso

Al crear una clave, eliges una de las siguientes preselecciones:

Después de la creación, los alcances no se pueden cambiar. Para usar diferentes alcances, crea una nueva clave.

Visualización de Claves

La lista de Claves de Agente muestra:

Revocación de una Clave

Para revocar una clave de inmediato:

• Navega a Integraciones → Claves de Agente.
• Encuentra la clave en la lista.
• Haz clic en Eliminar para quitarla permanentemente, o haz clic en Editar y desactiva el control de Activa (reversible).
• Confirma la acción.

Qué ocurre al revocar una clave:

• Todas las solicitudes que utilicen esa clave reciben de inmediato AUTH_KEY_REVOKED (401).
• El registro de la clave permanece en la base de datos para seguimiento de auditoría.
• Las entradas existentes del registro de actividad para esa clave se conservan.
• Cualquier integración que utilice esta clave debe actualizarse con una nueva clave.

Estrategia de Rotación de Claves

Para integraciones críticas en materia de seguridad, rota las claves periódicamente:

• Crea una nueva clave con los mismos alcances.
• Actualiza tu integración para usar la nueva clave.
• Verifica que la nueva clave funciona (llama a GET /api/agent/v1/health).
• Revoca la clave anterior.

Esto asegura que no haya tiempo de inactividad durante la rotación.

Claves de Miembro

Los miembros (clientes) también pueden crear claves de agente para acceder a sus propios datos desde aplicaciones externas e integraciones de billetera.

Creando una Clave de Miembro

• Inicia sesión en el panel del miembro.
• Abre el menú de usuario y haz clic en Claves de Agente.
• Haz clic en Crear.
• Elige un nombre y un preset de permiso.
• Copia la clave del cuadro de diálogo de visualización única.

Diferencias en las Claves de Miembro

Preajustes de Permiso de Miembro

Restricciones

• Los miembros anónimos no pueden crear claves — Solo los miembros verificados con una dirección de correo electrónico pueden acceder a la gestión de claves de agente.
• Expiración predeterminada de 90 días — Las claves de los miembros vencen tras 90 días de forma predeterminada. Los miembros pueden establecer una fecha personalizada, pero el sistema impone un valor predeterminado para la seguridad de la clave orientada al consumidor.

Límites

• Claves de socio: Los administradores pueden establecer cuántas claves puede crear cada socio a través del 'Límite de claves de agente' en Permisos de socio. Un valor de -1 indica ilimitado.
• Claves de miembro: Fijo a 3 claves por miembro. Esto no es configurable.

Lista de Verificación de Producción

Lista de verificación de seguridad de lanzamiento para integraciones de la API de Agentes, incluyendo idempotencia, reintentos, gestión de claves y reconciliación.

Utiliza esta lista de verificación antes de poner en producción un POS, un conector de comercio electrónico o una automatización.

Gestión de Claves

• Utiliza claves separadas por entorno. No compartas una clave entre desarrollo local, pruebas (staging) y producción.
• Utiliza claves separadas por superficie de integración cuando sea práctico. Una flota de terminales POS no debe compartir la misma clave que un trabajo de informes nocturno.
• Almacena las claves en variables de entorno o un gestor de secretos.
• Mantén las claves de socio solo en el lado del servidor. Nunca las expongas en código del navegador o aplicaciones móviles.
• Recuerda que las claves completas se muestran una vez y nunca son recuperables.
• Rota las claves creando primero el reemplazo, actualizando la integración y luego revocando la clave antigua.

Higiene de Alcances

• Empieza con el menor privilegio.
• Otorga alcances de escritura (write) solo para los recursos que la integración realmente muta.
• Utiliza claves de miembro para operaciones en la billetera del miembro y claves de socio para acciones comerciales propiedad del socio.
• Verifica los alcances finalmente otorgados llamando a GET /api/agent/v1/health.

Seguridad de Transacciones

Los flujos de compras y canjes no son idempotentes.

• POST /partner/transactions/purchase puede otorgar puntos más de una vez si vuelves a enviar el mismo pedido lógico.
• POST /partner/transactions/redeem puede deducir puntos más de una vez si vuelves a enviar el mismo canje lógico.

Práctica recomendada:

• Trata una respuesta exitosa confirmada como final.
• Compra devuelve 201; canje devuelve 200.
• Si obtienes un tiempo de espera agotado o una falla de red ambigua, reconcilia antes de volver a intentar.
• Rastrea tus propios identificadores de pedido externos o identificadores de canje.
• Pasa esos identificadores en el campo note donde sea compatible, para que la reconciliación sea posible más adelante.

Ejemplo:

POST /api/agent/v1/partner/transactions/purchase HTTP/1.1
Host: tu-dominio.com
Accept: application/json
Content-Type: application/json
X-Agent-Key: rl_agent_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0

{
  "card_id": "3598a5db-f008-477c-ac4d-5365c662ad62",
  "member_identifier": "customer@example.com",
  "purchase_amount": 24.50,
  "note": "Order #12345"
}

Notas y Reconciliación

Utiliza el campo note siempre que el endpoint lo admita.

Buenos valores:

• Order #12345
• POS ticket 98441
• Shopify order gid://shopify/Order/123456789
• Cashier session 2026-03-08-07

Esto es especialmente útil para:

• Reconciliación de compras
• Investigación de canje de recompensas
• Auditorías de ajustes de sellos
• Tickets de soporte

Paginación y Filtrado

No asumas que los endpoints de lista devuelven todos los registros en una sola respuesta.

• per_page por defecto es 25.
• per_page tiene un máximo de 100.
• Los filtros from y to de la lista de transacciones aceptan formato Y-m-d.

Ejemplo:

GET /api/agent/v1/partner/transactions?from=2026-03-01&to=2026-03-08&per_page=100 HTTP/1.1
Host: tu-dominio.com
Accept: application/json
X-Agent-Key: rl_agent_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0

Construye bucles de paginación explícitamente.

Manejo de Errores

Tu cliente debe ramificar la lógica basado en retry_strategy, no solo en el estado HTTP.

Pruebas requeridas antes del lanzamiento:

• Clave inválida
• Alcance incorrecto
• Rol incorrecto
• Recurso no encontrado
• Puntos o saldo insuficientes
• Límite de tasa excedido
• API de agentes del socio deshabilitada

Límites de Tasa

Cada respuesta incluye encabezados de límite de tasa:

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset

En caso de un 429 RATE_LIMITED, respeta el encabezado Retry-After. No bombardees la API después de recibir una respuesta de límite de tasa.

Monitoreo Operativo

• Registra los identificadores de solicitudes salientes y tus propias referencias de pedidos o tickets.
• Monitorea los Registros de Actividad en busca de comportamiento de automatización inesperado.
• Mantén una cola de "mensajes muertos" o cola de reintento para los errores de retroceso (backoff).
• Alerta sobre respuestas repetidas de AUTH_INVALID_KEY, AUTH_INSUFFICIENT_SCOPE y RATE_LIMITED.

Lista Final de Verificación de Lanzamiento

• Indicador de característica activado en el entorno correcto.
• Permiso de API de Agentes del socio activado donde se requiera.
• Tipo de clave correcto elegido.
• Alcances minimizados y verificados mediante /health.
• Lógica de reintento implementada.
• Flujos de compra y canje no idempotentes reconciliados por referencia externa.
• Notas rellenadas con identificadores externos donde esté soportado.
• Paginación implementada.
• Manejo del límite de tasa implementado.
• Ramas de error probadas.

Alcances y Permisos

Entendiendo la aplicación de alcances y lo que permite cada nivel de permiso.

Los alcances (scopes) definen lo que se le permite hacer a una clave de agente. Cada endpoint de agente verifica la clave de la solicitud en busca del alcance requerido antes de ejecutarse. Si la clave carece del alcance requerido, la solicitud es rechazada con un error HTTP 403.

Cómo Funcionan los Alcances

Cada clave lleva un arreglo de alcances asignados en el momento de su creación. Cuando una solicitud llega a un endpoint:

• El controlador verifica qué alcance(s) requiere el endpoint.
• Los alcances de la clave se comparan con el requisito.
• Si coincide cualquier alcance requerido, se concede el acceso (lógica OR).
• Si no coincide ningún alcance, se devuelve un error 403 AUTH_INSUFFICIENT_SCOPE.

Alcances Disponibles

Alcance de Lectura

El alcance read es un permiso de lectura global. Cualquier clave con read puede llamar a cualquier endpoint GET.

Alcances de Escritura

Los alcances de escritura son específicos del recurso. Una clave con write:transactions puede registrar compras pero no puede crear clubes.

Alcances de Escritura de Miembro

Las claves de miembro usan un conjunto separado de alcances de escritura:

Los alcances de escritura de miembro están auto-limitados — solo afectan los datos del propietario de la clave.

Súper Alcance

El alcance admin omite todas las verificaciones de alcance. Úsalo para claves que necesiten acceso sin restricciones.

Alcances de Administrador

Las claves de administrador tienen alcances a nivel de plataforma:

Jerarquía de Alcances

Los alcances siguen una jerarquía lógica:

Comportamientos importantes:

• Escritura implica lectura en ese recurso: Una clave con write:cards puede llamar a GET /partner/cards, pero no puede leer miembros u otros recursos.
• Admin otorga todo: El alcance admin actúa como un súper alcance para todo.
• Lectura no puede escribir: Una clave de solo lectura no puede crear, actualizar ni eliminar nada.
• Los alcances de escritura están aislados: write:clubs no puede leer recompensas, write:transactions no puede leer personal.

Ajustes Preestablecidos de Permiso

Al crear una clave en el panel, eliges desde presets que mapean arreglos de alcances:

Preajustes de Miembro

Preajustes de Administrador

Requisitos de Alcance por Endpoint

Clubes

Tarjetas de Fidelidad

Recompensas

Transacciones

Miembros

Tarjetas de Sellos

Cupones

Niveles

Personal

Perfil de Miembro

Saldo y Tarjetas de Miembro

Transacciones de Miembro

Recompensas de Miembro

Socios de Administrador

Miembros de Administrador

Analíticas de Administrador

Errores de Alcance

Cuando una clave carece del alcance requerido:

{
  "error": true,
  "code": "AUTH_INSUFFICIENT_SCOPE",
  "message": "This action requires the 'write:cards' scope.",
  "retry_strategy": "no_retry",
  "details": {
    "required_scope": "write:cards"
  }
}

El retry_strategy es no_retry — la clave no puede ganar alcances dinámicamente. En su lugar, crea una nueva clave con los alcances requeridos.

Endpoints de Socio

Referencia completa de endpoints para operaciones de agentes con alcance de socio.

Todos los endpoints de socio tienen el prefijo /api/agent/v1/partner y requieren una clave con alcance de socio (rl_agent_).

Patrones Comunes

Todos los endpoints de socio comparten estos comportamientos:

• Aislamiento multi-inquilino (Multi-tenant) — Una clave de socio solo puede acceder a los recursos creados por ese socio.
• Contratos de API canónicos — Las solicitudes se validan contra el esquema de agente en vivo, puertas de permisos y verificaciones de propiedad.
• Solicitud/respuesta JSON — Envía y recibe application/json.
• Paginación — Los endpoints de lista admiten los parámetros de consulta ?page=1&per_page=25.

Chequeo de Salud

Chequeo de Salud

Disponible para todos los roles de clave. Devuelve la identidad de la clave, los alcances y la información del propietario. Úsalo para verificar que tu clave funciona antes de realizar otras solicitudes.

Alcance: No se requiere alcance.

Clubes

Los clubes organizan el personal y las operaciones de un socio. La mayoría de los recursos (tarjetas, personal) pertenecen a un club.

Listar Clubes

Alcance: read o write:clubs

Obtener Club

Alcance: read o write:clubs

Crear Club

Alcance: write:clubs

{
  "name": "Downtown Location",
  "description": "Our flagship store"
}

Actualizar Club

Alcance: write:clubs

Eliminar Club

Alcance: write:clubs

Tarjetas de Fidelidad

Las tarjetas de fidelidad definen las reglas para ganar puntos y las recompensas asociadas.

Listar Tarjetas

Alcance: read o write:cards

Obtener Tarjeta

Alcance: read o write:cards

Crear Tarjeta

Alcance: write:cards

Actualizar Tarjeta

Alcance: write:cards

Eliminar Tarjeta

Alcance: write:cards

Recompensas

Las recompensas son para lo que ahorran los miembros. Cada recompensa pertenece a una tarjeta de fidelidad.

Listar Recompensas

Alcance: read o write:rewards

Obtener Recompensa

Alcance: read o write:rewards

Crear Recompensa

Alcance: write:rewards

Actualizar Recompensa

Alcance: write:rewards

Eliminar Recompensa

Alcance: write:rewards

Transacciones

Las transacciones manejan el flujo principal de ganar y quemar (canjear). Estos son los endpoints más críticos para las integraciones POS.

Listar Transacciones

Alcance: read o write:transactions

Lista las transacciones de la cuenta de socio, las más recientes primero. Acepta los siguientes parámetros de consulta:

Registrar una Compra (Otorgar Puntos)

Alcance: write:transactions

{
  "card_id": "uuid-of-loyalty-card",
  "member_identifier": "member@example.com",
  "purchase_amount": 24.50,
  "staff_id": "uuid-of-staff-member",
  "note": "Coffee and pastry"
}

Identificación de miembro — El campo member_identifier acepta múltiples formatos:

• UUID del Miembro
• Dirección de correo electrónico
• Número de miembro
• Identificador único

El sistema resuelve el miembro automáticamente. Esta flexibilidad es fundamental para los sistemas POS que pueden tener solo el correo electrónico de un cliente o un número de lealtad.

El staff_id es opcional — atribuye la transacción a un miembro específico del personal para los informes. Sin él, la transacción se atribuye al "Sistema".

Canjear una Recompensa (Deducir Puntos)

Alcance: write:rewards

{
  "card_id": "uuid-of-loyalty-card",
  "reward_id": "uuid-of-reward",
  "member_identifier": "member@example.com",
  "staff_id": "uuid-of-staff-member"
}

El staff_id es opcional. Sin él, el canje se atribuye al "Sistema" — esto permite integraciones sin interfaz (headless como Shopify o WooCommerce) que no tienen cuentas de personal.

Las respuestas exitosas de canje incluyen transaction_id, points_deducted, member_balance, new_balance, reward_id, reward, card_id, y member_id.

Miembros

Los endpoints de miembro son de solo lectura para las claves de socio. Los miembros no se pueden crear ni modificar a través de la API de agente — ellos se registran solos a través de la plataforma.

Listar Miembros

Alcance: read

Obtener Miembro

Alcance: read

Obtener Saldo de Miembro

Alcance: read

Devuelve el saldo de puntos del miembro para una tarjeta de fidelidad específica.

Las respuestas de lista/detalle de miembros exponen solo la carga de datos pública endurecida: id, unique_identifier, name, email, locale, currency, time_zone, last_login_at, created_at, updated_at, avatar, is_anonymous.

Tarjetas de Sellos

Las tarjetas de sellos funcionan como tarjetas perforadas digitales. Los miembros coleccionan sellos y ganan una recompensa cuando la tarjeta está completa.

Listar Tarjetas de Sellos

Alcance: read o write:stamps

Obtener Tarjeta de Sellos

Alcance: read o write:stamps

Crear Tarjeta de Sellos

Alcance: write:stamps

Actualizar Tarjeta de Sellos

Alcance: write:stamps

Eliminar Tarjeta de Sellos

Alcance: write:stamps

Añadir Sellos

Alcance: write:stamps

Otorgar sellos a un miembro en una tarjeta de sellos específica.

Canjear Recompensa de Sellos

Alcance: write:stamps

Canjear la recompensa de la tarjeta de sellos cuando un miembro ha coleccionado todos los sellos requeridos.

Usar campos canónicos de creación/actualización: stamps_expire_days y requires_physical_claim.

Cupones

Los cupones proporcionan descuentos de valor instantáneo a través de códigos promocionales.

Listar Cupones

Alcance: read o write:vouchers

Obtener Cupón

Alcance: read o write:vouchers

Crear Cupón

Alcance: write:vouchers

Actualizar Cupón

Alcance: write:vouchers

Eliminar Cupón

Alcance: write:vouchers

Validar Código de Cupón

Alcance: write:vouchers

Comprueba si un código de cupón es válido y se puede canjear sin canjearlo realmente.

Usa campos canónicos de cupones: type, value, valid_from, valid_until, max_uses_total, y max_uses_per_member. El identificador code es opcional en la creación y se genera automáticamente cuando se omite.

Validar cuerpo de la solicitud (request body):

• code
• member_identifier
• club_id
• order_amount (opcional, unidades menores)

Validar campos de respuesta:

• valid, voucher_id, code, name, type, value, currency, discount_amount, capped, original_amount, final_amount, times_used, remaining_uses, valid_until

Canjear Cupón

Alcance: write:vouchers

Cuerpo de solicitud de canje (Redeem request body):

• member_identifier
• order_amount (opcional, unidades menores)
• order_reference (opcional)

Campos de respuesta de canje:

• voucher_id, code, type, member_id, discount_amount, points_awarded, remaining_uses, redemption_id

Niveles

Los niveles de membresía definen niveles VIP con multiplicadores y beneficios.

Listar Niveles

Alcance: read o write:tiers

Obtener Nivel

Alcance: read o write:tiers

Crear Nivel

Alcance: write:tiers

Usa el campo canónico de umbral de nivel: points_threshold.

Actualizar Nivel

Alcance: write:tiers

Eliminar Nivel

Alcance: write:tiers

Personal

Administra a los miembros del personal que procesan transacciones en las ubicaciones de los socios.

Listar Personal

Alcance: read o write:staff

Obtener Miembro del Personal

Alcance: read o write:staff

Crear Miembro del Personal

Alcance: write:staff

Usa el campo canónico de asignación de personal: club_id.

Las respuestas de lista/detalle del personal exponen: id, club_id, club_name, name, email, locale, time_zone, number_of_times_logged_in, last_login_at, created_at, updated_at, avatar.

Actualizar Miembro del Personal

Alcance: write:staff

Eliminar Miembro del Personal

Alcance: write:staff

Manejo de Errores

Entendiendo las respuestas de error estructuradas y estrategias de reintento.

Cada respuesta de la API de Agente sigue una estructura predecible. Las respuestas de éxito y de error usan el mismo formato de envoltura, haciéndolas fáciles de analizar programáticamente — crítico para agentes de inteligencia artificial y herramientas de automatización.

Envoltura de Respuesta

Respuesta Exitosa

{
  "error": false,
  "data": {
    "id": "9e1a...",
    "name": "Downtown Club"
  }
}

Las respuestas de listas paginadas incluyen metadatos de paginación:

{
  "error": false,
  "data": [...],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total": 42
  }
}

Todas las respuestas incluyen encabezados de límite de tasa:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1741260060

Respuesta de Error

{
  "error": true,
  "code": "VALIDATION_FAILED",
  "message": "The request data did not pass validation.",
  "retry_strategy": "fix_request",
  "details": {
    "errors": {
      "card_id": ["The card_id field is required."],
      "purchase_amount": ["The purchase_amount must be at least 0.01."]
    }
  }
}

Campos de Error

Estrategias de Reintento

El campo retry_strategy le dice a los agentes de IA y herramientas de automatización cómo manejar el error:

Ejemplos de Estrategias de Reintento

no_retry — No vuelvas a intentar. La solicitud está mal.

{
  "code": "AUTH_INVALID_KEY",
  "retry_strategy": "no_retry"
}

fix_request — Rectifica los datos y vuelve a intentar.

{
  "code": "VALIDATION_FAILED",
  "retry_strategy": "fix_request",
  "details": {
    "errors": {
      "card_id": ["The card_id field is required."]
    }
  }
}

backoff — Espera y reintenta con retroceso exponencial.

{
  "code": "INTERNAL_ERROR",
  "retry_strategy": "backoff"
}

Práctica recomendada de backoff: 1s → 2s → 4s → 8s → 16s → stop.

contact_support — Se requiere intervención humana.

{
  "code": "FEATURE_DISABLED",
  "retry_strategy": "contact_support",
  "details": {
    "permission": "loyalty_cards_permission"
  }
}

Referencia de Códigos de Error

Errores de Autenticación (401/403)

Errores de Validación (422)

Errores de Recurso (404)

Errores de Permisos (403)

Errores de Servidor (500)

Limitación de Tasa (429)

La respuesta 429 incluye detalles y encabezados adicionales:

Retry-After: 23
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1741260023

Revisa la sección de Autenticación — Límites de Tasa para detalles completos.

Para Desarrolladores de Agentes de IA

Si estás construyendo un agente de IA que consume esta API, aquí se explica cómo manejar los errores programáticamente:

response = call_agent_api(endpoint, data)

if response["error"]:
    match response["retry_strategy"]:
        case "no_retry":
            log_error(response["code"], response["message"])
            raise PermanentError(response["message"])
        case "fix_request":
            fix_fields(response["details"]["errors"])
            retry_with_fixed_data()
        case "backoff":
            wait_exponential(attempt)
            retry()
        case "contact_support":
            notify_human(response["message"])
            raise NeedsHumanIntervention(response["message"])

Endpoints de Miembro

Referencia completa de endpoints para operaciones de agente con alcance de miembro.

Todos los endpoints de miembro tienen el prefijo /api/agent/v1/member y requieren una clave con alcance de miembro (rl_member_).

Patrones Comunes

Todos los endpoints de miembro comparten estos comportamientos:

• Alcance propio — Una clave de miembro solo puede acceder a los datos de su propio titular. No es posible el acceso cruzado entre miembros.
• Principalmente de solo lectura — Los miembros pueden ver su saldo, tarjetas, transacciones y recompensas. El acceso de escritura se limita a las actualizaciones de perfil y a los reclamos de recompensas.
• Solicitud/respuesta JSON — Envía y recibe application/json.
• Paginación — Los endpoints de lista admiten los parámetros de consulta ?page=1&per_page=25.

Diferencias Clave con las Claves de Socio

Perfil

Obtener Perfil

Alcance: read

Devuelve la propia información de perfil del miembro.

{
  "data": {
    "id": "member-uuid",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "locale": "en_US",
    "unique_identifier": "454-925-184-086",
    "avatar": null,
    "is_anonymous": false,
    "has_interacted": true,
    "first_interaction_at": "2026-01-15T10:30:00+00:00",
    "created_at": "2026-01-01T00:00:00+00:00"
  }
}

Actualizar Perfil

Alcance: write:profile

Solo el nombre (name) y el idioma (locale) pueden actualizarse mediante la API. Los cambios de correo electrónico requieren el flujo de autenticación completo mediante el panel del miembro.

{
  "name": "Jane Updated",
  "locale": "fr_FR"
}

Saldo y Tarjetas

Resumen de Billetera (Todos los Saldos)

Alcance: read

Devuelve los saldos de todas las tarjetas de fidelidad inscritas en una sola llamada. Este es el endpoint principal para los widgets de "resumen de billetera" (wallet overview) en tiendas web.

Las respuestas dirigidas al miembro omiten intencionalmente la información del club. Los clubes son estructuras internas de enrutamiento y acceso del personal; los miembros interactúan directamente con las tarjetas.

{
  "data": [
    {
      "card_id": "card-uuid-1",
      "card_title": "Coffee Rewards",
      "balance": 250,
      "currency": "points"
    },
    {
      "card_id": "card-uuid-2",
      "card_title": "VIP Club",
      "balance": 1200,
      "currency": "points"
    }
  ]
}

Listar Tarjetas

Alcance: read

Lista paginada de tarjetas inscritas con mayor nivel de detalle que /balance, incluyendo saldos específicos para el miembro y campos de presentación.

Obtener Tarjeta

Alcance: read

Devuelve los detalles y el saldo del miembro para una sola tarjeta. Devuelve un error 404 si el miembro no está inscrito en dicha tarjeta.

Historial de Transacciones

Todas las Transacciones

Alcance: read

Devuelve el historial completo de transacciones del miembro en todas las tarjetas. Ordenado por el más reciente primero y también paginado.

Transacciones por Tarjeta

Alcance: read

Filtra el historial de transacciones de una tarjeta específica. Devuelve un error 404 si el miembro no está inscrito en esta tarjeta.

Recompensas

Navegar por Recompensas Disponibles

Alcance: read

Enumera todas las recompensas disponibles en las tarjetas inscritas del miembro. Cada recompensa incluye:

• Si el miembro puede costearla (según su saldo actual).
• El mejor saldo del miembro entre las tarjetas vinculadas.
• El coste en puntos de la recompensa.

Esto permite crear mensajes como "Necesitas X puntos más" en las interfaces de las webshops.

Reclamar una Recompensa

Alcance: write:redeem

Envía una solicitud de reclamo de recompensa. Esto no deduce directamente los puntos — el personal debe confirmar el canje mediante el panel de socios o la API de agente de socio.

Esto preserva el flujo de la plataforma según el cual "el personal confirma el canje", lo cual previene el fraude de autoservicio en ubicaciones físicas.

Respuesta de Éxito (200):

{
  "data": {
    "status": "claim_submitted",
    "reward_id": "reward-uuid",
    "reward_title": "Free Coffee",
    "points_required": 100,
    "card_id": "card-uuid",
    "card_title": "Coffee Rewards",
    "current_balance": 250,
    "message": "Your claim has been submitted. A staff member will confirm it."
  }
}

Saldo Insuficiente (422):

{
  "error": true,
  "code": "INSUFFICIENT_BALANCE",
  "message": "Not enough points. You have 50, but this reward requires 100.",
  "details": {
    "balance": 50,
    "required": 100,
    "deficit": 50
  }
}

Descubrimiento

Los miembros descubren tarjetas de dos formas:

• Navegar por la página inicial — Los recursos activos cuyo ajuste is_visible_by_default está habilitado aparecen de forma pública.
• Códigos QR / enlaces compartidos — Se puede hallar cualquier tarjeta de fidelidad, tarjeta de sellos o cupón escaneando un código QR o abriendo un enlace directo.

Navegar Tarjetas Descubribles

Alcance: read

Devuelve todas las tarjetas (de fidelidad, sellos y cupones) actualmente visibles en la página de inicio. Incluye el estado de inscripción del miembro y el saldo de cada tarjeta que sigue.

{
  "data": {
    "cards": [
      {
        "type": "loyalty_card",
        "id": "card-uuid",
        "name": "Barista Club",
        "title": "Coffee Rewards",
        "description": "Earn points on every cup",
        "currency": "USD",
        "bg_color": "#C49A00",
        "text_color": "#ffffff",
        "is_following": true,
        "balance": 37519,
        "rewards_count": 4
      }
    ],
...

Resolver URL o Identificador

Alcance: read

Resuelve una URL de tarjeta (desde un escaneo QR o enlace) o identificador en detalles completos. Endpoint principal para flujos de escaneo usando códigos QR.

Formatos de entrada soportados:

Petición (URL):

{
  "url": "https://example.com/en-us/card/019cc3a5-51cb-7315-97e1-69147399f94d"
}

O mediante código identificador:

{
  "identifier": "344-319-665-971"
}

Seguir una Tarjeta

Alcance: write:profile

Guarda una tarjeta de fidelidad de manera segura a la colección de "Mis Tarjetas" del miembro. Idempotente (seguir tarjetas que ya sigues es una operación sin efecto).

{
  "card_id": "card-uuid"
}

Dejar de Seguir una Tarjeta

Alcance: write:profile

Remueve una tarjeta de la colección de "Mis Tarjetas".

{
  "card_id": "card-uuid"
}

Preajustes de Alcance

Las claves de miembro usan preajustes de alcance simplificados:

Para Integraciones de Tiendas Web

La API de agente de miembro se diseñó para el flujo de punto de venta (POS) y tiendas online (eCommerce):

• Al iniciar sesión: Usa GET /member/balance para mostrar el resumen de los saldos generales.
• En la página de producto: Usa GET /member/rewards para promocionar mensajes como "Usa 100 puntos y obtén 10% de descuento".
• En la caja: Combina procesos con la API de socio para otorgar los correspondientes puntos al confirmar una compra final.
• Después de la compra: Muestra el saldo actualizado y validado.

Revisa la sección de Autenticación sobre cómo usar ambas claves de la manera ideal y combinada en tus proyectos.

Endpoints de Administrador

Administración de la plataforma mediante la API de Agente — gestión de socios, búsqueda de miembros y analíticas.

Las claves de agente de administrador otorgan a los administradores de la plataforma acceso programático para gestionar socios, ver datos de miembros en toda la plataforma y obtener analíticas — ideal para integraciones CRM, paneles de facturación SaaS y herramientas de monitoreo.

URL Base

Todos los endpoints requieren una clave de agente de tipo administrador (rl_admin_***).

Socios

Listar Socios

Alcance: read:partners

Respuesta:

{
  "error": false,
  "data": [
    {
      "id": "uuid",
      "name": "Coffee Corner",
      "email": "partner@example.com",
      "locale": "en_US",
      "currency": "USD",
      "time_zone": "America/New_York",
      "is_active": true,
      "avatar": null,
      "created_at": "2026-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 25,
    "total": 72
  }
}

Obtener Socio

Alcance: read:partners

Devuelve el perfil del socio junto con sus permisos y conteos de uso.

{
  "error": false,
  "data": {
    "id": "uuid",
    "name": "Coffee Corner",
    "email": "partner@example.com",
    "is_active": true,
    "permissions": {
      "loyalty_cards_permission": true,
      "loyalty_cards_limit": -1,
      "stamp_cards_permission": true,
      "stamp_cards_limit": -1,
      "vouchers_permission": true,
      "agent_api_permission": true,
      "agent_keys_limit": 10
    },
    "usage": {
      "loyalty_cards": 3,
      "stamp_cards": 1,
      "vouchers": 5,
      "rewards": 8,
      "staff_members": 2
    }
  }
}

Actualizar Permisos

Alcance: write:partners

Actualiza los permisos de funciones y los límites de uso de un socio. Ideal para cambios de nivel de facturación (tiers) de SaaS.

Petición (JSON):

{
  "agent_api_permission": true,
  "agent_keys_limit": 10,
  "loyalty_cards_limit": 5
}

Activar / Desactivar Socio

Alcance: write:partners

Alterna la marca is_active del socio. Cuando se desactiva, todas las claves de agente del socio se vuelven inválidas (el middleware de autenticación verifica la propiedad de estado activo).

Miembros (Solo Lectura)

El acceso a miembros por parte del administrador es estrictamente de solo lectura. El ciclo de vida de los miembros se gestiona a través de transacciones de socios (inscripción automática) o el autoservicio del propio miembro.

Listar Miembros

Alcance: read:members

Obtener Miembro

Alcance: read:members

Devuelve el perfil del miembro junto con los saldos de todas sus tarjetas.

{
  "error": false,
  "data": {
    "id": "uuid",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "unique_identifier": "846-346-383-611",
    "is_active": true,
    "is_anonymous": false,
    "card_balances": [
      {
        "card_id": "uuid",
        "card_title": "Coffee Rewards",
        "club_name": "General",
        "balance": 250,
        "currency": "USD"
      }
    ]
  }
}

Analíticas

Resumen de la Plataforma

Alcance: read:analytics

Devuelve métricas globales agregadas de la plataforma.

{
  "error": false,
  "data": {
    "total_partners": 45,
    "active_partners": 42,
    "total_members": 12500,
    "total_cards": 38,
    "total_stamp_cards": 15,
    "total_vouchers": 92,
    "transactions_today": 340,
    "transactions_this_week": 2100,
    "transactions_this_month": 8500
  }
}

Métricas por Socio

Alcance: read:analytics

Desglose de uso detallado para un socio específico.

{
  "error": false,
  "data": {
    "partner_id": "uuid",
    "partner_name": "Coffee Corner",
    "is_active": true,
    "loyalty_cards": 3,
    "stamp_cards": 1,
    "vouchers": 5,
    "rewards": 8,
    "staff_members": 2,
    "total_transactions": 15420,
    "transactions_today": 45,
    "total_members_enrolled": 1250
  }
}

Alcances de Administrador

Recetas de Integración

Sincronización CRM

# Sincronizar lista de socios al CRM
GET /api/agent/v1/admin/partners?is_active=true

# Enviar métricas a un panel de monitoreo
GET /api/agent/v1/admin/analytics/overview

Cambio de Nivel de Facturación SaaS

# Actualizar el socio al nivel premium
PATCH /api/agent/v1/admin/partners/{id}/permissions
{
  "loyalty_cards_limit": -1,
  "stamp_cards_limit": -1,
  "vouchers_limit": -1,
  "agent_api_permission": true,
  "agent_keys_limit": 20
}

Búsqueda de Miembros

# Buscar a un miembro en todos los socios
GET /api/agent/v1/admin/members?search=jane@example.com

# Obtener los saldos de sus tarjetas