--- title: "Guia de Migração — Provider" url: "https://devcenter.stone.com.br/sdk-android-guia-de-migracao-pos-android-sdk-para-42011" image: "https://devcenter.stone.com.br/_og/d/c_Ocean.takumi,title_~R3VpYSBkZSBNaWdyYcOnw6NvIOKAlCBQcm92aWRlcg,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMzMEE2NkQifX19,p_Ii9zZGstYW5kcm9pZC1ndWlhLWRlLW1pZ3JhY2FvLXBvcy1hbmRyb2lkLXNkay1wYXJhLTQyMDExIg,s_DLd5YbmFGW8D0G9q.png" --- # Guia de Migração — Provider Este guia cobre a atualização de qualquer versão da série `4.18.x` para **4.20.16**. ## [Guia de Migração](#guia-de-migração) Este guia cobre a atualização de qualquer versão da série `4.20.x` para **4.20.15**, 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-como-atualizar) #### [1.1 Bump de dependência](#_11-bump-de-dependência) ```groovy dependencies { implementation "com.stone.pos:sdk:4.20.16" // ajuste o group/artifact conforme seu setup atual } ``` Sincronize o Gradle e recompile. ### [2\. Breaking changes / pontos de atenção obrigatórios](#_2-breaking-changes-pontos-de-atenção-obrigatórios) #### [2.1 Evento de "cartão removido" (fix da 4.20.11)](#_21-evento-de-cartão-removido-fix-da-42011) 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.2 Validação de "stone code" na ativação (fix da 4.20.7)](#_22-validação-de-stone-code-na-ativação-fix-da-4207) 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](#_3-pontos-que-não-exigem-mudança-de-código-mas-merecem-teste-manual) | Item | Versão | O que testar | | :---------------------------------------------------------------- | :-------------- | :------------------------------------------------------------------------------- | | Recibo/voucher com valores decimais (Bal/Amt) | 4.20.1 | Emitir recibo de voucher com valores fracionados e conferir formatação. | | Layout das informações do recibo | 4.20.5 | Conferir visualmente o recibo impresso/exibido em tela após transações comuns. | | Crash em transação de voucher | 4.20.4 | Rodar fluxo completo de voucher (aprovação e reversão). | | Abort/reversão não desfaz transação aprovada | 4.20.1 | Testar abort após aprovação online — a transação deve permanecer aprovada. | | PIX / Instant Payment | 4.20.1 | Confirmar que não há mais persistência indevida de authorize. | | Número de série no recibo | 4.20.1 | Verificar se o serial number aparece corretamente (não mais UNKNOWN). | | Suporte a novos hardwares (Transire Series S / T2, D400) | 4.20.1 / 4.20.6 | Se o seu parque de terminais inclui esses modelos, validar pareamento e transação nesses devices. | | HALs atualizados (Gertec, Positivo, Ingenico, Tectoy, Sunmi, PAL) | várias | Smoke test de transação (venda + cancelamento) nos modelos de terminal usados em produção, priorizando os fabricantes cujo HAL mudou. | | Suporte a páginas de memória de 16KB | 4.20.1 | Relevante apenas se o app/dispositivo já roda em Android com essa configuração; validar instalação/execução normal. | ### [4\. Checklist de migração](#_4-checklist-de-migração) - [ ] Atualizar a versão do SDK para `4.20.15` 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.15. ### [5\. Rollback](#_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.15` (seção 1.2). --- **Jornada: [Entender a SDK Android](https://devcenter.stone.com.br/sdk-android-o-que-e-a-sdk-android)** Etapa 10 de 10 [**Etapa anterior**Boas Práticas e Segurança](https://devcenter.stone.com.br/sdk-android-boas-praticas-e-seguranca) Siga a Stone nas redes sociais [](https://www.facebook.com/stonepagamentos/)[](https://x.com/sejastone/)[](https://www.instagram.com/stone/)[](https://br.linkedin.com/company/stone-co)[](https://www.youtube.com/channel/UCk4L4JykgoDkN8YeuxkNqIQ) © Stone Instituição de Pagamento S.A. CNPJ 16.501.555/0001-57 Av. Rebouças, 2880, 4º andar, Pinheiros, CEP 05.402-500 – São Paulo/SP Instituição de pagamento autorizada pelo Banco Central do Brasil, nas modalidades de credenciadora e emissora de moeda eletrônica.