Versionado

Política de versionado plano /v1 con la cabecera Factuarea-Version. Compromisos de estabilidad y deprecación.

La API de Factuarea sigue una política de URL con versionado plano (/v1) combinada con una cabecera de fecha opcional para una evolución sin cambios incompatibles. El compromiso es claro: una vez publicada, /v1 se mantiene estable. Los cambios incompatibles requieren /v2.

Versión en la URL

https://api.factuarea.com/v1/...

v1 es nuestra primera versión pública (mayo de 2026). No hay versiones anteriores accesibles.

Cuando se diseñe /v2:

/v1 y /v2 coexisten durante al menos 12 meses.
Las rutas de /v1 no cambian en esa ventana (ni payloads, ni status codes, ni campos, ni semántica).
Avisos por email a los desarrolladores con keys activas, banner en la documentación, cabeceras en las respuestas (ver más abajo).

Cabecera `Factuarea-Version`

Factuarea-Version: 2026-05-15

Opcional. Si la envías, fijas el comportamiento del subconjunto de endpoints que reciben mejoras incrementales sin cambios incompatibles (nuevos campos en la respuesta, nuevos parámetros opcionales). Sin la cabecera → obtienes la última versión por fecha.

Esto es una preparación para el patrón de "date-versioning" al estilo de Stripe. En la v1 inicial no hay diferencias entre fechas, pero la cabecera se valida si está presente.

Errores

Valor mal formado (que no sea YYYY-MM-DD, p. ej. 2026-05 o 15/05/2026) → 422 invalid_param_format con param: "Factuarea-Version".

En v1 la cabecera solo valida su formato y se registra para auditoría; todavía no cambia ninguna respuesta. Una fecha bien formada pero futura o pasada se acepta sin error.

¿Qué es un cambio incompatible?

Consideramos incompatible (prohibido en /v1):

Renombrar / eliminar campos de la respuesta JSON.
Cambiar el tipo de un campo (string → int).
Cambiar el type/code de un envoltorio de error existente.
Cambiar status codes (p. ej. devolver 201 donde antes era 200).
Convertir en obligatorio un campo de la petición que antes era opcional.
Cambiar el formato de un identificador (UUID v7 sigue siendo UUID v7).
Eliminar un endpoint sin un reemplazo documentado y una ventana de migración.
Cambiar la semántica de la máquina de estados de los documentos.

Consideramos no incompatible (permitido sin una nueva versión):

Añadir campos nuevos en las respuestas.
Añadir parámetros opcionales en las peticiones.
Añadir endpoints nuevos.
Relajar restricciones (subir un límite, aceptar más formatos).
Añadir valores de enum nuevos a campos que no sean críticos para las máquinas de estados del lado del cliente.
Mejorar los mensajes de error (cambia message, no type/code).

Política de deprecación

Cuando un endpoint o campo se marca como deprecado dentro de /v1 (p. ej. un alias heredado reemplazado por una versión canónica):

Aviso por email a los desarrolladores con keys activas afectadas.
Banner en docs.factuarea.com con el changelog.
Cabeceras en cada respuesta del endpoint deprecado durante al menos 12 meses antes de su retirada (que solo ocurre en /v2):

Deprecation: true
Sunset: Wed, 15 May 2027 00:00:00 GMT
Link: <https://docs.factuarea.com/changelog#v1-deprecations>; rel="deprecation"
Link: <https://docs.factuarea.com/guides/migration-from-holded>; rel="alternate"

En /v1 el endpoint sigue funcionando hasta el lanzamiento de /v2. Las cabeceras avisan.
En /v2 el endpoint se retira / reemplaza. La ventana entre el primer aviso y /v2 es ≥ 12 meses.

Migración entre versiones

Cada migración (v1 → v2) viene acompañada de:

Una guía dedicada en docs.factuarea.com/guides/migration-v1-v2.
Mapeo campo a campo y endpoint a endpoint.
Recomendaciones operativas (mantener ambas keys, escritura dual durante la transición).
Webhooks: los eventos antiguos conservan su forma; los eventos nuevos viven en su propia versión declarada en el payload.

Changelog

Cada cambio de /v1 (campo nuevo, deprecación, evento nuevo, corrección de validación) se publica en Changelog con etiquetas:

feature — campo / endpoint / evento nuevo.
fix — corrección de un bug.
deprecation — campo o endpoint marcado como obsoleto (todavía activo en /v1).
breaking — solo aparece en /v2, nunca dentro de /v1.
security — corrección con implicaciones de seguridad. Léela primero.

Suscríbete al feed RSS en https://docs.factuarea.com/changelog.rss o sigue @factuarea en X para los anuncios.

Compromiso de estabilidad

Una integración construida hoy contra /v1 seguirá funcionando en /v1 durante al menos 24 meses desde hoy, sin tocar tu código. Ventana de soporte para v1 → mínimo 12 meses tras el lanzamiento de v2.

Esa es la garantía. Cualquier excepción se comunicará con plazos generosos.

En esta página