API de Holded: guía práctica de la v2
(y lo que la documentación no cuenta)
Si buscas la API de Holded, lo que tienes que saber es esto: hay una v1 y una v2, no se mezclan, y los tokens nuevos solo funcionan en la segunda. Aquí tienes cómo se autentica, qué permisos conviene dar y qué trampas nos hemos encontrado al integrarla.
Lo medimos nosotros el 28 de septiembre de 2026. Para el detalle de cada ruta, la referencia es la oficial: developers.holded.com. Esta guía es lo que no está allí. Si lo que buscas es qué se puede conectar sin programar, empieza por las integraciones de Holded.
Y si no quieres pelearte con esto, te lo integramos.
API de Holded v1 contra v2: la tabla que te ahorra una tarde
La confusión más común es probar un token nuevo contra la dirección vieja y creer que la API no funciona. Son dos mundos distintos.
Medido por nosotros el 28 de septiembre de 2026. Holded puede cambiar su API: confirma siempre en la referencia oficial.
Token de la API de Holded: 11 áreas y cuatro niveles de permiso
Es lo mejor de la v2. Cada token se configura por área con uno de cuatro niveles, y son 11 áreas. Si pides algo para lo que no tienes permiso, recibes un 403.
El token no ve esa área. Si la pide, recibe 403.
Consulta, pero no crea ni modifica nada. Es el punto de partida para cualquier informe o IA.
Puede crear y modificar. Solo si la integración lo necesita de verdad.
Control total del área. Casi nunca está justificado.
Nuestra regla: un token por integración y el mínimo permiso que necesite. Para informes, cruces con el CRM o una IA, Leer es suficiente. Así, si una llave se filtra, el daño tiene techo. Es lo mismo que aplicamos para conectar la IA con Holded, que explicamos en Holded con IA.
Tu primera petición a la API de Holded v2
Listar facturas con un token Bearer. El token del ejemplo es ficticio: el tuyo empieza también por pat_.
$ curl -s https://api.holded.com/api/v2/invoices \ -H "Authorization: Bearer pat_XXXXXXXXXXXXXXXX" \ -H "Accept: application/json" { "items": [ { "total": 1210.00, "payments_pending": 0, "verifactu_status": "...", ... } ]}La respuesta de la v2 llega paginada dentro de items y los campos en snake_case. Los valores del ejemplo son ilustrativos. Cualquier otra ruta, consúltala en la referencia oficial.
¿Tienes claro qué quieres conectar pero no quién lo monta? Lo vemos en un diagnóstico de 1 hora, sin coste y sin compromiso.
Reservar diagnósticoWebhooks de Holded y límites de uso: no preguntes cada pocos minutos
Dos mecanismos que van juntos: el límite te frena, el webhook hace que casi nunca lo toques.
Límites de uso
Holded limita el uso y, al pasarte, responde con 429 y una cabecera Retry-After. No te damos una cifra de peticiones porque no vamos a inventarla: está en la documentación oficial. Lo que sí sabemos es cómo comportarse: leer Retry-After, esperar eso, reintentar con espera creciente y no lanzar peticiones en paralelo sin control.
Webhooks
La v2 tiene webhooks: Holded te avisa cuando pasa algo, en vez de que tú preguntes cada pocos minutos. Gastas menos peticiones y te enteras antes. Dos consejos de oficio: haz tu receptor idempotente (que procesar dos veces el mismo aviso no duplique nada) y deja una comprobación periódica contra la API por si algún aviso se pierde.
Seis trampas de la API de Holded que te harán perder una tarde
Las encontramos al integrarla. Ninguna es grave si la conoces; todas son silenciosas si no.
Un 200 no significa que haya ido bien
En rutas que no existen, Holded puede devolver un 200 con una página HTML o con un JSON de error. Si tu código se fía del código de estado, procesará basura como si fuera un dato. Valida la forma de la respuesta (que venga el objeto o el items que esperas), no solo el código.
El status numérico de un documento es ambiguo
No te apoyes en él para saber si una factura está cobrada. Deriva el estado de payments_pending comparándolo con total: si no queda nada pendiente, está cobrada; si queda todo, no se ha cobrado nada; en medio, está parcial.
Las fechas llegan como timestamp unix, en segundos
No en milisegundos. Si las pasas tal cual a una librería de fechas de JavaScript, te salen fechas de 1970. Multiplica por 1.000 o usa una conversión explícita, y fija la zona horaria al mostrarlas.
Las series de numeración no están en la v2
Solo existen en la v1, que no acepta los tokens nuevos. Resultado práctico: las series se configuran a mano en Holded y tu integración debe asumir que ya existen, en vez de intentar crearlas.
Un token sin permiso da 403, no un resultado vacío
Si tu token no tiene permiso sobre un área, la API responde 403. Trátalo como un error de configuración que hay que avisar, no como «no hay datos». Si no, un permiso mal puesto parece que la cuenta está vacía.
Un 429 se respeta, no se machaca
Si te pasas del límite recibes 429 con Retry-After. Reintentar al instante empeora las cosas. Espera lo que indica la cabecera, reintenta con espera creciente y reduce el ritmo.
Campos de la API de Holded que merecen la pena
Cinco campos que convierten la API en algo útil para el negocio y no solo en un volcado de datos.
Si quieres entender qué significa cada estado fiscal, lo contamos en Holded y Verifactu.
Qué automatizar con la API de Holded y qué dejar en manos humanas
Lo que sale mal con una API no suele ser técnico: es dar demasiado poder a un script en una cuenta que factura de verdad.
Sí conviene
- Leer facturas, cobros y contactos para cruzarlos con tu CRM y saber qué campaña trae ventas reales.
- Listar facturas con incidencia en verifactu_status o pagos sin conciliar, como aviso diario.
- Avisar por webhook cuando entra algo nuevo, en lugar de preguntar cada pocos minutos.
- Dejar que una IA consulte la cuenta con un token de solo lectura.
Mejor no, en una cuenta viva
- Emitir facturas reales de forma automática en una cuenta viva, sin revisión humana ni prueba previa.
- Tocar la configuración fiscal: impuestos, series, envíos a Verifactu. Un error ahí tiene consecuencias legales.
- Dar un token con permiso Full «para ir más rápido». Si se filtra, se filtra todo.
- Borrar o modificar documentos ya emitidos sin un procedimiento claro.
Cuándo no necesitas programar contra la API
Honestidad: muchas veces la API sobra. Si lo que quieres es conectar Holded con una herramienta que ya trae su integración y cubre lo que necesitas, úsala y ahórrate el desarrollo. La API compensa cuando necesitas algo a medida, como cruzar facturas con tu CRM para medir ventas reales, o dar a una IA acceso controlado.
Qué integraciones conviene usar y cuáles hacer a medida lo tienes en Integraciones de Holded. Y si aún no tienes Holded implantado, empieza por la implantación.
Cómo trabajamos: por fases y con presupuesto cerrado
Presupuesto cerrado antes de empezar, la mitad al empezar cada fase y la otra al cerrarla.
Diagnóstico de 1 hora, sin coste y sin compromiso
Una reunión, no un informe de días. Vemos qué quieres conectar, qué ya existe hecho y si de verdad necesitas la API. Si no hace falta, te lo decimos.
Presupuesto cerrado antes de empezar
Trabajamos por fases. Cada fase tiene alcance y presupuesto cerrados antes de arrancar: la mitad al empezar la fase y la otra mitad al cerrarla.
Permisos mínimos y pruebas en seguro
Tokens por integración, con el mínimo permiso. Todo lo que escribe se prueba primero fuera de la cuenta viva.
Documentado para que no dependas de nadie
Te dejamos escrito qué token tiene qué permiso, qué se sincroniza, cada cuánto y qué hacer si algo falla.
Si no quieres pelearte con la API de Holded, te lo integramos
Un diagnóstico de 1 hora, sin coste y sin compromiso. Nos cuentas qué quieres conectar y te decimos cómo lo haríamos, qué ya existe hecho y si de verdad te hace falta tocar la API. Si prefieres hacerlo tú, te llevas el plan.
Preguntas frecuentes sobre la API de Holded
Lo que nos preguntan desarrolladores y responsables técnicos antes de integrar Holded con el resto de su sistema.