Versionado¶

Control de Versiones de la API¶

La API Pontotel utiliza versionado semántico para garantizar estabilidad y retrocompatibilidad.

Versión Actual¶

v4.0

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

Historial de Versiones¶

Versionado Semántico¶

Seguimos el estándar SemVer:

1
2

MAJOR.MINOR.PATCH
  4  .  0  .  0

MAJOR (Cambios que Rompen Compatibilidad)¶

Cambios que rompen la compatibilidad:

• Eliminación de endpoints
• Cambio de estructura de respuesta
• Cambio de tipos de datos
• Eliminación de campos obligatorios

Ejemplo: v3 → v4

MINOR (Nuevas Funcionalidades)¶

Nuevas funcionalidades sin romper la compatibilidad:

• Nuevos endpoints
• Nuevos campos opcionales
• Nuevos parámetros de consulta

Ejemplo: v4.0 → v4.1

PATCH (Correcciones de Errores)¶

Correcciones de errores y mejoras:

• Corrección de bugs
• Mejoras de rendimiento
• Actualizaciones de documentación

Ejemplo: v4.0.0 → v4.0.1

Cómo Especificar la Versión¶

En la URL (Recomendado)¶

1
2

https://apis.pontotel.com.br/pontotel/api/v4/usuarios/
                                          ^^

Vía Encabezado (Alternativo)¶

1
2
3

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

Política de Soporte¶

Línea de Tiempo Típica¶

gantt
    title Ciclo de Vida de Versión de la 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 Versiones¶

Lista de Verificación de Migración¶

Al migrar a una nueva versión mayor:

• Leer el changelog completo
• Identificar cambios que rompen compatibilidad
• Probar en sandbox
• Actualizar código
• Actualizar pruebas
• Validar en staging
• Deploy gradual en producción
• Monitorear métricas

Ejemplo: Migración v3 → v4¶

v3 (Deprecated):

1
2

# Autenticación con API Key
headers = {"X-API-Key": "tu_clave"}

v4 (Actual):

1
2

# Autenticación con Bearer Token
headers = {"Authorization": f"Bearer {token}"}

Changelog¶

v4.0.0 (Enero 2025)¶

🎉 Novedades¶

• ✨ Autenticación JWT Bearer Token
• ✨ Especificación OpenAPI 3.0 completa
• ✨ Swagger UI interactivo
• ✨ Nuevos endpoints de vacaciones y ausencias
• ✨ Soporte a webhooks v2

💥 Cambios que Rompen Compatibilidad¶

• ⚠️ Eliminada autenticación vía API Key
• ⚠️ Campo employee_id renombrado a empregado_id
• ⚠️ Endpoint /workers/ movido a /empregados/
• ⚠️ Formato de fecha cambiado a ISO 8601

🐛 Correcciones¶

• 🔧 Paginación mejorada
• 🔧 Rendimiento optimizado en listados
• 🔧 Manejo de errores estandarizado

v3.2.0 (Junio 2024)¶

• ✨ Añadidos filtros avanzados
• ✨ Exportación en CSV
• 🔧 Mejoras de rendimiento

Notificaciones de Cambios¶

Mantente informado sobre los cambios:

1. Email: Suscríbete al boletín de desarrolladores
2. RSS: https://docs-api.pontotel.com.br/changelog.xml
3. Webhook: Configura webhook para notificaciones

Entorno de Pruebas¶

Siempre prueba nuevas versiones en sandbox primero:

1
2
3

# Sandbox con versión específica
SANDBOX_V4 = "https://sandbox-apis.pontotel.com.br/pontotel/api/v4/"
SANDBOX_V3 = "https://sandbox-apis.pontotel.com.br/pontotel/api/v3/"

Retrocompatibilidad¶

Nos comprometemos a:

• ✅ Mantener versiones anteriores por al menos 18 meses
• ✅ Avisar con 6 meses de anticipación sobre deprecaciones
• ✅ Proporcionar guías de migración detalladas
• ✅ Ofrecer soporte durante la transición

Próximos Pasos¶

• Explorar entidades →
• Ver referencia completa →
• Conocer buenas prácticas →