Guia de Migração — pos-android-sdk para 4.20.12

Este guia cobre a atualização de qualquer versão da série 4.20.x para 4.20.12, e também traz
o diff real de build/infra em relação à 4.18.0 (última tag anterior à série 4.20.x disponível
para comparação de arquivos — lembrando que 4.18.x segue como linha de release paralela, não como
predecessora estrita).

1. Como atualizar

1.1 Bump de dependência

dependencies {
    implementation "com.stone.pos:sdk:4.20.12" // ajuste o group/artifact conforme seu setup atual
}

Sincronize o Gradle e recompile.

2. Breaking changes / pontos de atenção obrigatórios

2.1 Timestamp do StoneStart (segundos → milissegundos)

Introduzido em 4.20.1. O StoneStart passou a gerar/usar o timestamp do token de transação em
epoch milissegundos, e não mais em epoch segundos.

Ação necessária: se sua aplicação lê, loga, persiste ou compara esse timestamp manualmente
(ex.: validação de expiração de token, auditoria, envio para backend próprio), ajuste a conversão
para milissegundos. Se você apenas repassa o valor sem interpretá-lo, nenhuma ação é necessária.

// Antes (epochSeconds)
val expiresAt = tokenTimestamp + 300 // 5 min em segundos

// Depois (epochMilliseconds)
val expiresAt = tokenTimestamp + 300_000 // 5 min em milissegundos

2.2 Evento de "cartão removido" (fix da 4.20.11)

Antes da 4.20.11, em determinados fluxos o evento de remoção de cartão não era emitido pelo SDK
(o entry mode era setado depois do ponto em que a checagem de remoção ocorria).

Ação recomendada: se sua UI tinha algum workaround (timeout manual, polling, tela que nunca
saía do estado "aguardando remoção do cartão") para compensar esse bug, remova esse workaround após
migrar, e revalide o fluxo de "aguardar remoção do cartão" em testes manuais com cartão físico —
o comportamento correto agora vem nativamente do SDK.

2.3 Validação de "stone code" na ativação (fix da 4.20.7)

A validação de tamanho do "stone code" durante a ativação do POS foi removida por estar incorreta/
bloqueando ativações válidas.

Ação recomendada: se seu app tinha validação própria e redundante do tamanho do stone code
antes de chamar a ativação do SDK, revise-a — ela pode estar reproduzindo a mesma regra incorreta
e bloqueando casos válidos que agora o SDK aceita.

3. Pontos que não exigem mudança de código, mas merecem teste manual

4. Checklist de migração

• Atualizar a versão do SDK para 4.20.12 no build.gradle.

• Se vier de fora da série 4.20.x (ex.: 4.18.x) ou de uma versão 4.20.1–4.20.11,
  conferir a tabela da seção 1.2 (targetSdk, AGP, Kotlin, Koin, NDK) e rodar
  ./gradlew :app:dependencies para checar conflitos de resolução, especialmente em Koin e
  Kotlin. Se seu pipeline usa apenas mirrors públicos do Android SDK, valide especificamente a
  resolução do ndkVersion 35.0.0.

• Se importa módulos do SDK individualmente, verificar necessidade de declarar auth-gateway.

• Remover workarounds relacionados a "cartão não removido"/evento de remoção não disparado.

• Remover validações duplicadas/redundantes de tamanho do "stone code" na ativação, se houver.

• Rodar smoke tests de venda, cancelamento, voucher e PIX nos modelos de terminal usados em
  produção (priorizando os fabricantes com HAL atualizado: Gertec, Positivo, Ingenico, Tectoy,
  Sunmi).

• Validar impressão/exibição de recibo (layout e valores decimais em voucher).

• Rodar regressão completa de ativação do POS.

• Publicar em ambiente de homologação antes de produção, dado o volume acumulado de fixes
  (12 releases) entre a versão anterior e a 4.20.12.

5. Rollback

Como não há mudanças de schema/persistência reportadas além do timestamp (item 2.1), o rollback
para uma versão 4.20.x anterior é seguro na maioria dos casos — apenas revalide se algum dado
gerado com timestamp em milissegundos foi persistido e precisa ser lido por uma versão anterior
que espera segundos. Evite fazer rollback especificamente para 4.20.1–4.20.11, já que essas
versões contêm a regressão de libs corrigida na 4.20.12 (seção 1.2).