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.

Página Add API key con Name, Expiration, Restrict key, Permissions, Restrict by IP y Status
La página Add API key, con Restrict key marcado
1

Ponle un nombre

Escribe un nombre en Name, por ejemplo el sistema que la usará.

2

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.

3

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.

4

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.

5

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.