URL base única, paginación por cursor, errores estructurados y un servidor MCP en camino. Te contamos qué cambia técnicamente, qué trampas reales hay al migrar y por qué el MCP nativo cambia la conversación con IA.
El portal anterior developers.holded.com ya se retiró. La v1 sigue accesible como referencia archivada (5 product APIs, 136 endpoints) y las integraciones existentes siguen funcionando. Todo desarrollo nuevo va a v2 y, según la propia documentación, las integraciones nuevas deberían usarla directamente.
No solo cambia la URL. Hay cambios estructurales que rompen código si no se revisa.
Varias superficies por producto (Invoice API, CRM API, Projects API, Team API, Accounting API)
URL base única consolidada con secciones (Contabilidad, Tesorería, Ventas, Inventario, Contactos, CRM, Proyectos, Equipo y RRHH, Calendario, Bandeja de entrada)
Cambia tu base URL y los prefijos de ruta. Trabajo de buscar y reemplazar, pero hay que repasar todo.
Paginación por offset (page=1, page=2, …)
Paginación por cursor (next_cursor opaco)
Eficiente con listas grandes, pero rompe cualquier código que asumiera saltar a página N o calcular total de páginas.
Mensajes de error ad hoc por endpoint
Errores estructurados con códigos consistentes
Tu manejo de errores anterior puede no reconocer los nuevos formatos. Repaso obligatorio.
Operaciones individuales en su mayoría
Operaciones bulk para facturas (cancelar, aprobar, eliminar en lote)
Optimización clara para cargas grandes. Cuidado con la idempotencia en reintentos parciales.
Inventario básico
Multi-almacén con niveles de stock, stock en tránsito, almacenes con CRUD completo
Casos que en v1 requerían lógica externa ahora se resuelven con un endpoint nativo.
Webhooks limitados o inexistentes según el área
Webhooks documentados como próximos
Mientras tanto, polling con cursor. Cuando lleguen los webhooks nativos, migración por componente.
Sin protocolo estándar para agentes IA
Servidor MCP (Model Context Protocol) anunciado como próximo
Cambia la conversación con IA: tu asistente podrá leer y actuar sobre Holded sin wrappers REST a medida.
Facturas recurrentes con lógica limitada
Calendario de recurrencia consultable y omisión de ocurrencias puntuales
Casos de suscripciones SaaS y servicios profesionales se vuelven mucho más manejables.
Adjuntos limitados
Adjuntos nativos en facturas, compras, presupuestos, proformas, rectificativas, pedidos y albaranes
Casos de trazabilidad documental dejan de requerir almacenamiento externo paralelo.
Sales pipelines manuales
Pipelines configurables en cada tipo de documento (factura, presupuesto, proforma, pedido, albarán)
El CRM y la facturación comparten estado real, no copias.
MCP (Model Context Protocol) es un estándar abierto promovido por Anthropic para que agentes de IA accedan a sistemas externos con herramientas tipadas y permisos controlados. Que Holded esté preparando un servidor MCP nativo significa una cosa concreta para tu negocio:
En francodesystems llevamos agentes propios con la SDK de Anthropic en producción. Cuando Holded publique su MCP, podemos conectarlo a tu equipo en días, no en meses.
Un "USB-C para asistentes IA": un protocolo único para que cualquier modelo se conecte a cualquier sistema con herramientas tipadas, sin reinventar la integración cada vez.
Anthropic (Claude). Adoptado ya por OpenAI, Cursor, Zed, GitHub Copilot, Replit y un ecosistema creciente de SaaS B2B.
Es el caso que más nos llega. Funciona y nadie quiere tocarlo, pero la paginación inicial al sincronizar productos o catálogos se va a romper en cuanto crezcas. Recomendamos migrar dentro de un trimestre, no bajo presión.
Aquí la paginación por offset de v1 era el cuello de botella. v2 con cursor es donde más mejora vais a notar. Migración relativamente barata porque no escribe — riesgo bajo.
Cero discusión: directamente v2. No tiene sentido empezar nada en v1 si vas a tener que migrar en algún momento.
Espera al servidor MCP. Cualquier wrapper REST que construyas ahora va a quedar obsoleto. En el ínterin, definimos el alcance y validamos casos de uso, pero no construimos plomería que se va a tirar.
Una migración de API que escribe datos no puede hacerse con corte seco. Lo que hacemos en cada proyecto:
Holded mantiene la documentación v1 como archivo público para que las integraciones existentes sigan funcionando. No hay una fecha de apagado anunciada, pero el portal anterior developers.holded.com ya se retiró y todo el desarrollo nuevo va exclusivamente a v2. La recomendación oficial es que las integraciones nuevas usen v2 y que las antiguas planifiquen migración cuando aborden cualquier cambio mayor.
Tres cambios estructurales que afectan a código existente: URL base única consolidada (antes había varias superficies por producto), paginación por cursor en vez de offset (más eficiente con listas grandes pero requiere repensar bucles que asumían páginas numeradas) y respuestas de error estructuradas (códigos y campos consistentes en vez de mensajes ad hoc por endpoint). Además v2 amplía cobertura con operaciones bulk, pipelines de documentos, multi-almacén con tracking, facturas recurrentes con calendario y adjuntos nativos.
MCP es Model Context Protocol, un estándar abierto promovido por Anthropic para que agentes de IA (Claude, ChatGPT vía adaptadores, agentes a medida) accedan a sistemas externos con herramientas tipadas y permisos controlados. Que Holded anuncie un servidor MCP nativo significa que en cuestión de meses cualquier asistente conectado podrá leer facturas, productos o asientos contables sin que tengas que escribir un wrapper REST por cada caso. Para empresas que estén pensando en asistente interno con Claude o agente para asesoría, conviene esperar al MCP nativo en vez de invertir en wrappers que quedarán obsoletos.
Holded los anuncia como próximos. Hasta entonces, las integraciones serias siguen apoyándose en polling con cursor (más eficiente que el polling con offset de v1) o, según el caso, en triggers desde el lado del sistema origen (Shopify, Stripe, etc.) que entran a una cola persistida. Cuando los webhooks nativos lleguen, la migración del polling al webhook se hace por componente, sin tocar el resto del flujo.
Los principales: bucles de paginación rotos por el cambio offset→cursor, mapeos de campos que cambiaron de nombre o estructura, manejo de errores que asumía los textos antiguos, y sobre todo idempotencia — si la v1 te garantizaba un comportamiento determinado y la v2 lo cambia (por ejemplo en bulk operations), puedes acabar duplicando documentos en reintentos. Recomendamos siempre periodo paralelo: el flujo v1 sigue produciendo y la v2 escribe a un entorno de staging hasta que validas que ambos cuadran.
Independientes. Verifactu es un requisito fiscal regulado por el RD 1007/2023 y modificaciones posteriores (obligatorio enero 2027 sociedades, julio 2027 autónomos según RD-ley 15/2025). Holded gestiona el cumplimiento desde el ERP y es Colaborador Social oficial AEAT. La API v2 da las herramientas técnicas para integrar el flujo desde fuera (ecommerce, pasarela, etc.) sin romper la cadena Verifactu. Una integración mal hecha contra v2 puede dejar facturas sin huella encadenada, así que el cumplimiento se valida igual en ambas versiones de API.
Precio cerrado tras diagnóstico, no por horas. La complejidad real depende de cuántos endpoints v1 uses, si hay paginación intensiva, si hay bulk operations y si tu integración escribe (más sensible) o solo lee. Sale gratis el diagnóstico de 30 minutos donde te decimos el alcance exacto.
En 30 minutos te decimos si toca migrar ya o puede esperar, y qué riesgos reales hay según tu uso actual.
