Versioning¶

API Version Control¶

The Pontotel API uses semantic versioning to ensure stability and retrocompatibility.

Current Version¶

v4.0

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

Version History¶

Version	Status	Launch	Sunset	Main Changes
v4	Current	Jan 2025	- What?	New JWT authentication, OpenAPI 3.0
v3		Jun 2023	Dec 2025	Webhooks support
v2	Sunset	Jan 2021	Jun 2023	- What?
v1	Sunset	Mar 2019	Jan 2021	Initial version

V3 Deprecation

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

Semantic Versioning¶

We followed the pattern UnViewed:

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

MAJOR (Compatibility breaking)¶

Changes break compatibility:

Endpoints removal
Response structure change
Change of data types
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 Cools)¶

Bug fixes and improvements:

Bug fixing
Performance improvements
Documentation Updates

Example: v4.0.0 → v4.0.1

How to Specify Version¶

In URL (Recommended)¶

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

Via Header (Alternative)¶

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

Support Policy¶

Period	Description
Active	Full support, new features
Maintenance	Only critical corrections and security
Deprecated	Discontinuation warning without new features
Sunset	Removed completely

Typical Timeline¶

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

Version Migration¶

Migration Checklist¶

When migrating to new major version:

Example: Migration v3 → v4¶

v3 (Deprecated):

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

v4 (current):

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

Retrocompatibility¶

We commit ourselves to:

Keep previous versions by at least 18 months
Warn with 6 months in advance on precautions
Provide detailed migration guides
Provide support during transition