Saltearse al contenido
qr3.app Docs

Versionado de API y política LTS

Versionado de API y política LTS

Esquema de versionado

qr3.app utiliza versionado basado en URL: /v1/, /v2/, etc.

https://qr3.app/v1/codes
                    ^^^
                    Versionspräfix

La versión estable actual es v1 LTS .

Ciclo de vida de las versiones

Neu         → Stable (LTS) → Maintenance → End-of-Life
 Beta-Phase    Aktiv            Nur Fixes      Eingestellt
 (0–3 Monate)  (12+ Monate)     (6 Monate)     (danach)
VersiónEstadoSoporte hastaNotas
v1✅ Stable (LTS)Mín. marzo de 2027Versión de producción actual
v2📋 Planificado—Roadmap: Fase 5+

Breaking Changes — Definición

Un Breaking Change es cualquier cambio que rompa los clientes existentes sin una adaptación previa:

  • Eliminación o renombrado de campos de Request/Response
  • Cambio de códigos de estado HTTP para escenarios existentes
  • Eliminación de endpoints
  • Cambio del método de autenticación
  • Cambios incompatibles en el formato de errores

No se consideran Breaking Changes (extensiones compatibles):

  • Adición de campos opcionales de Request
  • Adición de nuevos campos de Response
  • Nuevos endpoints
  • Nuevos parámetros de consulta (query parameters) opcionales
  • Nuevos códigos de error (RFC 7807 sigue siendo compatible)

Comunicación de Breaking Changes

Los Breaking Changes nunca se realizan sin previo aviso:

  1. Aviso: Al menos 90 días antes del Breaking Change
  2. Canal: Correo electrónico a todos los usuarios de la API + banner en el panel de control + CHANGELOG.md
  3. Ayuda de migración: Guía de migración y ejemplos de código
  4. Cabeceras de depreciación: La API proporciona las cabeceras HTTP Deprecation y Sunset
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 01 Mar 2027 00:00:00 GMT
Link: <https://docs.qr3.app/de/api/versioning>; rel="deprecation"

Garantías LTS (v1)

Para la versión LTS actual v1 se aplica lo siguiente:

GarantíaPeríodo
Sin Breaking ChangesMín. 12 meses desde el estado Stable
Parches de seguridadDurante todo el período de soporte LTS
Corrección de erroresDurante todo el período de soporte LTS
Modo de mantenimiento6 meses después del fin de LTS
Soporte completoMín. hasta marzo de 2027

Cómo identificar la versión

Cada respuesta de la API contiene metadatos sobre la versión actual:

{
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "api_version": "1.0.0"
  }
}

El endpoint GET /v1/health también proporciona:

{
  "version": "1.0.0",
  "environment": "production",
  "status": "ok"
}

Migración entre versiones

Cuando se lanza una nueva versión principal, la versión anterior permanece activa en paralelo durante al menos 6 meses.

Proporcionamos:

  • Diff completo de todos los endpoints modificados
  • Herramienta de migración automática (cuando sea posible)
  • Soporte de migración personalizado para clientes Business/Agency

Política de depreciación para endpoints individuales

Los endpoints individuales también pueden marcarse como obsoletos (deprecated) dentro de una misma versión:

GET /v1/codes HTTP/1.1


HTTP/1.1 200 OK
Deprecation: true
Sunset: Thu, 01 Jan 2026 00:00:00 GMT
Link: <https://docs.qr3.app/de/api/codes>; rel="deprecation"

Registro de cambios (Changelog)

Todos los cambios de la API se documentan en el archivo CHANGELOG.md del repositorio.

FechaVersiónTipoDescripción
Marzo de 2026v1.0.0InicialPrimer lanzamiento estable: códigos QR, redirección, Auth, Billing
Marzo de 2026v1.1.0CaracterísticaAPI por lotes (Batch-API), destinos A/B, expiración, exportación a PDF
Marzo de 2026v1.2.0CaracterísticaOrganizations, Workspaces, registros de auditoría (Audit-Logs), comentarios, endpoints de RGPD

¿Preguntas?

Si tienes preguntas sobre la política de versionado: [email protected]