Skip to content

Versioning

API Version Control

The Pontotel API uses semantic versioning to ensure stability and backward compatibility.

Current Version

v4.0

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

Version History

Version Status Release Sunset Main Changes
v4 ✅ Current Jan 2025 - New JWT authentication, OpenAPI 3.0
v3 ⚠️ Deprecated Jun 2023 Dec 2025 Webhook support
v2 ❌ Sunset Jan 2021 Jun 2023 -
v1 ❌ Sunset Mar 2019 Jan 2021 Initial version

v3 Deprecation

v3 will be discontinued in December 2025. Migrate to v4 as soon as possible.

Semantic Versioning

We follow the SemVer standard:

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

MAJOR (Breaking Changes)

Changes that break compatibility:

  • Endpoint removal
  • Response structure changes
  • Data type changes
  • Removal of required fields

Example: v3 → v4

MINOR (New Features)

New features without breaking compatibility:

  • New endpoints
  • New optional fields
  • New query parameters

Example: v4.0 → v4.1

PATCH (Bug Fixes)

Bug fixes and improvements:

  • Bug fixes
  • Performance improvements
  • Documentation updates

Example: v4.0.0 → v4.0.1

How to Specify Version

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

Via Header (Alternative)

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

Support Policy

Period Description
Active Full support, new features
Maintenance Critical fixes and security only
Deprecated Discontinuation notice, no new features
Sunset Completely removed

Typical Timeline

gantt
    title API Version Lifecycle
    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

Version Migration

Migration Checklist

When migrating to a new major version:

  • Read complete changelog
  • Identify breaking changes
  • Test in sandbox
  • Update code
  • Update tests
  • Validate in staging
  • Gradual production deploy
  • Monitor metrics

Example: Migration v3 → v4

v3 (Deprecated):

Python
1
2
# API Key authentication
headers = {"X-API-Key": "your_key"}

v4 (Current):

Python
1
2
# Bearer Token authentication
headers = {"Authorization": f"Bearer {token}"}

Changelog

v4.0.0 (January 2025)

🎉 New Features

  • ✨ JWT Bearer Token authentication
  • ✨ Complete OpenAPI 3.0 specification
  • ✨ Interactive Swagger UI
  • ✨ New vacation and absence endpoints
  • ✨ Webhooks v2 support

💥 Breaking Changes

  • ⚠️ API Key authentication removed
  • ⚠️ employee_id field renamed to empregado_id
  • ⚠️ /workers/ endpoint moved to /empregados/
  • ⚠️ Date format changed to ISO 8601

🐛 Fixes

  • 🔧 Improved pagination
  • 🔧 Optimized listing performance
  • 🔧 Standardized error handling

v3.2.0 (June 2024)

  • ✨ Added advanced filters
  • ✨ CSV export
  • 🔧 Performance improvements

Change Notifications

Stay informed about changes:

  1. Email: Subscribe to the developer newsletter
  2. RSS: https://docs-api.pontotel.com.br/changelog.xml
  3. Webhook: Configure webhook for notifications

Test Environment

Always test new versions in sandbox first:

Python
1
2
3
# Sandbox with specific version
SANDBOX_V4 = "https://sandbox-apis.pontotel.com.br/pontotel/api/v4/"
SANDBOX_V3 = "https://sandbox-apis.pontotel.com.br/pontotel/api/v3/"

Backward Compatibility

We commit to:

  • ✅ Maintaining previous versions for at least 18 months
  • ✅ Providing 6 months advance notice about deprecations
  • ✅ Providing detailed migration guides
  • ✅ Offering support during transition

Next Steps