10. La API REST de iDempiere

La API REST de iDempiere (plugin idempiere-rest, de la comunidad bxservice) expone el mismo modelo de datos y las mismas reglas de negocio que ZK, bajo /api/v1 — es la base de toda integración de FINORA: el portal, apps externas, y los propios playbooks que documentan cómo configurar un tenant sin entrar a la interfaz gráfica.

Autenticación

POST /api/v1/auth/tokens
{"userName":"GardenAdmin","password":"***"}
→ 200 {"clients":[{"id":11,"name":"GardenWorld"}],"token":"<token de paso 1>"}

PUT /api/v1/auth/tokens
{"clientId":11,"roleId":102,"organizationId":11,"warehouseId":103,"language":"en_US"}
→ 200 {"userId":101,"token":"<jwt>","refresh_token":"<rt>"}

Es un intercambio en dos pasos: primero usuario/contraseña (que puede devolver varios clients si la persona tiene acceso a más de un tenant), después la elección de cliente/rol/organización/almacén, que sí es la que entrega el JWT final. El token trae como claims el cliente, usuario, rol, organización y almacén elegidos — el mismo contexto que en ZK se arma en el diálogo de selección de rol (ver Tutorial 4). Expira en 60 minutos por defecto; el refresh token rota en cada uso y es de un solo uso (finora-erp-experience/idempiere/API_MAP.md, §2).

/models/{tabla}: acceso genérico gracias al Diccionario

GET /api/v1/models/c_bpartner?$filter=IsCustomer eq true&$select=Value,Name,TaxID&$orderby=Name&$top=3

Este endpoint funciona para cualquier tabla del Diccionario, incluidas las que agrega FINORA LVE, porque el REST le pregunta al Diccionario qué columnas tiene una tabla — el mismo mecanismo que hace posible que ZK dibuje cualquier ventana sin código nuevo (ver Tutorial 3). Soporta filtros al estilo OData ($filter, $select, $orderby, $expand, $top/$skip), incluyendo $expand anidado para traer un objeto de negocio completo en una sola llamada (finora-erp-experience/idempiere/API_MAP.md, §3.2: un Business Partner con sus facturas abiertas, pagos y contactos en una petición).

Trampas reales de escritura por REST (verificadas en desarrollo)

• Los valores por defecto se aplican también a claves foráneas. Una columna omitida recibe su DefaultValue del Diccionario aunque eso produzca una referencia inválida (ejemplo real: C_Tax.Parent_Tax_ID con default @C_Tax_ID@, que evalúa a 0 en un registro nuevo y rompe la restricción de clave foránea). Hay que enviar esas columnas explícitamente.
• POST /models/c_invoiceline necesita AD_Org_ID explícito — su valor por defecto depende de contexto de ventana que REST no tiene.
• Un rechazo de regla de negocio durante el guardado (un event handler que llama addErrorMessage) llega como HTTP 500, no como 400 — el mismo mecanismo del Tutorial 9 que rechaza un RIF inválido en ZK, devuelve el mismo mensaje por REST, solo que con otro código HTTP.

(finora-erp-experience/idempiere/API_MAP.md, §1.3 y §7.1)

Procesos y acciones de documento

Un proceso se ejecuta con POST /processes/{slug}, con sus parámetros en el cuerpo. Los parámetros de rango tienen una convención específica, corregida a partir de evidencia real de desarrollo: el límite inferior va en <nombre> y el superior en <nombre>_to, no como un arreglo [desde, hasta] (finora-erp-experience/idempiere/API_MAP.md, §6.1):

{"DateAcct": "2024-01-01", "DateAcct_to": "2024-12-31"}

Completar, anular o reversar un documento no es un endpoint propio: es un PUT sobre el registro con un campo doc-action, y dispara exactamente el mismo flujo (DOC_BEFORE_COMPLETE, DOC_AFTER_COMPLETE…) que el botón Completar en ZK — ver el diagrama de secuencia del Tutorial 2:

PUT /api/v1/models/c_invoice/{id}
{"doc-action":"CO"}

Nunca ejecutes acciones de documento como SuperUser

Completar una factura autenticado como un usuario de System (SuperUser) puede fallar con “Cross tenant PO writing”: MInvoice.completeIt actualiza el contacto de la factura (AD_User.LastContact), y si nadie especificó AD_User_ID, usa el usuario de la sesión — que, siendo de System, dispara la protección multi-tenant del core al intentar guardarse en un tenant ajeno (ver Tutorial 4). La solución es operar siempre con un usuario del propio tenant, o enviar AD_User_ID explícito con un contacto del tercero (finora-erp-experience/idempiere/API_MAP.md, §6.2 — causa raíz confirmada en MInvoice.java:2186-2190 y PO.checkCrossTenant).

Qué NO cubre el REST genérico (y qué hace falta agregar)

No todo lo que se necesita para una pantalla de negocio real existe de fábrica: agregados/KPI ($apply, $count no están soportados), antigüedad de saldos (RV_OpenItem no tiene una clave que REST pueda usar), o qué acciones de documento son válidas para un registro en un momento dado (ningún endpoint replica DocumentEngine.getValidActions). Estos casos requieren una vista del Diccionario con clave, o un endpoint propio — no un cambio al plugin REST (finora-erp-experience/idempiere/API_MAP.md, §10).

Todo lo de FINORA LVE se puede configurar por REST — por diseño

Es una regla del proyecto, no una casualidad: toda configuración de datos de FINORA debe poder hacerse por REST y quedar documentada como playbook (finora-lve/AGENTS.md, regla 7). Es la razón por la que los parámetros de tenant viven en la tabla propia FVE_Config en vez de en AD_SysConfig — la API REST no permite escribir AD_SysConfig desde un rol de tenant (ver Tutorial 4).

Paginación por defecto

Una consulta a /models/{tabla} sin $top no devuelve la tabla completa: el plugin aplica un tamaño de página por defecto y expone el total y los enlaces de siguiente/anterior página en la respuesta, al estilo OData ($top/$skip explícitos para pedir una página distinta). Para un listado que un integrador espera completo (por ejemplo, sincronizar todos los C_BPartner de un tenant), hay que iterar páginas explícitamente en vez de asumir que la primera respuesta ya trae todo.

Por verificar

El tamaño exacto de página por defecto del plugin idempiere-rest en la versión que usa FINORA no está confirmado en esta guía con un valor numérico — antes de construir una integración que dependa de ese número, verifícalo contra la instalación real (la respuesta de cualquier GET /models/{tabla} sin $top lo revela directamente).

Fuentes

• finora-erp-experience/idempiere/API_MAP.md (mapa completo del REST, con ejemplos ejecutados el 2026-09-24)
• finora-lve/AGENTS.md, regla 7 (toda configuración de datos por REST, documentada como playbook)
• finora-lve/decisions/ADR.md, ADR-LVE-013 (por qué FVE_Config y no AD_SysConfig)
• Repositorio de referencia: bxservice/idempiere-rest en GitHub