Saltar al contenido principal

Desarrolladores

Esta sección es para quien programa la integración de una marca o agencia: un TPV, una tienda online, un CRM o una web propia.

Qué puedes integrar​

Quiero…UsaPágina
Consultar socios y movimientos de puntos desde mi TPV o backendAPI pública /api/v1API pública
Crear y administrar programas, niveles, campañas, recompensas y cupones por APIAPI de gestiónAPI de gestión
Obtener tokens de corta duración en lugar de enviar la claveOAuth2 client credentialsOAuth2
Automatizar tareas del panel con una claveÁmbitos de administraciónÁmbitos de administración
Recibir un aviso en mi sistema cuando pasa algo en el programaWebhooks salientesWebhooks
Recibir los eventos en mi cola SQS o en un fichero diario en mi bucketCola SQS y export S3Eventos a tu cola o bucket
Desarrollar sin enviar mensajes ni mover dinero realesModo pruebas y claves mk_test_Modo pruebas
Probar la API desde PostmanColección PostmanColección Postman
Construir mi propia landing o portal con JavaScriptSDK de JavaScriptSDK JavaScript
Mostrar una campaña dentro de mi web y leer su rankingEmbed y ranking públicoEmbed de campaña
Publicar un juego HTML5 propio en el portal del socioJuegos externosInicio rápido

Autenticación con clave API​

Las llamadas a /api/v1 van con una clave API de tu cuenta. Se envía en la cabecera Authorization:

Authorization: Bearer mk_xxxxxxxxxxxxxxxx

Las claves solo existen en cuentas de cliente: una clave de la cuenta anfitriona recibe 403.

Si prefieres no enviar la clave en cada llamada, cámbiala por un token de corta duración con OAuth2.

Crear una clave​

  1. Entra en Administración › Claves API. Necesitas el permiso Claves API (Pages.Administration.ApiKeys).
  2. Pulsa Crear nueva clave de API.
  3. Rellena Nombre, Descripción y, si quieres, la fecha de caducidad (déjala vacía para que no caduque).
  4. Ajusta Límite de peticiones por hora. Por defecto son 1000.
  5. Opcional: limita IPs permitidas y Orígenes Permitidos (vacíos = cualquiera).
  6. Pulsa Guardar.

Diálogo con la clave de API recién creada, con el valor enmascarado

Copia la clave ahora

La clave completa solo se muestra una vez, al crearla. Si la pierdes, usa Regenerar: la anterior deja de funcionar al instante.

Ámbitos (scopes)​

La API comprueba estos ámbitos. Una clave sin ámbitos tiene acceso completo.

ÁmbitoPermite
readBuscar socios, saldos, historial y validar cupones
transactions:writeRegistrar compras, acciones, canjes y ajustes de puntos
coupons:writeCanjear cupones en caja
Ámbitos en el formulario

El selector Ámbitos del formulario ofrece hoy otros valores (documents:read, credits:write…). La API pública solo reconoce los tres de la tabla: con una clave que lleve solo esos otros valores, cada llamada devuelve 403. Si no necesitas limitar la clave, deja Ámbitos vacío.

Los ámbitos de la API de gestión (programs:*, campaigns:*, rewards:*, coupons:read, coupons:manage, raffles:read) y los de administración (admin:*) no los recibe una clave sin ámbitos: hay que concederlos expresamente, y el formulario tampoco los ofrece (se asignan con la API de administración).

Límites​

  • Cada clave tiene topes por ráfaga (por segundo), por minuto y por hora, además de la cuota mensual de API de tu cuenta. Al superar cualquiera recibes 429 con Retry-After: los segundos hasta que se reinicia la ventana que rechazó la petición (no siempre una hora).
  • Los errores devuelven application/problem+json con un code estable (y, por compatibilidad, error con el texto).

Entornos​

Usa la misma clave y la misma ruta en cada entorno; solo cambia la dirección base. Pide a tu administrador la dirección de tu plataforma y no la escribas fija en el código.

Siguientes pasos​