Inicio Rápido

¡Bienvenido a Fiskil! Esta guía te ayudará a poner en marcha tu integración con Fiskil en muy poco tiempo. Tanto si construyes una aplicación bancaria como de energía, sigue estos pasos para conectar las cuentas de tus usuarios y empezar a obtener datos.

1. Crea tu cuenta de Fiskil

Empieza creando una cuenta en la Consola de Fiskil. Una vez registrado, podrás generar tus claves de API y acceder a las herramientas necesarias para integrar Fiskil en tu app o sitio web.

2. Autentícate con Fiskil

Fiskil autentica tus peticiones a la API mediante claves de API generadas desde la consola. Así se intercambian tus claves de API por un token de acceso:

Genera claves de API

En el menú Settings > API Keys, crea una clave de API seleccionando todos los scopes.

Solicita un token de acceso

Haz una petición POST al endpoint /v1/token. Sustituye your_client_id y your_client_secret por el client ID y el secret que guardaste en el paso anterior.

curl --location --request POST 'https://api.fiskil.com/v1/token' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}'

3. Crea un usuario final

Un End User representa a un usuario de tu app. Necesitas crear este objeto para vincular cuentas y gestionar el consentimiento.

Haz una petición POST a /v1/end-users con los datos del usuario. Sustituye your_token por el token que obtuviste del endpoint /v1/token.

curl --request POST \
  --url https://api.fiskil.com/v1/end-users \
  --header 'Authorization: Bearer your_token' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "user@example.com",
    "name": "User Name",
    "phone": "+1234567890"
  }'

Guarda el end_user_id devuelto en la respuesta para futuras llamadas a la API.

4. Configura tu flujo de consentimiento

Las APIs de Fiskil son agnósticas al caso de uso, pero es fundamental que tus usuarios entiendan qué datos están consintiendo compartir.

Personaliza el consentimiento en la consola

Ve a la página Customize UI de la Consola de Fiskil.

Actualiza:

• Periodo de consentimiento: elige una duración adecuada
• Historial de datos: limita el historial a lo necesario para una sincronización más rápida
• Casos de uso: describe con claridad por qué necesitas el acceso
• Marca: añade tu logotipo, el nombre de tu empresa y ajusta los colores a tu marca

Pulsa "Save" cuando estés satisfecho con tu UI de consentimiento.

5. Crea una Auth Session

Una Auth Session facilita la vinculación de la cuenta de un usuario a través del flujo de consentimiento que diseñaste. La Auth Session se usa junto con el SDK de Fiskil Link para incrustar la interfaz de vinculación de cuentas dentro de tu aplicación.

Haz una petición POST a /v1/auth/session:

curl --request POST \
  --url https://api.fiskil.com/v1/auth/session \
  --header 'Authorization: Bearer ${token}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "cancel_uri": "https://yourapp.com/cancel",
    "end_user_id": "${end_user_id}"
  }'

Gestiona la respuesta

{
  "auth_url": "https://auth.fiskil.com/?sess_id=your_session_id",
  "expires_at": "2025-12-31T23:59:59Z",
  "session_id": "your_session_id"
}

Usa el auth_session_id con el SDK de Fiskil Link para lanzar la interfaz incrustada de vinculación de cuentas en tu aplicación.

Uso del SDK de Link

npm install @fiskil/link
# or
yarn add @fiskil/link

import { link } from '@fiskil/link';

const flow = link('auth_session_id');

try {
  const result = await flow;
  console.log('Consent ID:', result.consentID);
} catch (err) {
  console.error('Link error:', err);
}

// Cancel programmatically if needed
// flow.close();

Para conocer todas las opciones de configuración y la gestión de errores, consulta Integrar el SDK de Link.

6. Escucha eventos de webhook

Cuando un usuario completa el flujo de consentimiento, Fiskil emite eventos de webhook para avisarte de que los datos están listos. Escucharlos es el patrón de integración recomendado.

Eventos clave a gestionar:

• consent.received – se dispara cuando el usuario completa el flujo de consentimiento
• banking.transactions.sync.completed – los datos bancarios se han sincronizado
• energy.usage.sync.completed – los datos de energía se han sincronizado

Puedes registrar tu endpoint de webhooks en la Consola de Fiskil, en Settings > Teams > Webhooks.

Fiskil firma cada payload con una firma HMAC-SHA256 en la cabecera X-Fiskil-Signature. Asegúrate de verificar esta firma antes de procesarlo.

Más información en la guía de Webhooks

7. Obtén datos con las APIs de Fiskil

Una vez que el usuario ha completado el flujo de consentimiento, puedes acceder a sus datos mediante las APIs de Banking o Energy de Fiskil.

APIs de Banking

APIs de Energy

Nota: la mayoría de los endpoints admiten reintentos e idempotencia. Recomendamos escuchar los eventos de webhook antes de intentar obtener datos para asegurar su disponibilidad.

8. Prueba tu integración

Antes de pasar a producción, valida tu integración de extremo a extremo:

• Crea un usuario final de prueba
• Recorre el flujo de consentimiento
• Confirma la entrega de webhooks
• Obtén datos con la API correspondiente

Cuando tengas confianza en tu flujo, revisa nuestra Checklist de lanzamiento para prepararte para producción.

¿Necesitas ayuda?

¿No eres desarrollador? ¡No pasa nada! Contacta con los expertos certificados de Fiskil o explora nuestros ejemplos Open Source.

🎉 ¡Eso es todo! Ya estás listo con Fiskil. Cuéntanos qué estás construyendo: nos encantará ayudarte o incluso destacar tu producto en nuestro blog.