Versionado¶

Control de versión API¶

La API Pontotel utiliza versionamiento semántico Para garantizar la estabilidad y la retrocompatibilidad.

Versión estándar¶

v4.0

Base URL: https://apis.pontotel.com.br/pontotel/api/v4/

Historial de verano¶

Versión	Status	Lanzamiento	Sunset	Cambios principales
v4	Atual	Jan 2025	-	Nueva autenticación JWT, OpenAPI 3.0
v3	⚠️ Deprecated	Jun 2023	Diez 2025	Soporte webhooks
v2	❌ Sunset	Jan 2021	Jun 2023	-
v1	❌ Sunset	Mar 2019	Jan 2021	Versión inicial

Deprecación de v3

v3 se suspenderá en Diciembre de 2025. Migre para v4 cuanto antes.

Versionamiento Semántico¶

Seguimos el patrón SinVer:

Text Only
1 2	`MAJOR.MINOR.PATCH 4 . 0 . 0`

MAJOR (Quebra Compatibilidad)¶

Cambios que rompen compatibilidad:

Eliminación de variables
Cambio de estructura de responsabilidad
Cambio de tipos de datos
Eliminación de campos obligatorios

Ejemplo: v3 → v4

MINOR (Nuevas Features)¶

Nuevas funcionalidades sin romper compatibilidad:

Nuevos endpoints
Nuevos campos opcionales
Nuevos query parameters

Ejemplo: v4.0 → v4.1

PATCH (Bug Fixes)¶

Correciones de errores y mejoras:

Corrección de errores
Mejoras de rendimiento
Actualizaciones de documentación

Ejemplo: v4.0.0 → v4.0.1

Cómo especificar versión¶

En la URL (Recomendado)¶

Text Only
1 2	`https://apis.pontotel.com.br/pontotel/api/v4/usuarios/ ^^`

Via Header (Alternativo)¶

HTTP
GET /usuarios/
Host: apis.pontotel.com.br
Accept: application/json; version=4

Política de soporte¶

Período	Descripción
Active	Soporte completo, nuevas features
Maintenance	Sólo correcciones críticas y seguridad
Deprecated	Aviso de interrupción sin nuevas features
Sunset	Eliminar completamente

Timeline Típica¶

gantt
    title Ciclo de Vida de Versão da API
    dateFormat YYYY-MM
    section v4
    Active           :2025-01, 2026-12
    Maintenance      :2027-01, 2027-12
    section v3
    Active           :2023-06, 2024-12
    Deprecated       :2025-01, 2025-12
    Sunset           :2026-01, 2026-01

Migración de verano¶

Checklist de migración¶

Al migrar a una nueva versión mayor:

Ejemplo: Migración v3 → v4¶

v3 (Deprecated):

Python
# Autenticação com API Key
headers = {"X-API-Key": "sua_chave"}

v4 (Actual):

Python
# Autenticação com Bearer Token
headers = {"Authorization": f"Bearer {token}"}

Retrocompatibilidad¶

Nos comprometemos a:

Mantener versiones anteriores como mínimo 18 meses
Avisar con 6 meses de antemano sobre deprecaciones
Proporcionar guías de migración detalladas
Ofrecer soporte durante transición