Usar el SDK de JavaScript

El SDK es un cliente ligero para el navegador y Node. Con él conectas tu propia landing o web a una campaña, al portal del socio o a la API pública sin escribir las llamadas HTTP.

Antes de empezar

• Una campaña con su identificador de URL (slug) si vas a participar desde una landing.
• Una clave API solo para llamadas desde tu servidor.
• Tu dominio en los Orígenes Permitidos de la clave o en la configuración de CORS de la plataforma.

1. Instalar el SDK

Con una etiqueta script, desde tu plataforma:

<script src="https://<tu-plataforma>/sdk/incentia.js"></script>

O como paquete, si lo has recibido de IncentIA (@incentia/sdk, con tipos TypeScript):

import { IncentIA } from '@incentia/sdk';

2. Crear el cliente

const ia = new IncentIA({ baseUrl: 'https://<tu-plataforma>' });

Opción	Para qué
baseUrl	Obligatoria. Dirección de tu plataforma
apiKey	Clave mk_..., solo para servidor
programId	Programa por defecto en las operaciones de socio
onTokenExpired	Función a la que se llama si el token del socio caduca (401)

No publiques tu clave API en el navegador

Cualquiera puede leer el código de tu web. Usa apiKey solo en tu servidor. Las landings usan ia.campaigns y ia.auth, que no necesitan clave.

3. Participar en una campaña desde tu landing

<script>
const ia = new IncentIA({ baseUrl: 'https://<tu-plataforma>' });

ia.campaigns.getStatus('verano-2026').then(data => {
  document.getElementById('titulo').textContent = data.campaign.name;
});

document.getElementById('form').onsubmit = async (e) => {
  e.preventDefault();
  const result = await ia.campaigns.register('verano-2026', {
    email: document.getElementById('email').value,
    firstName: document.getElementById('nombre').value,
    marketingOptIn: true,
  });
  if (result.hasGame) {
    const play = await ia.campaigns.play('verano-2026', { participantId: result.participantId });
    alert(play.prizeName ? `¡Has ganado ${play.prizeName}!` : 'Otra vez será');
  }
};
</script>

4. Iniciar sesión como socio (OTP)

await ia.auth.sendOtp({ phone: '+34600111222', programId: 1 });
const auth = await ia.auth.verifyOtp({ phone: '+34600111222', code: '123456' });
const dashboard = await ia.portal.getDashboard();

verifyOtp guarda el token. Para restaurar una sesión usa ia.setMemberToken(token).

5. Llamar a la API pública desde tu servidor

const ia = new IncentIA({ baseUrl: 'https://<tu-plataforma>', apiKey: process.env.INCENTIA_KEY });

const member = await ia.members.lookup({ programId: 1, phone: '+34600111222' });
await ia.transactions.purchase({
  memberId: member.memberId, programId: 1, amount: 49.99, externalReference: 'ORDER-12345',
});

Módulos

Módulo	Acceso	Métodos principales
ia.campaigns	Público	getStatus, register, play
ia.auth	Público	resolve, register, sendOtp, verifyOtp, loginGoogle, loginApple, refresh
ia.portal	Token de socio	getDashboard, getRewards, redeemReward, getGames, playGame, getStamps, checkin, submitEvidence…
ia.members	Clave API	lookup, getBalance, getTransactions
ia.transactions	Clave API	purchase, action, redeem, adjust
ia.coupons	Clave API	validate, redeem
ia.whitelabel	Público	resolve, getLanding, getCampaignLanding

Las rutas y los campos de los módulos con clave API son los de la API pública.

Errores

Cada método devuelve una promesa. Al fallar, el error trae status, message y details:

try { await ia.portal.redeemReward(99); }
catch (err) { if (err.status === 400) alert(err.message); }

Comprueba que funciona

Abre la consola del navegador: ia.campaigns.getStatus('<tu-slug>') debe devolver los datos de la campaña. Un error de CORS indica que falta tu dominio en los orígenes permitidos.

Siguientes pasos

• Embed de campaña y ranking, si prefieres no escribir código.
• API pública v1