Qué es la API de Holded
La API de Holded (Interfaz de Programación de Aplicaciones) te permite conectar tu cuenta con otras aplicaciones para intercambiar información automáticamente.
Es el sistema que hace posible que diferentes programas trabajen juntos e intercambien datos de forma estructurada. La API utiliza formato JSON.
Por ejemplo, puedes:
Crear contactos desde otro CRM.
Generar facturas desde un e-commerce.
Sincronizar productos o stock.
La API funciona mediante peticiones que permiten:
Obtener información (GET).
Crear datos (POST).
Actualizar datos (PUT).
Eliminar datos (DELETE).
Estas acciones se realizan sobre un endpoint específico (URL que determina la operación). Por ejemplo:
https://api.holded.com/api/v2/invoices
Aunque Holded cuenta con integraciones nativas con distintas aplicaciones, si necesitas una automatización a medida, puedes utilizar la API para conectar Holded con cualquier otro software que utilice tu empresa.
Quién puede usar la API
La API está disponible en todos los planes de pago o trial con un límite mensual según el plan de pago. Para generar una API Key debes:
Tener acceso al apartado de Desarrolladores.
Tener un plan activo distinto a Free.
☝🏼 Puedes dar acceso a usuarios con el rol de desarrollador, o bien con un rol personalizado con acceso al apartado Desarrolladores para que puedan acceder y editar la API.
Cómo generar o una API Token
Un API token es la clave que identifica tu cuenta de Holded en cada petición.
Debe incluirse en todas las llamadas a la API para indicar a qué cuenta pertenece la operación. Puedes crear tantas como sean necesarias y con permisos distintos.
Para generarla, sigue estos pasos:
Ve a tu cuenta (arriba a la izquierda) y haz clic en Configuración.
En el apartado Desarrolladores, haz clic en Credenciales.
Pulsa Agregar API Token.
Podrás seleccionar qué permisos tiene esa API Key.
☝🏼 Si necesitas acceder a la API v1 podrás acceder mediante el banner que Ir a la Api Keys v1.
Haz clic en Crear Token.
Se generará un código alfanumérico que podrás copiar.
Ten en cuenta que en la creación la visualización del API Token será única. Una vez creado, para poder copiarlo desde Holded aparecerá encriptado por seguridad con el siguiente formato <XX>.
⚠️ La API Key es un dato privado. No debes compartirla ni hacerla pública.
Cómo consultar la documentación de la API
Una vez generada la API Key, puedes consultar la documentación técnica para conocer los endpoints y acciones disponibles.
Para acceder:
Ve a Menú > Configuración.
Haz clic en Desarrolladores > Credenciales
Haz clic en </> Documentación de la API.
Desde ahí podrás consultar:
Endpoints disponibles en los distintos módulos de Holded: Ventas, inventario, Contabilidad, Tesorería, Contactos, CRM, Proyectos.
Parámetros obligatorios.
Ejemplos de llamadas.
Respuestas y códigos de error.
Cómo probar la API antes de integrarla
Antes de realizar una integración definitiva, es recomendable probar la API para verificar que las acciones que necesitas funcionan correctamente.
Puedes hacerlo desde herramientas externas como Postman.
Postman es una herramienta de testeo que permite enviar peticiones a la API y comprobar su funcionamiento antes de integrarla en un desarrollo definitivo.
Para probarla:
Descarga e instala la aplicación Postman.
Selecciona el método correspondiente (GET, POST, PUT o DELETE).
Introduce el endpoint que quieras utilizar.
En el apartado Autthorization, añade:
Auth Type > Bearer Token
Token > Api Token generada en Holded.
Añade en el Body los parámetros obligatorios.
Envía la petición y revisa la respuesta.
Asegúrate de añadir el Token completo y no encriptado por seguridad con el formato <XX> al copiarlo desde Holded.
Si todo funciona correctamente, podrás realizar la integración definitiva en tu sistema.
Límite de llamadas de API y uso
Según condiciones comerciales, existe un límite mensual según el plan contratado.
Puedes revisar los límites en la propia documentación de API o bien a través de la página de precios de Holded.
Puedes revisar tu uso mensual de la API en tu misma cuenta de Holded.
Ve a Menú > Configuración.
Haz clic en Desarrolladores > Uso de la API.
Podrás revisar las llamadas realizadas y el límite que tienes en tu cuenta.
Preguntas frecuentes y casos de uso sobre la API
¿Qué roles pueden acceder a la API?
Aquellos roles que tengan acceso al apartado de Desarrolladores, como por ejemplo el rol predeterminado de Desarrollador.
Para los roles personalizados también podrás activar la opción de Desarrolladores, con acceso a API Token o Webhooks.
⚠️ Ten en cuenta que esta opción solo aplica al acceso o edición de API V2. Cualquier usuario con rol de propietario o administrador tendrá acceso a la API V1.
¿Es posible configurar permisos por cada token?
Sí, es posible.
La API no hereda permisos por rol de usuario, pero es posible limitar la API a algunas acciones, dado que en la creación del API Token podemos escoger el acceso a los módulos permitiendo escritura, lectura o todo.
¿Hasta que período puedo utilizar la API v1?
La API key v1 seguirá disponible hasta nuevo aviso. Avisaremos con antelación antes de retirarla.
¿Qué soporte ofrece Holded para desarrollos con API?
Las integraciones mediante API deben ser realizadas por un desarrollador.
El equipo de soporte puede resolver dudas sobre campos o endpoints, pero no desarrolla integraciones personalizadas.
Si no dispones de un técnico, puedes contactar con un Solution Partner.
¿Mediante un endpoint de GET projects puedo acceder a proyectos privados?
No, no es posible. El rol de miembro en proyectos prevalece al acceso del API token a obtener información de los proyectos. Únicamente es posible a través de API obtener información de los proyectos públicos.
¿Cómo funciona la paginación?
Cuando llamas a un endpoint de listado, la respuesta incluye:
items, items, el array de resultados de la página actualcursor, cursor, una cadena opaca para pasar como parámetro en la siguiente páginahas_more, has_more, un booleano que indica si existen más resultados
De forma que puedas añadir como parámetro en relación a estas opciones para filtrar la información obtenida.
El cursor es una especie de "marcador" que señala dónde empieza la siguiente página. Es una cadena de texto sin significado legible, no hay que interpretarla.
Para pasar a la siguiente página simplemente coges el valor del cursor y lo añades como parámetro en la siguiente llamada. La API lo lee, sabe desde dónde continuar y te devuelve los siguientes resultados con un cursor nuevo. Repites el proceso hasta que has_more sea false.
Imagina que quires obtener todos los asientos contables de una cuenta entre dos fechas. Los resultados son muchos y la API los divide en páginas.
Primera llamada — sin cursor, devuelve la primera página:
GET https://api.holded.com/api/v2/ledger-entries?start_date=2025-12-31&end_date=2026-06-26&account=70500002
La API responde con los primeros resultados y al final indica que hay más información:
{ "items": [ ... ], "cursor": "697897a629cf44c5f50ff679", "has_more": true }
Segunda llamada — copias el cursor tal cual y lo añades como parámetro:
GET https://api.holded.com/api/v2/ledger-entries?start_date=2025-12-31&end_date=2026-06-26&account=70500002&cursor=697897a629cf44c5f50ff679
La API devuelve la siguiente página con un cursor nuevo:
{ "items": [ ... ], "cursor": "a1b2c3d4e5f6a7b8c9d0e1f2", "has_more": true }
Tercera llamada — repites con el nuevo cursor:
GET https://api.holded.com/api/v2/ledger-entries?start_date=2025-12-31&end_date=2026-06-26&account=70500002&cursor=a1b2c3d4e5f6a7b8c9d0e1f2
Esta vez has_more es false — ya no hay más páginas:
json
{ "items": [ ... ], "cursor": null, "has_more": false }
¿Qué parámetros puedo utilizar en el GET de libro diario?
Los parámetros de consulta actualmente disponibles son los siguientes:
start_date que es un parámetro obligatorio y permite filtrar asientos desde esta fecha
end_date que es un parámetro obligatorio y permite filtrar asientos hasta esta fecha.
cursor que es un campo opcional y permite la paginación.
limite que es un campo opcional, y permite añadir un número máximo de asientos a devolver por página. Por defecto 25, máximo 100.
account (integer) es un campo opcional. Permite filtrar asientos por número de cuenta del plan contable.
☝🏼 Es importante que el formato de la fecha aplicado sea (YYYY-MM-DD).
Puedes encontrar toda la información detallada en nuestra documentación de referencia de la API.
¿Puedo listar registros de tiempo de un proyecto con sus partes de horas e imputaciones?
Sí, es posible a través del endpoint https://api.holded.com/api/v2/projects/{projectId}/times.
Debes tener en cuenta que para usar el parámetros de fechas en este endpoint, debes utilizar la siguiente estructura:
startDate : Filtra los registros a partir de esta fecha (ISO 8601, AAAA-MM-DD)
endDate: Filtra los registros hasta esta fecha, inclusive (ISO 8601, AAAA-MM-DD)
¿Cómo puedo interpretar los errores de respuesta de la API?
Los códigos de errores más frecuentes son los siguientes:
400: Bad Request · Parámetros inválidos o cuerpo de petición mal formado
401: Unauthorized · Clave API ausente o inválida
403: Forbidden · Clave API válida pero permisos insuficientes
404: Not Found · El recurso solicitado no existe
422: Unprocessable Entity · JSON válido pero la validación semántica falló
429: Too Many Requests · Límite de tasa excedido. Espera y reintenta.
500: Internal Server Error · Algo salió mal en nuestro lado
☝🏼 La API permite 100 peticiones por minuto por clave API. Cuando excedes este límite, recibirás una respuesta 429. Espera a que se reinicie la ventana de límite antes de reintentar.