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
- El ERP pide; nosotros avisamos. El módulo tira de la API, y el webhook solo le dice cuándo merece la pena pedir.
- Cada movimiento tiene un
idestable. Úsalo como referencia única del apunte en el ERP: crear o actualizar por él hace que un reintento no duplique. - Se sincroniza por fecha de modificación
(
sort=updatedyupdated_since), no por fecha del movimiento: así llega también lo antiguo que cambió. - La categoría es
classification.categoryes la que da el banco, tal cual. Muchos bancos dan solo un código sin nombre («5»): entoncesclassification.labeles nulo y el código va enclassification.bank_code. No lo enseñes como si fuera una categoría.
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));
redirect_uri:https, sin fragmento ni usuario. Solo conenvironment=testse admitehttp://localhostohttp://127.0.0.1. Se guarda tal cual y el canje la exige idéntica.- Si algún parámetro no vale, la pantalla lo dice y no vuelve a tu ERP.
- Al denegar, vuelve con
error=access_deniedy tustate.
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.
- La clave es a nombre de quien autorizó, solo llega a la empresa elegida y puede lo que necesita el módulo
(cuentas, movimientos, contabilidad, notas y justificantes, peticiones, conexiones, avisos y
webhooks; tesorería, solo leer).
GET /keylo dice. - En el panel sale como «De integración: Dolibarr» con su instancia, y se revoca desde allí. No se rota: se vuelve a conectar desde el ERP, y al canjear se revocan las claves anteriores de esa misma instancia.
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:
- Una vez, registra tu dirección de vuelta con la clave del ERP:
POST /tenants/{tenant}/return_urlscon{"url": "…"}. Solo se admite el mismo origen (esquema, host y puerto) que laredirect_uriautorizada; registrar otra vez la misma devuelve la que había. - Crea la sesión:
POST /tenants/{tenant}/connect_sessionsconredirect_urlen ese origen (y, si quieres,entity). No se manda ningún correo. - Lleva al usuario a la
urlde la respuesta. Al terminar vuelve a turedirect_urlconsession,statusy, si ya terminó,connection. Con «No conectar y volver»,status=cancelled. - Una conexión real suele volver con
status=authorizing: la lectura sigue en el banco. Sigue la sesión conGET /connect_sessions/{session}(o el webhooksesion_de_conexion.completada) hastacompleted, que trae la conexión enconnection_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
- Leer no gasta cupo. Sincronizar tantas veces como quieras es gratis; lo que gasta es pedir una lectura nueva al banco, y eso no le toca al módulo: las lecturas programadas ya las hace el servicio.
- Los permisos son los del panel. La clave hace lo que puede hacer quien la
emitió: con una de solo lectura, reclasificar devuelve
403. Y si esa persona tiene limitadas las cuentas, la clave también. - Lo que va por plan se ve en la documentación. Cada operación dice en qué planes está; abierta desde el panel, marca lo que queda fuera del tuyo.
- A los 30 días la contraparte se enmascara (y el concepto pierde lo que la
nombraba), y ese cambio sí vuelve a traer el movimiento en la sincronización,
con
counterparty.maskeda verdadero. Si el ERP guardó el nombre, no lo pises con el vacío: actualiza el apunte sin tocar la contraparte que ya tenía. Lo que se borra al darse de baja un cliente no deja rastro. - Lo que se borra no sale en la sincronización: sale en las lápidas. Un duplicado
resuelto, una conexión quitada o el borrado a petición del titular dejan, durante 90 días,
el
iddel movimiento con su cuenta, cuándo y por qué enGET /transactions/deleted?since=. Pídelas en cada pasada y retira del ERP lo que ya habías llevado. - Di qué movimientos llevaste.
PUT /transactions/{id}/erp_entrycon la referencia del apunte y el sistema (para una lista larga,PUT /transactions/erp_entriesmarca hasta 100 en una petición y da el resultado de cada uno);erp_entry=missingda lo que te queda. Si otro ERP (o tu módulo reinstalado) ya lo marcó con otra referencia, recibes409 erp_entry_conflict: no lo lleves otra vez. Es lo único que EasyBankData guarda de lo que haces en tu ERP. - La conciliación se hace en tu ERP, con tus facturas: no nos las mandes. EasyBankData no recibe
facturas ni documentos, y el panel no tiene pantalla de conciliar. Tu módulo lee los movimientos, mira
las facturas abiertas en su propia base de datos, propone con cuál casa cada uno, registra el pago y
marca el movimiento (el punto de arriba). Lo que antes servía para eso
(
/reconciliation/*,/transactions/{id}/ignorey los avisoscasado.*) se retiró y contesta410 endpoint_retired: qué se retiró y por qué. - Para no esperar a la pasada, suscribe tu receptor a
lectura.terminada,movimientos.nuevosytraspasos.por_revisar. Solo llevan identificadores: el aviso adelanta la pasada, y la pasada sigue siendo la que lee y escribe. Un reintento dePOST …/refreshcon la mismaIdempotency-Keytrae las mismas cabeceras del cupo que la primera respuesta. - El saldo del banco a una fecha (para cuadrarlo en el módulo con el saldo del ERP):
GET /accounts/{id}/balance?date=AAAA-MM-DD, con la apertura y los movimientos guardados; antes de la apertura no hay saldo y la respuesta dice por qué. - Si prefieres ficheros, el Norma 43 de una cuenta y el Excel de lo filtrado también salen por la API.
- Si el ERP remesa recibos, suscríbete a
recibo.devuelto: sale una vez por cada devolución (tras una lectura o tras importar un extracto), con el movimiento devuelto, el original si se identifica sin dudas y si es un recibo que cobraste (issued) o que te cobraron (received). Lo mismo se lee conGET /returned_receiptsydetected_since. Qué recibo de una remesa volvió no se sabe sin el fichero N19: si el original no se identifica, llega nulo. Si el banco carga la devolución con sus gastos en el mismo movimiento (605,00 cobrados, −608,50 devueltos), el original se enlaza igual yoriginal_matchdicewith_fees: los gastos son la diferencia entre los dos importes. - La contrapartida de cada movimiento, como datos:
GET /accounting/transaction_counterparts(un periodo otransaction_id), con la subcuenta, el tercero y de dónde sale (manual,transfer,counterparty,categoryobridge). Es la misma que el fichero de asientos, sin bajar el fichero. Tu ERP sabe de qué factura viene cada movimiento; esto es lo que sabe el servicio, solo del banco. - La tarjeta de débito no se suma dos veces. Cada compra con una tarjeta de débito sale también
en su cuenta corriente. Si esa cuenta está conectada, la tarjeta trae
mirror_of_account_id(su cuenta), y sus movimientos no cuentan en recurrentes, comisiones, avisos ni traspasos; enGET /transactions/totals, con la cuenta también en el filtro, no suman y se cuentan enmirror_card_count. Si llevas las dos al ERP, no apuntes dos veces el mismo cargo: con la cuenta basta. - Los avisos en el idioma de tu usuario. Manda
Accept-Language(esoen) enGET /notices: elsummarysale en ese idioma. Sin la cabecera, en castellano. - Cada usuario decide qué alertas le llegan.
GET/PUT /notification_preferencesson las preferencias de quien emitió la clave en esa empresa (correo y campana por tipo, al momento o en el resumen diario, importe mínimo en céntimos y cuentas), las mismas de Ajustes › Correos que recibes.GET /noticesya llega filtrado con ellas. Para callar un concepto concreto,POST /alerts/{alert}/mute; la lista y el «deshacer», en/notification_preferences/muted. Los webhooks no dependen de esto. - Lo que creas, lo puedes borrar.
DELETE /tags/{tag}(se quita de sus movimientos, que vuelven en la siguiente sincronización),DELETE /cost_centers/{id}(no si lo mide un presupuesto) yDELETE /integrations/{system}al desinstalar el módulo. Borrar del catálogo pide ver todas las cuentas de la empresa. - Para pintar tu lista sin una llamada por movimiento, cada movimiento trae
notes_count,attachments_countyopen_document_requests_count. Las peticiones de justificante se sincronizan como los movimientos:GET /document_requests?sort=updated&updated_since=. - Di cómo va tu módulo.
PUT /integrations/{system}(versión, última sincronización, escrituras pendientes, código del último error): el cliente lo ve en el panel y el soporte en su ficha. Al desinstalar,DELETE /integrations/{system}(con?instance=si la declaraste con instancia). - Prueba el ciclo entero en el sandbox: con una clave de prueba lees movimientos de bancos de prueba y los marcas como llevados (cómo).
Siguiente: la API entera, con probador en vivo · qué puede fallar