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-06-01

El date-versioning funciona al estilo de Stripe. Hay un registro de versiones soportadas (fechas YYYY-MM-DD); hoy hay una sola, 2026-06-01, que es también la última. La versión que aplica a una petición — la versión efectiva — se resuelve en este orden:

La cabecera de petición Factuarea-Version, si la envías.
Si no, la versión fijada en tu API key (se establece al crear la key; null significa "siempre la última").
Si no, la última versión del registro.

La versión efectiva se devuelve en cada respuesta en la cabecera Factuarea-Version, así siempre sabes qué versión por fecha sirvió tu petición.

Factuarea-Version: 2026-06-01

Fijar una versión (por cabecera o en la key) congela el comportamiento del subconjunto de endpoints que reciben mejoras incrementales sin cambios incompatibles (nuevos campos en la respuesta, nuevos parámetros opcionales). Sin cabecera ni fijación, obtienes la última versión.

El registro tiene hoy dos fechas: 2026-06-01 (la predeterminada, y la que obtienes sin cabecera ni fijación) y 2026-09-01. Optar por la más reciente cambia dos cosas, y ninguna más:

Cambio en `2026-09-01`	Qué obtienes en `2026-06-01`
Las respuestas de borrado masivo usan la forma transversal de éxito parcial `{total, successful, failed, failures[{id, error_code, error_message}]}`.	La forma anterior `{object: "bulk_delete_result", deleted, failed[{id, reason}]}`.
Los cinco errores preexistentes de los gates de cobro (`payment_method_required`, `seat_charge_failed`, `gestoria_plan_required`, `employee_seat_payment_method_required`, `employee_seat_charge_failed`) llevan `error.type: "payment_required_error"`.	`error.type: "invalid_request_error"` en esos cinco, exactamente como antes.

La reclasificación del error no toca error.code, error.subcode ni el estado HTTP — son 402 con el mismo código en todas las versiones. Si ramificas por code (que es lo que recomendamos), no cambia nada para ti en ningún caso. addon_required es un código posterior y lleva siempre payment_required_error.

Errores

La cabecera se valida contra el registro:

Valor mal formado (que no sea YYYY-MM-DD, p. ej. 2026-05 o 15/05/2026) → 400 parameter_invalid_format con param: "Factuarea-Version".
Bien formado pero no soportado (una fecha válida que no está en el registro) → 400 unsupported_api_version con param: "Factuarea-Version".

Omitir la cabecera nunca es un error — cae a la fijación de la key o a la última versión.

¿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).
Reclasificar el type de un envelope de error existente detrás de una versión por fecha: las keys fijadas a una fecha anterior siguen recibiendo el type previo tal cual, y code/subcode/estado no se mueven. Así se recategorizaron los cinco errores de cobro en 2026-09-01. Hacerlo sin versión por fecha es el caso incompatible que aparece arriba.

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