La API pública de JeriCommerce permite que tus propios sistemas trabajen con tu programa de fidelización. Está disponible para todos los programas: solo necesitas una clave de API.
La API sirve para dos tipos de tareas:
- Acciones de fidelización: dar puntos, asignar cupones, canjear recompensas, enviar notificaciones push al wallet y consultar datos de clientes. Cada acción está documentada en Automatizaciones, con una pestaña API junto a las opciones de Shopify Flow y Klaviyo, para que puedas comparar canales y construir tu solicitud.
- Endpoints de referencia: los que aparecen en esta página, como el catálogo de recompensas o la vista previa del saldo.
Si tu propio sistema debe ser la fuente de verdad de clientes y saldos, y recibir todos los eventos de los clientes, configura mejor la integración API personalizada. Hay que activarla en JeriCommerce y funciona junto con esta API.
URL base ¶
Todos los endpoints cuelgan de tu programa:
https://api.jericommerce.com/v1/programs/{program_slug}
Sustituye {program_slug} por el slug o el ID de tu programa. Sirven ambos. Los encontrarás en JeriCommerce, en Settings > Technical > Program Information.
Autenticación ¶
Envía tu clave de API en el encabezado api-key en cada solicitud. Las claves pertenecen a un solo programa y solo funcionan con ese programa. Consulta Autenticación mediante la API para crear una.
Convenciones de las solicitudes ¶
- Los cuerpos de las solicitudes y de las respuestas son JSON. Envía
Content-Type: application/json. - Los clientes se identifican por su correo electrónico. El correo no distingue entre mayúsculas y minúsculas.
- La mayoría de los endpoints de escritura aceptan una matriz de elementos, así que puedes actuar sobre muchos clientes en una sola llamada. El límite es de 100 elementos por solicitud, o 250 cuando sincronizas clientes o información de fidelización mediante la integración API personalizada.
Endpoints en cola ¶
Increase balance, Decrease balance, Redeem a reward, Assign a coupon y Send a push notification ponen cada elemento en una cola y responden 201 de inmediato. Un 201 significa que la solicitud era válida, no que cada elemento se haya procesado bien. Si un elemento falla más tarde (por ejemplo, porque el cliente no existe o no tiene puntos suficientes), la API no te lo comunica. Para confirmar el resultado, escucha el webhook de eventos o consulta al cliente con Obtener los datos de un cliente.
Los demás endpoints se ejecutan al momento y devuelven el resultado o un error en la respuesta.
Errores ¶
Los errores devuelven un código de estado HTTP y un cuerpo JSON. El campo message contiene un código que puedes usar en tu integración:
{
"statusCode": 404,
"message": "CUSTOMER_NOT_FOUND",
"path": "/v1/programs/your-program/customers/someone@example.com",
"timestamp": "2026-10-11T09:00:00.000Z"
}
Cuando el cuerpo de la solicitud no es válido, el estado es 400 y message es una lista de los campos que no han pasado la validación.
| Estado | Significado |
|---|---|
400 |
La solicitud no es válida: falta un campo, es incorrecto o hay demasiados elementos. |
403 |
Falta la clave de API, no pertenece a este programa o la integración API no está activa. |
404 |
El programa o el cliente no existe. |
412 |
Al cliente le falta algo que necesita la acción, como una tarjeta de fidelización. |
Endpoints ¶
| Endpoint | Qué hace |
|---|---|
| Obtener los datos de un cliente | Consulta el perfil, el saldo y el nivel de un cliente. |
| Aumentar y reducir el saldo | Suma o resta puntos. |
| Ejecutar un flujo de acumulación personalizado | Da puntos mediante una de tus formas personalizadas de obtener puntos. |
| Canjear una recompensa | Cambia los puntos de un cliente por una recompensa. |
| Asignar un cupón | Da un cupón a un cliente. |
| Enviar una notificación push | Envía una notificación push al wallet de un cliente. |
| Obtener un enlace de descarga | Construye un enlace de descarga de la tarjeta de fidelización. |
| Balance preview | Calcula los puntos que daría el importe de un pedido. |
| List rewards | Obtiene el catálogo de recompensas del programa. |
| Tokens de cliente | Crea tokens para enlaces de descarga y enlaces de sesión de Customer App. |
La integración API personalizada añade endpoints para sincronizar clientes e información de fidelización, además del webhook de eventos.