Toda solicitud a la API debe incluir tu clave de API en el encabezado api-key. Si falta la clave, o no pertenece al programa de la URL, la API responde 403.
Cada clave pertenece a un solo programa. Puedes crear varias claves, por ejemplo una por cada sistema que se conecta a JeriCommerce, dar a cada una solo el acceso que necesita y eliminar cualquiera sin afectar a las demás.
Obtén una clave de API ¶
Para crear una clave, ve a Settings > Technical > API keys y haz clic en Add API key. Se abre una página con estos ajustes.

Ponle un nombre
Escribe un nombre en Name, por ejemplo el sistema que la usará.
Elige cuándo caduca
En Expiration, elige 15 minutes, 1 hour, 1 day, 7 days, 30 days o Never. Las claves nuevas empiezan en Never. El tiempo cuenta desde que guardas.
Elige a qué puede acceder
Las claves nuevas tienen marcado Restrict key. En Permissions, marca al menos una opción. La tabla de más abajo indica qué permite cada una.
Limita las direcciones IP, si quieres
Marca Restrict by IP para aceptar solo solicitudes de ciertas direcciones. Escribe una en IP address or CIDR range, por ejemplo 203.0.113.7 o 203.0.113.0/24, y haz clic en Add. Puedes añadir hasta 100 entradas, IPv4 o IPv6.
Guarda y copia la clave
Haz clic en Save. El cuadro de diálogo API key created muestra la clave. Cópiala y guárdala en un lugar seguro, porque no podrás volver a verla.
Si desmarcas Restrict key, la clave puede llamar a toda la API y una filtración es mucho más arriesgada. Déjalo marcado salvo que un sistema necesite de verdad acceso completo.
Incluye el token en las solicitudes a la API ¶
Para acceder a los endpoints, usa como valor del encabezado api-key la clave que obtuviste en el paso anterior.
Este es un ejemplo con cURL que consulta un cliente:
curl --request GET \
--url https://api.jericommerce.com/v1/programs/{program_slug}/customers/customer@example.com \
--header 'api-key: {{ apiKey }}'
Guarda la clave en tu servidor. Cualquiera que la tenga puede modificar los datos de tus clientes, así que no la pongas nunca en una web, en una app ni en ningún código que se ejecute en el dispositivo del cliente.
Los endpoints Balance preview y List rewards son públicos y funcionan sin clave.
Qué permite cada permiso ¶
Una clave restringida solo puede hacer lo que marques en Permissions. Los webhooks de Klaviyo también son llamadas a la API, así que su clave necesita el permiso de esa acción.
| Permiso | Qué puede hacer la clave |
|---|---|
| Customers | Consultar los datos del cliente |
| Customer tokens | Obtener un enlace de descarga y tokens de cliente |
| Balance | Aumentar y reducir el saldo |
| Coupons and rewards | Asignar un cupón y canjear una recompensa |
| Campaigns | Enviar una Gift Card y asignar campañas |
| Push | Enviar una notificación push |
| Earning flows | Ejecutar un flujo personalizado para ganar puntos |
| Subscriptions | Crear o cancelar la suscripción del programa a JeriCommerce |
| API integration | Sincronizar clientes e información de fidelización con la Custom API Integration |
| VTAP | Conectar un lector NFC VTAP |
| MCP | Usar esta clave con el MCP de JeriCommerce: No access, Read o Write. Write incluye la lectura |
Edita una clave ¶
En Settings > Technical > API keys, haz clic en los tres puntos de una clave y elige Edit API key. Puedes cambiar todo menos el valor de la clave.
- Expiration ofrece Don't change cuando la clave tiene fecha de caducidad, para que guardar otro ajuste no la mueva.
- Status, en la columna lateral, detiene una clave cuando lo pones en Inactive. Vuelve a ponerlo en Active para reactivarla.
- Delete API key, en el mismo menú, elimina la clave. Las aplicaciones que la usan dejarán de funcionar.
La lista muestra una insignia en cada clave: Active, Inactive o Expired. Las claves creadas antes de estos ajustes no tienen restricciones ni caducidad, y muestran Unrestricted hasta que las restrinjas.
Errores de clave de API ¶
Estos errores llegan en el campo message de la respuesta.
| Estado | message |
Qué significa |
|---|---|---|
401 |
API_KEY_INACTIVE |
La clave no está activa. Comprueba su Status. |
401 |
API_KEY_EXPIRED |
Ha pasado la fecha de Expiration de la clave. |
403 |
API_KEY_IP_NOT_ALLOWED |
La solicitud llega desde una dirección fuera de Restrict by IP. |
403 |
API_KEY_PERMISSION_DENIED |
La clave no tiene el permiso para esta solicitud. |