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:
-
Empresas y cuentas. Todas, o las que marques (cada cuenta con su banco y sus cuatro
últimos dígitos). Es siempre un recorte de lo que ve quien la emite hoy: si a esa
persona se le retira una empresa o una cuenta, la clave la pierde en la llamada siguiente,
sin tocarla. Una empresa fuera del alcance responde
404, como una que no existe; una cuenta fuera del alcance no sale en ninguna lista y por su identificador da404. Lo que suma toda la empresa (previsión, presupuestos, indicadores) se comporta como para una persona limitada a esas cuentas. -
Permisos por recurso. Acceso completo (solo leer, o leer y escribir), o un nivel por
recurso: movimientos, cuentas, tesorería, informes y exportaciones, webhooks…
Cada operación dice su recurso en
x-recursodel contrato. Sin el nivel, la respuesta es403 key_permission_missingcondetails.resource,details.required_accessydetails.granted_access. El MCP solo enseña las herramientas de los recursos que la clave puede usar. -
Caducidad. Opcional. Desde esa fecha la clave responde
401 invalid_key, como una revocada. Quien la emitió recibe un correo y un aviso en la campana 7 días antes.
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
-
Leer no gasta; pedir una lectura sí. Recorrer cuentas y movimientos es
consultar lo ya descargado. Pedir una lectura nueva llama al banco y consume el
cupo de ESA conexión —las lecturas al día que el plan de su empresa le da, en
24 horas móviles—, que viene en cada respuesta con su cabecera y en
GET /plan. -
Nada que dependa del banco es inmediato. Una conexión real tarda entre 5 y
15 minutos en traer los datos. Por eso las peticiones que la necesitan contestan
202con una operación que se sigue aparte, y por eso existe el aviso de que terminó. -
Para conectar un banco, el enlace. Si el banco es de otra persona (tu
cliente), crea un enlace de conexión y mándaselo: no necesita cuenta en el panel.
El
connect_urlque devuelvePOST /connectionssigue valiendo, pero es la pantalla del panel y pide entrar con una cuenta de la empresa. - Las páginas se recorren con un testigo. La respuesta trae el suyo; mientras lo devuelva, quedan páginas.
-
Reintentar es seguro si lo dices. Con la cabecera
Idempotency-Key, repetir la misma petición devuelve la misma respuesta sin volver a gastar. Sin ella, repetir una que gasta gasta otra vez. - Toda lectura queda registrada en el registro de accesos de la empresa, con la clave que la hizo.
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