Crear clientes, planes y suscripciones mediante la API

Retrospectiva histórica: noviembre de 2025–abril de 2026
Este artículo se redactó posteriormente y reúne la ampliación documentada de los recursos de la API.

La API permite que un sistema externo mantenga sincronizados los registros principales de Alunta. Trabaja con los objetos en su orden natural: crea o encuentra al cliente, crea un plan con precios e intervalos válidos y, por último, crea la suscripción.

Para estas llamadas, utiliza el token personal del equipo de Ajustes → API. OAuth de socios es una vía de autorización independiente para integraciones de socios y no cambia cómo se crea o revoca el token API del equipo.

Clientes y correspondencias estables

Crea un cliente con un nombre; es el único campo obligatorio en el contrato OpenAPI. El correo electrónico, el teléfono, la dirección, el código postal, la ciudad y country son opcionales. Si envías country, utiliza un código ISO 3166-1 alfa-2 en mayúsculas, como DK; si lo omites, el contrato utiliza el país del equipo como valor predeterminado. El external_customer_id opcional puede contener la referencia de tu sistema. Guarda tanto la referencia externa como el UUID de Alunta; resuelven problemas distintos. No reutilices una referencia externa en varios clientes sin una regla de asignación explícita.

Planes e intervalos

Consulta primero pricing_type del plan. En un plan normal, solicita sus intervalos de renovación y utiliza un renewal_interval_uuid válido. Un plan por niveles no tiene filas de intervalos de renovación en esa colección; para crearlo, utiliza el interval y la currency documentados del precio del nivel, además de los datos de nivel requeridos. Comprueba siempre que sean compatibles el precio, la moneda, el tipo de precio y el proveedor de pago. Un plan es una descripción reutilizable de lo que se vende; no equivale al precio efectivo de un cliente ni a su fecha de inicio.

La suscripción

Cuando el cliente y el plan estén listos, crea la suscripción con el UUID del plan, el UUID del cliente y un UUID de intervalo de renovación o el par de intervalo y moneda de nivel que ofrezca el plan. Un ejemplo sintético por niveles puede utilizar los UUID ficticios e inexistentes {"plan_uuid":"00000000-0000-4000-8000-000000000002","customer_uuid":"00000000-0000-4000-8000-000000000001","interval":1,"currency":"DKK"}; consulta el esquema OpenAPI actual para conocer los nombres exactos de los campos y los endpoints posteriores de niveles. La respuesta es la fuente estable del UUID y el estado de la suscripción. Vuelve a consultarla después de crearla si la integración necesita mostrar la fecha de inicio, el precio o los datos de pago.

Los endpoints documentados de cuentas bancarias permiten crearlas, actualizarlas, consultarlas y eliminarlas. Así se mantiene sincronizada una interfaz de administración externa o ERP; crear una cuenta bancaria no mueve dinero ni cambia automáticamente el estado de pago de una factura.

Errores y límites

422 puede indicar que el código de país, la moneda, el intervalo o el proveedor de pago no son compatibles con la solicitud. Si falta un intervalo, el cliente no debe inventar una alternativa. Consulta en OpenAPI la paginación, los nombres de campo y los estados, y trata los importes con la unidad especificada en el esquema pertinente.

Consulta la guía de API pública y webhooks (Markdown-fil, AI-agentvenlig) para ver el orden actual y ejemplos con UUID sintéticos.

Ejemplo completo

Un sistema externo de ventas puede enviar primero un cliente con external_customer_id: "crm_demo_42", guardar el UUID devuelto y después solicitar los intervalos de renovación del plan. Si el plan tiene un precio en EUR para 12 meses, el cliente no debe crear la suscripción en DKK ni con un intervalo que el plan no ofrezca. Tras crearla, guarda el UUID de la suscripción y vuelve a consultar su estado. Así, un webhook posterior podrá vincularse tanto al ID de cliente externo como a las referencias propias de Alunta.

Si el cliente ya existe, la integración debe utilizar su propia correspondencia única o buscar su identidad mediante el mecanismo documentado antes de crear otro. La API no debe deduplicar solo por nombre. Si se elimina una cuenta bancaria, el cliente también debe comprobar los ajustes vigentes de cuenta bancaria estándar y uso; las operaciones CRUD de cuentas bancarias no son una orden de pago.

¿Por qué falta un intervalo? En un plan normal, falta un precio válido para el intervalo de renovación. En uno por niveles, que la colección de intervalos de renovación esté vacía es lo esperado; consulta los precios por niveles y utiliza el intervalo y la moneda.

¿Puedo cambiar un plan sin cambiar todas las suscripciones? El catálogo de planes y una suscripción existente son cosas distintas; consulta la descripción del endpoint y la respuesta de la suscripción.

¿Qué hago con 422? Muestra el error del campo, corrige la combinación no válida y vuelve a enviar la misma intención de negocio solo cuando los datos de entrada sean válidos.