# Integração de Backend: Gerenciando Solicitações de SSO

Para autorizar operações e gerenciar o acesso de usuários, você deve expor um endpoint de API no seu sistema de backend. A plataforma Tap on Phone chama este endpoint para verificar as permissões de Single Sign-On (SSO) sempre que o seu aplicativo cliente solicitar uma operação sensível, como inicializar o terminal ou processar um estorno.

Este guia mostra como implementar e configurar este endpoint para receber, validar e responder a solicitações de SSO.

## Passo 1: Configurar os requisitos do seu endpoint

O seu endpoint de backend deve atender a requisitos técnicos específicos para se comunicar com sucesso com a plataforma Tap on Phone:

* **Protocolo**: O endpoint deve usar `HTTPS`.  
* **Tempo de Resposta**: O endpoint deve processar a solicitação e responder em um máximo de **5 segundos**. Qualquer atraso além disso resulta em um erro de timeout.  
* **IP Whitelisting**: Você deve configurar o seu firewall ou proxy reverso para permitir solicitações de entrada dos seguintes endereços IP da plataforma Tap on Phone:  
  **IPs do Ambiente de Teste:** * `35.156.130.116`  
  * `35.156.242.206`

  **IPs do Ambiente de Produção:**

  * `3.124.56.20`  
  * `63.176.190.170`  
  * `18.158.202.149`  
  * `18.197.125.190`

## Passo 2: Gerenciar a solicitação recebida

Quando um usuário aciona uma ação que requer autorização (como iniciar a `InitActivity`), a plataforma Tap on Phone envia uma solicitação POST para o seu endpoint.

### Cabeçalhos

A plataforma passa o token de autenticação do usuário no cabeçalho da solicitação. Este token corresponde à string `userToken` que o seu aplicativo cliente passa durante a chamada do Intent.

```
X-Auth-Token: 1234567
```

### Corpo da Solicitação

A solicitação inclui um corpo JSON detalhando a operação solicitada e seus metadados.

```json
{
  "operation": "serviceInitialisation",
  "operationMetadata": {
    "ClientID": "4bac0922d476436697283b8238ba282b"
  }
}
```

* `operation`: O tipo de operação que o usuário está tentando realizar. Os valores suportados incluem serviceInitialisation e refund.  
* `operationMetadata`: Contém metadados contextuais, incluindo o `ClientID` da sua organização.

## Passo 3: Validar a solicitação

Ao receber a solicitação, o seu backend deve realizar os seguintes passos de validação:

1. **Autenticar o usuário**: Leia o cabeçalho X-Auth-Token e verifique se a sessão do usuário está ativa e válida dentro do seu sistema.  
2. **Autorizar a operação**: Verifique o campo operation. Determine se o usuário autenticado tem as permissões necessárias para realizar esta ação específica (por exemplo, garantir que apenas usuários administradores possam realizar um estorno).

## Passo 4: Retornar a resposta apropriada

Após validar a solicitação, você deve retornar uma resposta HTTP para instruir a plataforma Tap on Phone sobre como prosseguir.

### Resposta Bem-sucedida

Se você aprovar a solicitação, retorne um código de status HTTP 200 OK com um payload JSON contendo os seguintes campos obrigatórios:

* **merchantId**: O ID Tap to Pay (número inteiro) do estabelecimento comercial registrado na plataforma (obtido durante o processo de onboarding).  
* **userId**: O identificador único do usuário. Ele deve corresponder ao userId originalmente passado pelo seu aplicativo cliente no Intent.

```json
{
  "merchantId": 19,
  "userId": "19"
}
```

### Respostas com Erro

Se a solicitação não for autorizada ou encontrar um erro durante o processamento, o seu backend deve retornar um dos seguintes códigos de status HTTP padrão:

* **401 Unauthorized**: Use isto se o X-Auth-Token for inválido, estiver expirado ou se o usuário não tiver as permissões necessárias para a operação solicitada.  
* **405 Method Not Allowed**: Use isto se o endpoint receber um método de solicitação diferente de POST.  
* **500 Internal Server Error**: Use isto se o seu backend encontrar um problema inesperado ao processar a validação.

## Próximos Passos

Assim que o seu endpoint de SSO estiver ativo e processando corretamente as solicitações de autorização, você estará pronto para começar a iniciar intents a partir do seu aplicativo Android.

Prossiga para o [Quick Start: Your First Initialization](/pt/get-tap-on-phone/first-steps/quick-start-your-first-initialization) para inicializar a sessão do POS.