Migración API Holded v2: límites, rate limits y webhooks

Integraciones·◷ 12 min de lectura·Publicado 1 Jun 2026·Actualizado 4 Nov 2026·Por David González

Holded ha lanzado una nueva versión de su API: la v2, con disponibilidad general en junio de 2026. La anterior — la v1 — queda marcada como obsoleta: sigue funcionando para integraciones existentes, pero ya no recibe novedades y toda integración nueva debe construirse sobre la v2.

El problema es que Holded no está explicando bien la migración: la documentación de la v2 está publicada, pero no hay una guía clara que compare versión con versión ni que diga qué tienes que cambiar exactamente en tu integración. Si te conectas a Holded por API — o pagas a alguien que lo hace por ti —, este artículo te lo aclara.

Antes de entrar en los cambios, si todavía no tienes claro qué es y para qué sirve, repasa nuestra guía de qué es la API de Holded. Aquí nos centramos en qué cambia de la v1 a la v2.

En pocas palabras: Si tu empresa usa una conexión con Holded, el cambio a v2 afecta principalmente al proveedor que la mantiene, no al uso diario de Holded. Conservamos la guía completa para que puedas supervisar la transición y pedir pruebas; la tabla de límites que encontrarás aquí se ha sustituido por la información vigente de Holded.

Por qué Holded cambia a la API v2

La API v1 de Holded creció a lo largo de los años de forma fragmentada: cada módulo (facturación, CRM, proyectos, equipo, contabilidad) tenía su propia ruta base y su propia lógica. Funcionaba, pero era inconsistente y limitada — apenas cubría una parte de lo que se puede hacer en la plataforma.

La v2 es una reescritura completa: una sola URL base, autenticación estándar, paginación moderna y 305 endpoints que cubren prácticamente toda la plataforma (contabilidad, tesorería, ventas, inventario, contactos, CRM, proyectos, equipo, calendario y bandeja de entrada). Es la base sobre la que Holded construye lo que viene: los webhooks ya están documentados y el servidor MCP sigue anunciado.

v1 vs v2: comparativa de un vistazo

Estos son los puntos donde realmente cambia la integración. Cada fila la desarrollamos justo después con ejemplos.

Los 6 cambios clave de la API de Holded

1. Autenticación: de la cabecera key al token Bearer

Es el cambio que rompe todas las integraciones de la v1. La v1 enviaba la API Key en una cabecera propia llamada key. La v2 usa el estándar de la industria: la clave viaja en la cabecera Authorization con el prefijo Bearer.

# Cabecera propia "key"
GET https://api.holded.com/api/invoicing/v1/contacts
key: TU_API_KEY
Content-Type: application/json

# Authorization: Bearer
GET https://api.holded.com/api/v2/contacts
Authorization: Bearer TU_API_KEY
Content-Type: application/json

Sigue siendo una clave y no hace falta montar un flujo OAuth, pero ojo: no basta con reutilizar la 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 Configuración → API pulsando «Generar nueva clave», marcando los permisos de lectura que tu integración necesite. La clave solo se muestra una vez, así que guárdala bien. El detalle está en cómo conseguir tu API Key de Holded.

2. URL base: de rutas por módulo a una sola

En la v1 cada módulo tenía su propio prefijo: /api/invoicing/v1/ para facturación, /api/crm/v1/, /api/accounting/v1/, etc. Había que recordar a qué «familia» pertenecía cada recurso. La v2 unifica todo bajo una única base: /api/v2/{recurso}.

https://api.holded.com/api/invoicing/v1/documents
https://api.holded.com/api/crm/v1/leads
https://api.holded.com/api/accounting/v1/dailyledger

https://api.holded.com/api/v2/invoices
https://api.holded.com/api/v2/leads
https://api.holded.com/api/v2/journal-entries

No es solo cosmético: además de la ruta, cambian nombres de recursos y la forma de las respuestas. No basta con sustituir el prefijo — hay que revisar cada endpoint contra la nueva referencia y la especificación OpenAPI que Holded publica.

3. Paginación: de página/offset al cursor

La v1 paginaba por página u offset. La v2 usa paginación por cursor, más fiable cuando hay muchos datos. Cada respuesta de listado trae tres campos: items (los resultados), cursor (la marca para pedir la página siguiente) y has_more (si quedan más). El parámetro limit controla el tamaño de página (por defecto 25, máximo 100).

// Bucle hasta que no quede cursor
let cursor = null;
do {
  const url = new URL("https://api.holded.com/api/v2/invoices");
  url.searchParams.set("limit", "50");
  if (cursor) url.searchParams.set("cursor", cursor);
  const res = await fetch(url, {
    headers: { "Authorization": "Bearer TU_API_KEY" }
  });
  const data = await res.json();
  procesar(data.items);
  cursor = data.has_more ? data.cursor : null;
} while (cursor);

Si tu integración v1 recorría páginas con un contador (page=1, 2, 3…), esa lógica hay que reescribirla por completo.

4. Cobertura: de ~136 a 305 endpoints

La v1 cubría cinco módulos (facturación, CRM, proyectos, equipo y una contabilidad muy básica). La v2 amplía a diez categorías y más del doble de endpoints, con áreas que antes no se podían tocar por API, como tesorería, calendario o la bandeja de entrada.

Límites actuales de uso de la API de Holded por plan

Holded documenta dos límites simultáneos: uno controla picos de actividad por minuto y otro el total mensual. Se aplican al conjunto de la cuenta, así que varias conexiones o claves pueden consumir la misma cuota. La siguiente tabla refleja la documentación consultada el 22 de septiembre de 2026; comprueba con Holded las condiciones de tu cuenta antes de dimensionar un proyecto.

Si se alcanza un límite, la integración puede recibir una respuesta de exceso de solicitudes (código 429). En lenguaje de negocio: la conexión debe frenar y reintentar cuando el servicio indique que puede hacerlo. Pregunta qué verá tu equipo durante esa pausa, si se acumulan los datos pendientes y quién recibe el aviso. Crear claves adicionales no aumenta el presupuesto común de la cuenta.

Los avisos automáticos de cambios, llamados webhooks, pueden reducir consultas repetidas para algunos eventos. No cubren todos los tipos de datos y no eliminan la necesidad de controles de respaldo. Consulta nuestra guía de webhooks de Holded para entender cuándo pueden ayudar y qué límites conviene confirmar.

6. Lo que viene: webhooks, MCP y OpenAPI

La v2 abre la puerta a tres cosas que la v1 no tenía. La especificación OpenAPI ya está disponible (puedes generar clientes automáticamente). Los webhooks ya están documentados: Holded publica eventos de ventas, de compras y de catálogo y contactos, así que puedes reaccionar a los cambios en lugar de preguntar cada X minutos — lo desarrollamos en la guía de la API de Holded. El servidor MCP (para conectar la cuenta a agentes de IA) sigue anunciado como «próximamente». Merece la pena tenerlos en el radar al diseñar una integración nueva.

Checklist de migración a la API v2

Si gestionas tu propia integración, este es el orden sensato para migrar sin sustos:

Conéctate a Holded sin tocar la API

Toda esta migración tiene sentido si tu negocio es mantener una integración propia. Pero si lo que quieres es ver tus datos de Holded convertidos en dashboards, estados financieros y análisis — sin programar nada —, no necesitas pelearte con v1 ni v2.

Numio se conecta a Holded por ti: introduces tu API Key de Holded y, a partir de ahí, nosotros nos ocupamos de hablar con la API — incluidos los cambios de versión. Cuando Holded evoluciona la API, lo absorbemos por dentro; tu integración no se rompe.

Si quieres entender cómo encaja una capa de análisis sobre tu ERP, te ayudan estas guías: integraciones financieras y cómo conectar tu ERP a un dashboard. También te interesa cómo exportar los datos de Holded por API con la v2.

Preguntas frecuentes

Conclusión

La migración a la API v2 de Holded no es un simple cambio de número de versión: cambian la autenticación, las rutas, la paginación y la cobertura. La v1 seguirá funcionando un tiempo, pero el futuro de la plataforma — webhooks, MCP, nuevas áreas — vive en la v2.

Si mantienes una integración propia, usa el checklist de arriba y prueba en paralelo antes de cortar. Y si lo que quieres es aprovechar tus datos de Holded sin convertirte en mantenedor de una API, esa es exactamente la parte que Numio resuelve por ti.