EasyBankData.

Integrar un ERP

El recorrido de un módulo que lleva a un ERP (Dolibarr, Odoo o el tuyo) los movimientos y la categoría que el cliente ve en el panel, sin duplicar nada y sin perder un cambio. Los ejemplos se generan del contrato que sirve el servicio. Si no has hecho aún la primera llamada, empieza por Empezar.

La idea, en cuatro frases

Conectar el ERP sin copiar la clave

El botón «Conectar con EasyBankData» de tu módulo no pide pegar ninguna clave: abre nuestra pantalla «Autorizar» en el navegador, la persona entra con su cuenta (y su doble factor), elige una de las empresas que administra, ve lo que podrá hacer el ERP y pulsa «Autorizar». Vuelve a tu ERP con un código de un solo uso que tu módulo canjea por la clave. Es el flujo de «código de autorización» de OAuth 2.0 con PKCE (S256), sin nada más que aprender.

1. Abrir «Autorizar»

Genera un code_verifier al azar (de 43 a 128 caracteres [A-Za-z0-9-._~]) y un state, guárdalos en la sesión del usuario del ERP y lleva el navegador a esta dirección:

https://app.easybankdata.com/autorizar?client=dolibarr
    &redirect_uri=https://erp.ejemplo.es/custom/easybankdata/admin/oauth.php
    &state=<state>
    &code_challenge=<BASE64URL(SHA256(code_verifier))>
    &code_challenge_method=S256
    &instance=<el nombre de esta instalación, el que verá la persona>
    [&environment=test]   (una clave de prueba: el sandbox)
    [&locale=en]
En PHP
$verifier  = rtrim(strtr(base64_encode(random_bytes(48)), '+/', '-_'), '=');
$state     = bin2hex(random_bytes(16));
$challenge = rtrim(strtr(base64_encode(hash('sha256', $verifier, true)), '+/', '-_'), '=');
$_SESSION['ebd_oauth'] = ['verifier' => $verifier, 'state' => $state];

header('Location: https://app.easybankdata.com/autorizar?'.http_build_query([
    'client' => 'dolibarr',
    'redirect_uri' => $redirectUri,   // la MISMA que mandarás al canjear
    'state' => $state,
    'code_challenge' => $challenge,
    'code_challenge_method' => 'S256',
    'instance' => $nombreDeLaInstalacion,
], '', '&', PHP_QUERY_RFC3986));

2. Recibir el código

Tu redirect_uri recibe code y state (se añaden a su consulta si ya tenía una). Comprueba que el state es el tuyo antes de nada. El código caduca a los 10 minutos y solo admite un intento.

3. Canjearlo por la clave

curl -X POST https://app.easybankdata.com/v1/authorizations/token \
  -H 'Content-Type: application/json' \
  -d '{"grant_type":"authorization_code","code":"<code>","code_verifier":"<verifier>","redirect_uri":"<la misma>"}'

Sin clave: lo que autentica es el código con su verificador. La respuesta trae la clave (api_key) una sola vez, la empresa (tenant_id) y el origen al que se autorizó (integration.return_origin). Guárdala cifrada. Cualquier fallo (código caducado, repetido, otra dirección u otro verificador) es 400 invalid_grant: vuelve al paso 1. Si un código ya canjeado se repite, la clave que salió de él se revoca.

Conectar un banco desde el ERP, con vuelta

El formulario del banco no puede ir dentro de tu ERP (el proveedor solo lo abre en sus dominios), así que «Conectar banco» abre nuestra página segura y vuelve sola a tu ERP:

  1. Una vez, registra tu dirección de vuelta con la clave del ERP: POST /tenants/{tenant}/return_urls con {"url": "…"}. Solo se admite el mismo origen (esquema, host y puerto) que la redirect_uri autorizada; registrar otra vez la misma devuelve la que había.
  2. Crea la sesión: POST /tenants/{tenant}/connect_sessions con redirect_url en ese origen (y, si quieres, entity). No se manda ningún correo.
  3. Lleva al usuario a la url de la respuesta. Al terminar vuelve a tu redirect_url con session, status y, si ya terminó, connection. Con «No conectar y volver», status=cancelled.
  4. Una conexión real suele volver con status=authorizing: la lectura sigue en el banco. Sigue la sesión con GET /connect_sessions/{session} (o el webhook sesion_de_conexion.completada) hasta completed, que trae la conexión en connection_id.

El recorrido

1. Saber qué empresas alcanza la clave

Al instalar el módulo. Con una asesoría, la clave alcanza sus empresas cliente: el módulo guarda el id de la que corresponde a esta instalación del ERP.

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

curl -s \
  -H "Authorization: Bearer $EBD_CLAVE" \
  "https://app.easybankdata.com/v1/tenants"
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. Registrar el webhook del módulo

También al instalar: la dirección de tu ERP donde quieres los avisos. Guarda el secret de la respuesta, que no se vuelve a enseñar, y comprueba con él la firma de cada entrega (se explica en «Empezar»). Lo hace quien administra la empresa.

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

curl -s \
  -X POST \
  -H "Authorization: Bearer $EBD_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{"name":"Módulo Dolibarr","url":"https://erp.ejemplo.es/easybankdata/aviso","events":["lectura.terminada","conexion.necesita_autorizarse"]}' \
  "https://app.easybankdata.com/v1/tenants/{tenant}/webhooks"
En PHP
$ch = curl_init('https://app.easybankdata.com/v1/tenants/{tenant}/webhooks');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => '{"name":"Módulo Dolibarr","url":"https://erp.ejemplo.es/easybankdata/aviso","events":["lectura.terminada","conexion.necesita_autorizarse"]}',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('EBD_CLAVE'),
        'Content-Type: application/json',
    ],
]);

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

3. Emparejar las categorías con tus cuentas contables

El catálogo de categorías, con su código y su etiqueta. El módulo deja que el usuario empareje cada código con una cuenta de su plan contable; lo que llegue sin categoría del catálogo, a una cuenta de espera.

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

curl -s \
  -H "Authorization: Bearer $EBD_CLAVE" \
  "https://app.easybankdata.com/v1/categories"
En PHP
$ch = curl_init('https://app.easybankdata.com/v1/categories');
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);

4. Emparejar las cuentas bancarias

Cada cuenta, con su identificador estable. El módulo la empareja una vez con la cuenta bancaria del ERP y guarda la relación.

GET https://app.easybankdata.com/v1/tenants/{tenant}/accounts

curl -s \
  -H "Authorization: Bearer $EBD_CLAVE" \
  "https://app.easybankdata.com/v1/tenants/{tenant}/accounts"
En PHP
$ch = curl_init('https://app.easybankdata.com/v1/tenants/{tenant}/accounts');
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);

5. La primera sincronización

Todo, en orden de modificación, paginando con cursor hasta que has_more sea falso. Por cada movimiento, crea o actualiza su apunte en el ERP usando id como referencia única (así un reintento no duplica). La categoría buena es classification, no category (esa es la del banco). Al terminar, guarda el updated_at del último.

GET https://app.easybankdata.com/v1/tenants/{tenant}/transactions?sort=updated&limit=100

curl -s \
  -H "Authorization: Bearer $EBD_CLAVE" \
  "https://app.easybankdata.com/v1/tenants/{tenant}/transactions?sort=updated&limit=100"
En PHP
$ch = curl_init('https://app.easybankdata.com/v1/tenants/{tenant}/transactions?sort=updated&limit=100');
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);

6. Cada vez que llegue un aviso (o cada hora)

Solo lo modificado desde el updated_at que guardaste, incluido: puede repetirse alguno del mismo instante —por eso se actualiza por id—, nunca faltar. Trae lo nuevo y también lo antiguo que cambió (una reclasificación, un traspaso confirmado). Pídelo cuando llegue lectura.terminada y, por si se perdiera un aviso, de vez en cuando.

GET https://app.easybankdata.com/v1/tenants/{tenant}/transactions?sort=updated&updated_since=2026-09-26T08%3A00%3A00%2B02%3A00&limit=100

curl -s \
  -H "Authorization: Bearer $EBD_CLAVE" \
  "https://app.easybankdata.com/v1/tenants/{tenant}/transactions?sort=updated&updated_since=2026-09-26T08%3A00%3A00%2B02%3A00&limit=100"
En PHP
$ch = curl_init('https://app.easybankdata.com/v1/tenants/{tenant}/transactions?sort=updated&updated_since=2026-09-26T08%3A00%3A00%2B02%3A00&limit=100');
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);

7. Si el usuario cambia la categoría en el ERP

Súbela: queda como manual y ninguna regla la pisa. Así el panel y el ERP dicen lo mismo, y la próxima sincronización de otros módulos lo trae.

PATCH https://app.easybankdata.com/v1/tenants/{tenant}/transactions/{transaction}

curl -s \
  -X PATCH \
  -H "Authorization: Bearer $EBD_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{"category":"suministros"}' \
  "https://app.easybankdata.com/v1/tenants/{tenant}/transactions/{transaction}"
En PHP
$ch = curl_init('https://app.easybankdata.com/v1/tenants/{tenant}/transactions/{transaction}');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_POSTFIELDS => '{"category":"suministros"}',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('EBD_CLAVE'),
        'Content-Type: application/json',
    ],
]);

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

Lo que conviene saber

Siguiente: la API entera, con probador en vivo · qué puede fallar