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¶

Versionamento Semântico¶

Seguimos o padrão SemVer:

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)¶

1
2

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

Via Header (Alternativo)¶

1
2
3

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

Política de Suporte¶

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:

• Ler changelog completo
• Identificar breaking changes
• Testar em sandbox
• Atualizar código
• Atualizar testes
• Validar em staging
• Deploy gradual em produção
• Monitorar métricas

Exemplo: Migração v3 → v4¶

v3 (Deprecated):

1
2

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

v4 (Atual):

1
2

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

Changelog¶

v4.0.0 (Janeiro 2025)¶

🎉 Novidades¶

• ✨ Autenticação JWT Bearer Token
• ✨ Especificação OpenAPI 3.0 completa
• ✨ Swagger UI interativo
• ✨ Novos endpoints de férias e afastamentos
• ✨ Suporte a webhooks v2

💥 Breaking Changes¶

• ⚠️ Removida autenticação via API Key
• ⚠️ Campo employee_id renomeado para empregado_id
• ⚠️ Endpoint /workers/ movido para /empregados/
• ⚠️ Formato de data alterado para ISO 8601

🐛 Correções¶

• 🔧 Paginação melhorada
• 🔧 Performance otimizada em listagens
• 🔧 Tratamento de erros padronizado

v3.2.0 (Junho 2024)¶

• ✨ Adicionados filtros avançados
• ✨ Exportação em CSV
• 🔧 Melhorias de performance

Notificações de Mudanças¶

Mantenha-se informado sobre mudanças:

1. Email: Inscreva-se na newsletter de desenvolvedores
2. RSS: https://docs-api.pontotel.com.br/changelog.xml
3. Webhook: Configure webhook para notificações

Ambiente de Testes¶

Sempre teste novas versões em sandbox primeiro:

1
2
3

# Sandbox com versão específica
SANDBOX_V4 = "https://sandbox-apis.pontotel.com.br/pontotel/api/v4/"
SANDBOX_V3 = "https://sandbox-apis.pontotel.com.br/pontotel/api/v3/"

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

Próximos Passos¶

• Explorar entidades →
• Ver referência completa →
• Conhecer boas práticas →