EasyBankData.

Empezar en cinco minutos

De cero a tu primer dato: sacar una clave, hacer una llamada y dejar montado el aviso de que llegaron datos nuevos. Los ejemplos de esta página se generan del contrato que sirve el servicio, así que no pueden quedarse viejos.

1. Saca una clave

En el panel, en API y webhooks. Empieza por una de prueba: ebd_test_… alcanza solo datos de ejemplo, no gasta cupo del proveedor y no toca ninguna conexión real. Es la forma de integrar de verdad antes de pagar nada.

El valor se enseña una sola vez —en nuestros servidores queda su resumen, no la clave—, así que cópiala a un sitio seguro. Va en cada llamada, en esta cabecera:

Authorization: Bearer ebd_test_…

Una clave de prueba y una de verdad se usan igual; lo que cambia es a qué alcanzan. La de prueba solo ve datos de ejemplo y del sandbox, y todas sus respuestas lo dicen.

Alcance, permisos y caducidad

Por defecto una clave llega a todas las empresas y cuentas de quien la emite, con acceso completo y sin caducidad. Al emitirla, en Opciones de la clave, puedes recortarla:

Tu programa puede preguntar qué tiene su clave con GET /v1/key: su alcance efectivo, el nivel de cada recurso y cuándo caduca. Un endpoint de avisos registrado por la API con una clave recibe solo los eventos que esa clave puede leer: los de sus empresas, sus cuentas y sus recursos (con una clave limitada a unas cuentas, los que son de toda la empresa, como los de presupuestos, no salen). Las claves de prueba admiten lo mismo, con las cuentas de ejemplo y del sandbox.

Con la de prueba puedes recorrer el ciclo completo: conectar bancos de prueba, seguir la operación, recibir los webhooks firmados y pedir refrescos, sin gastar nada y sin tocar un banco real. Está todo en el sandbox.

2. Haz tu primera llamada

La clave alcanza las empresas de quien la emitió (o las que se reservó al emitirla). Esta llamada no gasta nada y devuelve sus identificadores públicos: de ahí sale el {tenant} que llevan todas las demás direcciones.

2.1. Saber sobre qué empresas puede leer tu clave

Es la primera llamada que hay que hacer y no gasta nada. Devuelve las empresas cuyo acceso tiene quien emitió la clave, y de ahí sale el `{tenant}` que llevan todas las demás.

GET https://app.easybankdata.com/v1/tenants

curl -s \
  -H "Authorization: Bearer $EBD_CLAVE" \
  "https://app.easybankdata.com/v1/tenants"
Lo mismo en PHP
$ch = curl_init('https://app.easybankdata.com/v1/tenants');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('EBD_CLAVE'),
    ],
]);

$datos = json_decode(curl_exec($ch), true, 512, JSON_THROW_ON_ERROR);

2.2. Traer los movimientos, paginando

Los movimientos de todas las cuentas de esa empresa, del más reciente al más antiguo, dos por página para que se lea. La respuesta trae un testigo de continuación: mientras lo devuelva, quedan páginas.

GET https://app.easybankdata.com/v1/tenants/{tenant}/transactions?limit=2

curl -s \
  -H "Authorization: Bearer $EBD_CLAVE" \
  "https://app.easybankdata.com/v1/tenants/{tenant}/transactions?limit=2"
Lo mismo en PHP
$ch = curl_init('https://app.easybankdata.com/v1/tenants/{tenant}/transactions?limit=2');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('EBD_CLAVE'),
    ],
]);

$datos = json_decode(curl_exec($ch), true, 512, JSON_THROW_ON_ERROR);

2.3. Pedir datos frescos (esto sí gasta)

Leer lo que ya está descargado no gasta nada; pedir una lectura nueva llama al banco y consume cupo del plan. Contesta `202` con una operación, y el resultado llega después: el aviso de que terminó es el webhook de más abajo. Con una clave de prueba esta llamada se rechaza —una clave de prueba no gasta—, así que esta se prueba con la de verdad y sobre una conexión real.

POST https://app.easybankdata.com/v1/tenants/{tenant}/connections/{connection}/refresh

curl -s \
  -X POST \
  -H "Authorization: Bearer $EBD_CLAVE" \
  -H "Idempotency-Key: reintento-2026-09-24-a" \
  "https://app.easybankdata.com/v1/tenants/{tenant}/connections/{connection}/refresh"
Lo mismo en PHP
$ch = curl_init('https://app.easybankdata.com/v1/tenants/{tenant}/connections/{connection}/refresh');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('EBD_CLAVE'),
        'Idempotency-Key: reintento-2026-09-24-a',
    ],
]);

$datos = json_decode(curl_exec($ch), true, 512, JSON_THROW_ON_ERROR);

2.4. Conectar el banco de tu cliente con un enlace (el camino recomendado)

Crea un enlace y se lo mandas al titular por tu canal: lo abre sin cuenta en el panel, ve quién le pide acceso y conecta su banco. El enlace (`url`) solo viene en esta respuesta. Al terminar vuelve a tu `redirect_url` —si la diste y su origen está en Ajustes— y te llega el aviso `sesion_de_conexion.completada`. La profundidad del histórico la elige el titular, no se fija por la API.

POST https://app.easybankdata.com/v1/tenants/{tenant}/connect_sessions

curl -s \
  -X POST \
  -H "Authorization: Bearer $EBD_CLAVE" \
  -H "Idempotency-Key: enlace-cliente-123" \
  -H "Content-Type: application/json" \
  -d '{"external_ref":"cliente-123","locale":"es"}' \
  "https://app.easybankdata.com/v1/tenants/{tenant}/connect_sessions"
Lo mismo en PHP
$ch = curl_init('https://app.easybankdata.com/v1/tenants/{tenant}/connect_sessions');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => '{"external_ref":"cliente-123","locale":"es"}',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('EBD_CLAVE'),
        'Idempotency-Key: enlace-cliente-123',
        'Content-Type: application/json',
    ],
]);

$datos = json_decode(curl_exec($ch), true, 512, JSON_THROW_ON_ERROR);

La base de estas direcciones es https://app.easybankdata.com/v1. Y lo que puede contestar cada llamada, con qué hacer en cada caso, está en códigos de error.

3. Deja que te avisemos

Preguntar cada cinco minutos si hay datos nuevos es lo que hacen las integraciones que no quieren serlo. Registra un endpoint en el panel —tiene que ser https y resolver a una dirección de internet— y te avisamos cuando pase algo: una lectura terminada, una que falló, una conexión que necesita que su dueño la autorice otra vez, un consentimiento a punto de caducar, cómo va un enlace de conexión (abierto, completado, fallido o caducado sin terminar), o una cuenta cuyo saldo no cuadra con sus movimientos (saldo.descuadrado, con la diferencia en céntimos).

Un aviso dice qué ha pasado, de qué conexión y cuántos datos llegaron. Nunca lleva importes, saldos, cuentas ni contrapartes: viaja a un servidor que no es el nuestro, así que el detalle lo recoges por la API, con tu clave y en tu casa.

Cada entrega va firmada. La cabecera es X-EasyBankData-Signature y lleva t=<segundos>,v1=<hmac>, calculado sobre marca.cuerpo con el secreto del endpoint. Se comprueba así:

$cabecera = $_SERVER['HTTP_X_EASYBANKDATA_SIGNATURE'] ?? '';
$cuerpo   = file_get_contents('php://input');   // el cuerpo CRUDO, sin volver a montarlo

$t = null; $firmas = [];                     // t=…,v1=… (dos v1 mientras dura la gracia de una rotación)
foreach (explode(',', $cabecera) as $trozo) {
    [$k, $v] = array_pad(explode('=', trim($trozo), 2), 2, '');
    if ($k === 't')  { $t = $v; }
    if ($k === 'v1') { $firmas[] = $v; }
}

$mia = hash_hmac('sha256', $t.'.'.$cuerpo, $secreto);   // tu secreto, el del endpoint
$vale = array_filter($firmas, fn ($v1) => hash_equals($mia, $v1)) !== [];

if (! $vale || abs(time() - (int) $t) > 120) {
    http_response_code(401);                     // no es nuestro, o no es de ahora
    exit;
}

http_response_code(200);                         // con un 2xx se da por entregado
$aviso = json_decode($cuerpo, true);             // $aviso['type'], $aviso['data']

⚠️ El cuerpo se comprueba tal cual llegó, no reconstruido con tu librería: si lo vuelves a montar, el orden de las claves cambia y la firma deja de cuadrar. Contesta 2xx en cuanto lo tengas: cualquier otra cosa cuenta como intento fallido y se reintenta cinco veces, esperando cada vez más. Si tu servidor no contesta, el aviso no se pierde —se reintenta— y el registro de intentos queda en el panel.

Todo lo demás —el catálogo entero con ejemplos, rotar el secreto sin cortar, probar, el historial y reenviar lo que no llegó— está en la guía de webhooks.

4. Lo que hay que saber antes de programar

Siguiente: el sandbox · integrar un ERP · Google Sheets, Power BI y Looker Studio · la API entera, con probador en vivo · qué puede fallar · versiones y retiradas