Versionamento¶

Controle de Versão da API¶

A API Pontotel utiliza versionamento semântico para garantir estabilidade e retrocompatibilidade.

Versão Atual¶

v4.0

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

Histórico de Versões¶

Versão	Status	Lançamento	Sunset	Mudanças Principais
v4	✅ Atual	Jan 2025	-	Nova autenticação JWT, OpenAPI 3.0
v3	⚠️ Deprecated	Jun 2023	Dez 2025	Suporte a webhooks
v2	❌ Sunset	Jan 2021	Jun 2023	-
v1	❌ Sunset	Mar 2019	Jan 2021	Versão inicial

Deprecação da v3

A v3 será descontinuada em Dezembro de 2025. Migre para v4 o quanto antes.

Versionamento Semântico¶

Seguimos o padrão SemVer:

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

MAJOR (Quebra Compatibilidade)¶

Mudanças que quebram compatibilidade:

Remoção de endpoints
Alteração de estrutura de response
Mudança de tipos de dados
Remoção de campos obrigatórios

Exemplo: v3 → v4

MINOR (Novas Features)¶

Novas funcionalidades sem quebrar compatibilidade:

Novos endpoints
Novos campos opcionais
Novos query parameters

Exemplo: v4.0 → v4.1

PATCH (Bug Fixes)¶

Correções de bugs e melhorias:

Correção de bugs
Melhorias de performance
Atualizações de documentação

Exemplo: v4.0.0 → v4.0.1

Como Especificar Versão¶

Na 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 Suporte¶

Período	Descrição
Active	Suporte completo, novas features
Maintenance	Apenas correções críticas e segurança
Deprecated	Aviso de descontinuação, sem novas features
Sunset	Removida 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

Migração de Versões¶

Checklist de Migração¶

Ao migrar para nova versão major:

Exemplo: Migração v3 → v4¶

v3 (Deprecated):

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

v4 (Atual):

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

Retrocompatibilidade¶

Comprometemo-nos a:

✅ Manter versões anteriores por no mínimo 18 meses
✅ Avisar com 6 meses de antecedência sobre deprecações
✅ Fornecer guias de migração detalhados
✅ Oferecer suporte durante transição