Changelog y versionado API — España
Versiones de API con fecha, política de obsolescencia y cambios recientes — REST API para España.
Arquitectura — Modelo de versionado de la API España
Usamos versiones de API con fecha: Accept-Version: 2026-03-15. Dentro de una versión, los cambios son solo aditivos (nuevos campos, nuevos endpoints, nuevos enums tras flags opt-in). Las breaking changes salen como nueva versión con fecha. Tu cuenta queda pinned a la versión activa al registrarte salvo upgrade explícito. Los cambios del canal FACe/SII se versionan por separado y se exponen en el payload de la factura.
Cómo integrarlo — Política de obsolescencia
Las obsolescencias se anuncian con ≥12 meses de antelación por tres canales: banner en el dashboard, email mensual de changelog y cabecera Sunset en los endpoints afectados. Nunca eliminamos campos en silencio. Al final de vida la versión antigua devuelve 410 Gone con cabecera Link a la guía de migración. IVA 21% y otros campos fiscales de España son estables en v1 y v2.
Operación y casos límite — Cambios recientes (extracto)
2026-03-15: añadido partial_ok en pedidos, nuevo evento order.partially_shipped. 2026-01-10: añadido id de confirmación FACe/SII en el payload de factura. 2025-11-04: las idempotency keys ahora son obligatorias en POST /v1/orders (breaking; v2). Changelog completo en /docs/changelog con feeds RSS y Atom. Las adiciones al schema FACe / Suministro Inmediato de Información (SII) son non-breaking en versiones pinned.
Preguntas frecuentes
¿Cómo se pinnean las versiones?
Default de la cuenta al registrarse; override por petición vía Accept-Version. Prueba la nueva versión con cabecera antes de cambiar el default.
¿Cómo anuncian los cambios?
Banner en el dashboard, email mensual y cabecera Sunset en endpoints afectados. Nunca cambiamos comportamiento en silencio en una versión pinned.
¿Hay feed RSS?
Sí — /docs/changelog.rss y feed Atom en /docs/changelog.atom.
¿Cuánto tiempo se soportan versiones antiguas?
Mínimo 24 meses desde el sucesor; aviso de 12 meses antes del EOL.
¿Cambios en el canal FACe/SII?
Se siguen en el mismo changelog. El IVA 21% y otros campos fiscales son estables en v1 y v2.