La API de Holded, sin sorpresas.
Llevamos años integrando la API de Holded en proyectos reales: facturación automática, conciliación, CRM. Esta es la guía que nos habría ahorrado semanas: lo esencial, más los gotchas que no están en la documentación.
01 · TL;DR
La API de Holded es de lo mejor del segmento ERP pyme en España: REST, JSON y cobertura casi total del producto. Sus rarezas: autenticación por header propio key (v1), fechas en Unix timestamp en segundos, paginación simple 1-indexada y ausencia total de sandbox (todo es producción, respeta mucho). En mayo de 2026 llegó la API v2: Bearer token, paginación por cursor, fechas ISO y snake_case. Para integraciones nuevas, evalúa v2; la v1 sigue siendo la más documentada por la comunidad.
02 · Autenticación y estructura base (v1)
La API key se genera en Configuración → Developers dentro de Holded. Va en un header llamado key, en minúscula (no es un Bearer):
curl -H "key: TU_API_KEY" \
https://api.holded.com/api/invoicing/v1/contactsLa URL base incluye el módulo: https://api.holded.com/api/{modulo}/v1/{recurso}. Los módulos son invoicing (el grande: contactos, documentos, productos, pagos), accounting, projects, team y crm.
03 · Los recursos que más usarás
| Recurso | Para qué | Detalle clave |
|---|---|---|
/invoicing/v1/documents/{tipo} | Facturas, presupuestos, albaranes, proformas | El tipo va en la URL. Ojo: purchase es la factura RECIBIDA (de proveedor), no una orden de compra |
/invoicing/v1/contacts | Clientes y proveedores | Un solo recurso para ambos, distinguidos por atributos |
/invoicing/v1/products | Catálogo e inventario | Variantes anidadas |
/accounting/v1/dailyledger | Asientos contables | Para integraciones contables serias |
04 · Los 7 gotchas que te ahorrarán una tarde cada uno
- Fechas en Unix, en segundos. Si envías milisegundos (el default de JavaScript), Holded acepta la petición y te guarda la factura en el año 57.000 y pico. Divide entre 1000 siempre.
- No hay sandbox. Todo es producción. Nuestra práctica: una serie de facturación "PRUEBAS" y borrado disciplinado, o cuenta de test de pago aparte.
- Paginación 1-indexada hasta array vacío. No hay campo total: pides
?page=1, luego 2, hasta que la respuesta venga vacía. - Los IDs son ObjectId de MongoDB. 24 caracteres hex. Si guardas referencias cruzadas en tu sistema, trátalos como strings opacos.
- customFields case-sensitive. Se envían como array
[{"field": "NombreExacto", "value": "..."}]y el nombre debe coincidir letra a letra con el definido en Holded, mayúsculas incluidas. - Los totales los recalcula Holded. El importe de línea sale de unidades × precio: si tu origen trae descuentos o redondeos raros, envía el precio unitario efectivo (base de línea / cantidad) o los totales no cuadrarán céntimo a céntimo.
- El envío del SII no se dispara por API. El módulo SII de Holded se lanza desde la interfaz; si tu flujo lo necesita automático, tenlo en cuenta en el diseño.
05 · La nueva API v2 (mayo 2026): qué cambia
- Auth: Bearer token estándar en lugar del header
key. - Rutas: base unificada
/api/v2/. - Paginación por cursor en lugar de páginas numeradas: más robusta con datasets que cambian mientras paginas.
- Fechas ISO 8601 (adiós Unix) y snake_case en los campos.
- Módulos nuevos expuestos (bandeja de entrada, calendario, tesorería).
Nuestro criterio actual: integración nueva y sencilla → v2; integración con casuística fina → v1 todavía, porque la comunidad, los ejemplos y nuestro propio arsenal de recetas están en v1. Las dos conviven.
06 · Casos de uso reales (lo que construimos con ella)
- Captura de facturas de proveedor: el correo de facturas se lee solo, la IA extrae los datos y la factura entra en Holded como
purchasecon su PDF adjunto. Cero teclear. - Facturación desde otros sistemas: partes de trabajo, ERP sectorial o e-commerce que generan la factura en Holded automáticamente, con su numeración correcta.
- Reclamación de cobros: facturas vencidas detectadas cada mañana y recordatorio educado al cliente sin que nadie lo persiga.
- Informes a gerencia: ventas, cobros y tesorería del día en un resumen automático.
Si esto es lo que quieres para tu empresa, es literalmente nuestro trabajo: partner oficial de Holded especializado en automatización. Cómo trabajamos con Holded →. Y si estás eligiendo ERP todavía, empieza por qué es Holded y sus precios.
07 · Preguntas frecuentes
¿La API de Holded es gratuita?
El acceso a la API está incluido en los planes de pago de Holded; no se paga aparte por peticiones en uso normal. Genera la key en Configuración → Developers.
¿Tiene límites de peticiones (rate limit)?
Sí, hay límites razonables de uso justo. En integraciones bien diseñadas (webhooks donde se pueda, polling espaciado, reintentos con backoff) no se tocan. Un bucle sin control paginando todo el histórico cada minuto sí los tocará.
¿Puedo disparar el envío de facturas al SII o Verifactu por API?
El cumplimiento Verifactu (registros, QR) es automático al crear la factura, también por API. El envío masivo del módulo SII, en cambio, se lanza desde la interfaz de Holded, no hay endpoint público para dispararlo.
No soy técnico. ¿Todo esto me sirve de algo?
Sí: es la lista de la compra para quien contrates. Cualquier integrador serio debería conocer estos gotchas; si se los tienes que explicar tú, mala señal. Nosotros hacemos este trabajo llave en mano como partners.
¿Tienes una integración con Holded entre manos y algo no cuadra? Cuéntanoslo, probablemente ya nos hayamos peleado con ello. Solicitar diagnóstico →