# Arquitetura

Esta página explica os componentes arquitetônicos e o fluxo de comunicação que alimentam a integração do Get Tap on Phone (App2App). Entender esta arquitetura ajuda você a projetar uma integração robusta entre seu aplicativo Android, o aplicativo Tap on Phone e seus sistemas de backend.

## Os Componentes Principais

A integração App2App depende de quatro componentes distintos trabalhando juntos para autorizar e processar um pagamento de forma segura.

1. **Seu Aplicativo (Client App)** Este é o seu aplicativo Android de Registro de Caixa Eletrônico (ECR) ou Ponto de Venda (POS). Ele atua como a interface principal para o lojista. Ele gerencia a sessão do usuário, o carrinho de compras e inicia solicitações de pagamento ou inicialização.  
2. **Aplicativo Tap on Phone (Whitelabel App)** Este é o aplicativo de pagamento seguro instalado no mesmo dispositivo Android. Ele permanece inativo até que seu aplicativo o chame. Uma vez invocado, ele assume o controle da tela para gerenciar tarefas seguras, como leitura de cartão NFC e inserção de PIN, e então retorna o resultado para o seu aplicativo.  
3. **Backend do Tap on Phone** Esta plataforma baseada em nuvem roteia os dados da transação para as redes adquirentes e gerencia a configuração do terminal móvel. Crucialmente, ela intercepta as solicitações do aplicativo Tap on Phone e pede permissão ao seu backend para prosseguir.  
4. **Seu Backend (Client Backend)** Esta é a infraestrutura de servidor da sua organização. Ela hospeda o endpoint de autorização de Single Sign-On (SSO). Ela valida a sessão do usuário e aprova ou nega operações sensíveis com base nas permissões do lojista.

## O Fluxo de Comunicação

Como o aplicativo Tap on Phone opera de forma segura e independente, ele depende do seu aplicativo e do seu backend para autenticar o usuário.

Aqui está a sequência de eventos quando seu aplicativo solicita uma operação protegida (como inicializar o terminal ou processar um estorno):

1. **Iniciação**: Seu aplicativo envia uma solicitação para o aplicativo Tap on Phone no dispositivo local, passando o `userId`, `merchantId` e um `userToken` seguro.  
2. **Solicitação de Validação**: O aplicativo Tap on Phone encaminha esta solicitação para o Backend do Tap on Phone.  
3. **Solicitação de Permissão de SSO**: O Backend do Tap on Phone usa o `ClientID` para localizar seu endpoint de SSO específico. Ele envia uma solicitação de API para o seu backend contendo o `userToken` e a operação solicitada.  
4. **Autorização**: Seu backend verifica o token e as permissões do usuário, retornando uma resposta HTTP `200 OK` se aprovado.  
5. **Execução**: O Backend do Tap on Phone sinaliza para o aplicativo Tap on Phone prosseguir com a operação.  
6. **Conclusão**: O aplicativo Tap on Phone executa a operação (ex: configurar o terminal ou solicitar um cartão) e retorna o resultado final para o seu aplicativo.

## Padrões de Comunicação do Android

Para facilitar a comunicação local entre seu aplicativo e o aplicativo Tap on Phone, a integração usa mecânicas padrão do Android.

### Intents e a Activity Result API

Para operações síncronas que exigem uma interface de usuário — como inicializar o aplicativo ou processar um pagamento — você usa **Android Intents**.

Para receber o resultado desses intents, você deve usar as modernas **Activity Result APIs** (introduzidas no AndroidX Activity `1.2.0` e Fragment `1.3.0`).

* Você inicia o intent usando um launcher registrado.  
* O aplicativo Tap on Phone processa a solicitação e finaliza sua activity.  
* Seu callback registrado recebe um `RESULT_OK` (sucesso) ou `RESULT_CANCELED` (falha ou cancelamento pelo usuário), junto com um `Intent` contendo os dados detalhados da resposta (extras).

### Broadcast Receivers

Para operações assíncronas ou tarefas em segundo plano que não requerem uma interface de usuário imediata, a integração usa **Broadcasts**.

Você usa broadcasts para:

* **Verificar o Status do POS**: Verificar se o terminal está totalmente inicializado antes de tentar uma transação.  
* **Acionar Atestações**: Forçar uma verificação de segurança em segundo plano para evitar atrasos durante o fluxo de checkout.  
* **Recuperar o Status da Transação**: Consultar o status de um UUID de transação específico se o seu aplicativo falhou (crashed) ou perdeu o Activity Result original.  
* **Redefinir o POS**: Limpar a sessão do usuário atual e a configuração.

Quando você envia uma solicitação de broadcast para o aplicativo Tap on Phone, você pode fornecer uma string `ResponseAction` personalizada. O aplicativo Tap on Phone realiza a ação solicitada em segundo plano e emite um broadcast de resposta usando exatamente essa string, permitindo que seu aplicativo escute o resultado.