Primeros pasos con la API pública de Alunta

Retrospectiva histórica: noviembre de 2025
Este artículo se redactó posteriormente y describe el acceso a la API tal como se incorporó durante el periodo indicado.

La API conecta Alunta con un sistema que gestionas. Utilízala para leer los datos del equipo y ejecutar las acciones permitidas por el contrato v1 actual. La referencia de la API pública y el documento OpenAPI son las fuentes autoritativas de campos, estados y respuestas.

Antes de la primera solicitud

Activa el módulo API para el equipo y ve a Ajustes → API. Crea un token de API personal indicando un nombre y cópialo cuando se muestre. El token es secreto: guárdalo en un gestor de secretos o en una variable de entorno; nunca lo incluyas en el código fuente, una URL, los registros ni un ejemplo de soporte. Durante el desarrollo, utiliza una cuenta de prueba independiente. Las integraciones de socios pueden tener un flujo de autorización OAuth distinto; no es lo mismo que el token de API personal del equipo.

La base de la versión v1 es /api/v1. Una solicitud mínima es:

GET /api/v1/customers
Authorization: Bearer {access-token}
Accept: application/json

Guarda los UUID que devuelve la API y utilízalos en consultas posteriores. Los ID internos de base de datos no son referencias públicas y no se deben usar como claves estables.

Consulta primero el contrato

Antes de crear una solicitud, abre la referencia de la API pública o la especificación OpenAPI. Comprueba los campos, la paginación, la validación y la respuesta del recurso. Cuando lo indique el contrato, los importes de la API se expresan en la unidad menor de la moneda; por ejemplo, 10000 DKK normalmente significa 100,00 DKK.

401 suele indicar que falta el token o que ha caducado. 403 indica permisos insuficientes o que el equipo no dispone del módulo API. Para 422, consulta los errores de campo y corrige la solicitud. Respeta Retry-After después de un 429 y reintenta solo las operaciones que sea seguro repetir.

Cuando la integración esté en funcionamiento

Utiliza la paginación documentada para cada endpoint y no supongas que todas las colecciones admiten los mismos filtros. Utiliza webhooks para recibir eventos en vez de consultar la API sin necesidad y haz que el receptor sea idempotente. Mantén el cliente actualizado con el registro de cambios público y la documentación del contrato.

Puedes revocar un token personal en cualquier momento desde Ajustes → API. Esto detiene las solicitudes que lo utilizan; crea otro token y actualiza el secreto de la integración si la conexión debe continuar.

Consulta la guía actual de API pública y webhooks (Markdown-fil, AI-agentvenlig) para ver el flujo completo y resolver problemas.

Un primer flujo seguro

Empieza con GET /api/v1/ping o GET /api/v1/me si el token tiene acceso a esos endpoints y continúa con GET /api/v1/customers. Guarda en la integración el estado de la respuesta y el identificador de solicitud, pero nunca el token. Si una colección tiene varias páginas, sigue la paginación documentada para ese endpoint y detente únicamente cuando ya no haya una página siguiente.

Una prueba con el UUID ficticio e inexistente 00000000-0000-4000-8000-000000000001 de un cliente debe gestionar tanto 404 como 422 sin crear automáticamente otro cliente. 404 significa que el recurso no existe en el contexto de equipo del token. 422 significa que los datos o la acción no son válidos. Muestra la diferencia en la interfaz de administración para que el usuario sepa si debe corregir el acceso o los datos introducidos.

¿Se puede utilizar un token para todos los equipos? No. El acceso está vinculado al contexto del equipo. Selecciona la cuenta correcta y crea el acceso adecuado.

¿Un UUID es lo mismo que un ID externo? No. El UUID es la referencia de Alunta; un ID externo opcional sirve para establecer la correspondencia con tu sistema.

¿Debo reintentar todos los errores 5xx? Utiliza reintentos limitados para errores de red y respuestas 5xx temporales, pero no repitas a ciegas una acción que pueda crear un recurso nuevo.