Endpoints de la API de Holded: el mapa por áreas.
Qué recurso pedir para cada dato, con las rutas reales de la v2 verificadas contra la API, los parámetros que importan y las excepciones que no vienen en la documentación.
David GonzálezLos endpoints de la API de Holded son las rutas HTTP a las que una aplicación externa llama para leer o escribir cada tipo de dato del programa: facturas, contactos, asientos, productos, tesorería. Cada uno admite unos métodos, unos filtros y una paginación propios, y la documentación oficial no siempre dice cuál devuelve el dato que se necesita.
La documentación oficial de Holded lista los endpoints, pero no te dice cuál necesitas para lo que quieres construir. Si tu objetivo es montar un informe financiero, no necesitas 305 endpoints: necesitas seis o siete, y saber cuál devuelve qué.
Esta es una referencia práctica organizada por área de negocio, con las rutas reales de la v2, los parámetros que de verdad usarás y un par de excepciones que descubrimos probando contra la API y que no aparecen en el catálogo oficial.
El patrón: cómo se construye cualquier llamada
Todas las llamadas de la v2 comparten la misma forma. Una vez la tienes clara, cambiar de recurso es cambiar una palabra en la URL.
Todo cuelga de https://api.holded.com/api/v2. Se acabaron los prefijos por módulo de la v1 (/api/invoicing/v1/, /api/crm/v1/…).
Aquí está el cambio que más sorprende: no basta con la clave que usabas en la v1. En la v2 cada clave se genera con permisos concretos y solo puede llamar a los endpoints que esos permisos autorizan. La creas en Ajustes → API → «Generar nueva clave» y se muestra una sola vez: si no la copias, hay que generar otra.
La clave viaja en la cabecera Authorization: Bearer TU_CLAVE, el estándar de la industria, en lugar de la cabecera propia key de la v1.
Cada respuesta es un sobre con items, cursor y has_more. Pides la siguiente página pasando el cursor recibido, hasta que has_more sea falso. El límite máximo por página es de 100 registros.
sales:invoices.read o contacts.write— y la documentación indica cuál exige cada endpoint. Si a tu clave le falta uno, la respuesta es 403 Forbidden, no un error de autenticación. Es fácil confundirlo con una clave mal copiada y perder horas buscando donde no es.Por eso, si vienes de una integración v1, el camino fiable no es reutilizar la clave antigua sino generar una nueva marcando los permisos de lectura que tu integración necesita: contabilidad, ventas, compras, contactos y tesorería, según los recursos que vayas a pedir. Antes de dar la migración por buena, prueba una llamada por área: la que devuelva 403 te dice exactamente qué permiso falta. El resto de cambios —rutas, paginación y formatos— está en la guía de migración a la v2.
Contabilidad: la base de cualquier informe
Si tu objetivo es un balance o una cuenta de resultados, estos dos recursos son el 90 % de lo que necesitas:
| Recurso | Qué devuelve | Para qué sirve |
|---|---|---|
ledger-entries | Los apuntes del libro diario, con fecha, cuenta, debe y haber | Construir la cuenta de resultados y el balance por periodo |
accounting-accounts | El plan de cuentas de la empresa, con nombre y grupo | Mapear cada apunte a su epígrafe del PGC |
El orden correcto es traer primero el plan de cuentas y después los asientos, porque sin el plan no puedes agrupar: un apunte a la cuenta 705 no significa nada hasta que sabes que pertenece a la cifra de negocio. Es el mismo mapeo del que depende cualquier cuadro de mando.
Ventas y compras: cada tipo tiene su ruta
En la v2, cada tipo documental es un recurso propio. Estas son las rutas reales, verificadas contra la API:
| Tipo de documento | Ruta v2 | Área |
|---|---|---|
| Factura de venta | invoices | Ventas |
| Recibo de venta | sales-receipts | Ventas |
| Factura rectificativa | credit-notes | Ventas |
| Presupuesto | estimates | Ventas |
| Proforma | proformas | Ventas |
| Pedido de venta | sales-orders | Ventas |
| Albarán | waybills | Ventas |
| Compra | purchases | Compras |
| Pedido de compra | purchase-orders | Compras |
| Albarán de recepción | receipt-notes | Compras |
404 No route found, y el catálogo oficial tampoco la incluye. El tipo solo existe en numbering-series/{tipo} y para creación o descarga de PDF por id. Si tu integración itera todos los tipos documentales, tienes que excluirlo o fallará.Contactos, catálogo y tesorería
| Recurso | Qué devuelve | Nota |
|---|---|---|
contacts | Clientes y proveedores | Necesario para el análisis de ingresos por cliente |
products | Catálogo de productos y servicios | Base del margen por línea |
treasury/accounts | Cuentas de tesorería y bancos | Devuelve el listado de cuentas |
treasury/accounts/{id}/bank-movements | Movimientos de una cuenta concreta | Anidado: primero pides las cuentas, luego los movimientos de cada una |
La tesorería es el único bloque con estructura anidada: no hay un endpoint global de movimientos. Tienes que listar las cuentas y después recorrer los movimientos de cada una filtrando por rango de fechas. Es la vía para construir la previsión de tesorería sobre datos reales.
Equipo y proyectos
| Recurso | Qué devuelve | Para qué |
|---|---|---|
employees | Personas del equipo | Coste de estructura y análisis por persona |
employee-times | Fichajes | Control de jornada |
projects | Proyectos abiertos | Rentabilidad por proyecto |
tasks | Tareas dentro de proyectos | Desglose del trabajo |
project-times | Horas imputadas a proyectos | El coste real de cada proyecto |
El cruce de project-times con el coste por hora de employees es lo que permite calcular la rentabilidad real de un proyecto — y de ahí, el coste variable que necesitas para el punto de equilibrio.
Los tres errores que más tiempo cuestan
A esos tres se suma el clásico: no controlar los límites de uso. La v2 los aplica por ventanas deslizantes y responde 429 con una cabecera Retry-After — el manejo correcto está detallado en la guía de la API de Holded.
Preguntas frecuentes
¿Dónde está la documentación oficial?
¿Me sirve la API Key que usaba en la v1?
key a Authorization: Bearer— sino el modelo de permisos: cada clave se genera con permisos concretos por recurso, mientras que en la v1 eran globales. Lo fiable es generar una clave nueva desde Ajustes → API marcando los permisos que tu integración necesita.Me devuelve 403 y estoy seguro de que la clave es correcta
403 Forbidden en la v2 significa que la clave es válida pero no tiene autorizado ese recurso. Revisa qué permiso exige el endpoint y regenera la clave incluyéndolo. Un 401, en cambio, sí sería una clave inválida o revocada.¿Puedo ver la clave otra vez si la pierdo?
¿Cuántos registros devuelve cada página?
¿Hay endpoint para los movimientos bancarios de todas las cuentas?
treasury/accounts y después pedir los movimientos de cada cuenta por su id.¿Puedo escribir además de leer?
¿Y si no quiero programar nada de esto?
Conclusión
La API de Holded cubre prácticamente toda la plataforma, pero para análisis financiero el mapa es pequeño: plan de cuentas, asientos, documentos, contactos y tesorería. Con esos cinco bloques tienes balance, cuenta de resultados, ratios y previsión de caja.
El resto de los 305 endpoints existen y son útiles, pero no los necesitas para empezar. Lo que sí necesitas es controlar la paginación, los límites y las excepciones — que es donde se va el tiempo de cualquier integración.
Todo lo anterior, calculado sobre tu ERP y con cada partida desglosada hasta la subcuenta: así lo resuelve Numio.
La integración con Holded, ya construida
Numio se conecta a la API de Holded, mantiene la sincronización y convierte tus asientos en balance, cuenta de resultados, ratios y tesorería. Sin endpoints ni mantenimiento.
Prueba Numio 30 días gratisSin tarjeta y sin permanencia, desde 39€/mes. ¿Llevas la contabilidad de clientes? Reserva una demo para asesorías.