Versionamento de API & Política LTS

Esquema de Versionamento

O qr3.app utiliza versionamento baseado em URL: /v1/, /v2/, etc.

https://qr3.app/v1/codes
                    ^^^
                    Versionspräfix

A versão estável atual é a v1 LTS .

Ciclo de Vida de Versões

Neu         → Stable (LTS) → Maintenance → End-of-Life
 Beta-Phase    Aktiv            Nur Fixes      Eingestellt
 (0–3 Monate)  (12+ Monate)     (6 Monate)     (danach)

Versão	Status	Suporte até	Notas
v1	✅ Stable (LTS)	Mín. Março de 2027	Versão de produção atual
v2	📋 Planejado	—	Roadmap: Fase 5+

Breaking Changes — Definição

Uma Breaking Change é qualquer alteração que quebre os clientes existentes sem adaptação:

Remoção ou renomeação de campos de Request/Response
Alteração de códigos de status HTTP para cenários existentes
Remoção de endpoints
Alteração do método de autenticação
Alterações incompatíveis no formato de erro

Não são Breaking Changes (extensões compatíveis):

Adição de campos opcionais de Request
Adição de novos campos de Response
Novos endpoints
Novos parâmetros de query opcionais
Novos códigos de erro (o RFC 7807 permanece compatível)

Comunicação de Breaking Changes

As Breaking Changes nunca são realizadas sem aviso prévio:

Aviso prévio: Pelo menos 90 dias antes da Breaking Change
Canal: E-mail para todos os usuários da API + banner no painel + CHANGELOG.md
Ajuda de migração: Guia de migração e exemplos de código
Headers de Deprecation: A API fornece os headers HTTP Deprecation e Sunset

HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 01 Mar 2027 00:00:00 GMT
Link: <https://docs.qr3.app/de/api/versioning>; rel="deprecation"

Garantias LTS (v1)

Para a versão LTS atual v1, aplica-se o seguinte:

Garantia	Período
Sem Breaking Changes	Mín. 12 meses a partir do status estável
Patches de segurança	Por todo o período de suporte LTS
Correções de bugs	Por todo o período de suporte LTS
Modo de manutenção	6 meses após o fim do suporte LTS
Suporte completo	Mín. até março de 2027

Identificar a Versão

Cada resposta da API contém metadados sobre a versão atual:

{
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "api_version": "1.0.0"
  }
}

O endpoint GET /v1/health fornece adicionalmente:

{
  "version": "1.0.0",
  "environment": "production",
  "status": "ok"
}

Migração entre Versões

Quando uma nova versão principal é lançada, a versão antiga permanece ativa em paralelo por pelo menos 6 meses.

Nós fornecemos:

Diff completo de todos os endpoints alterados
Ferramenta de migração automática (onde possível)
Suporte de migração personalizado para clientes Business/Agency

Política de Depreciação para Endpoints Individuais

Endpoints individuais também podem ser marcados como depreciados dentro de uma versão:

GET /v1/codes HTTP/1.1

HTTP/1.1 200 OK
Deprecation: true
Sunset: Thu, 01 Jan 2026 00:00:00 GMT
Link: <https://docs.qr3.app/de/api/codes>; rel="deprecation"

Changelog

Todas as alterações da API são documentadas no arquivo CHANGELOG.md no repositório.

Data	Versão	Tipo	Descrição
Março de 2026	v1.0.0	Inicial	Primeiro lançamento estável: QR-Codes, Redirect, Auth, Billing
Março de 2026	v1.1.0	Feature	API em lote, destinos A/B, expiração, exportação em PDF
Março de 2026	v1.2.0	Feature	Organizations, Workspaces, logs de auditoria, comentários, endpoints de GDPR

Dúvidas?

Em caso de dúvidas sobre a política de versionamento: [email protected]