# Arquitetura da API Cloud

A Get Smart API Cloud foi projetada para preencher a lacuna entre o seu software de gestão baseado na nuvem e os terminais de pagamento físicos (TPV-PC). Ao contrário das APIs puramente de e-commerce, onde as transações ocorrem instantaneamente no navegador, os pagamentos físicos exigem interação humana (inserção de cartão, digitação de PIN).

Para acomodar isso, a API utiliza uma **arquitetura assíncrona de duas fases**. Entender esse fluxo é essencial para evitar erros comuns de integração, como presumir que uma transação está concluída ao receber a resposta HTTP inicial.

## Fluxo de Dados de Alto Nível

O ciclo de vida de uma transação envolve três partes: Sua **Aplicação**, a **API Cloud** e o **Terminal Físico**.

1. **Iniciação (Síncrona):** Sua aplicação envia uma requisição para a Cloud.  
2. **Processamento (Físico):** A Cloud instrui o Terminal a ser ativado. O cliente interage com o dispositivo.  
3. **Conclusão (Assíncrona):** A Cloud notifica sua aplicação sobre o resultado final.

## Fase 1: A Requisição Síncrona

Quando você envia uma requisição (ex.: para `/pago`), a API Cloud realiza uma verificação de validação imediata.

* **O que acontece:** O sistema verifica suas credenciais, a assinatura da mensagem e o formato JSON.  
* **A Resposta:** Você recebe uma resposta HTTP 200 OK imediata com um código de resultado.  
* **Conceito Crucial:** Um código de resultado `"0"` **não significa que o pagamento foi aprovado**. Significa simplesmente **"Requisição Recebida e Validada."**

```
// Example Synchronous Response
{
    "resultado": {
        "codigo": "0" // The command was successfully queued for the terminal.
    }
}
```

<Callout type="warning">

Não trate esta resposta como um recibo. Nesta fase, nenhum dinheiro foi movimentado. O terminal pode nem ter acendido ainda. Você deve atualizar o status local do seu pedido para "Pendente" ou "Em Andamento".

</Callout>

## Fase 2: A Notificação Assíncrona

Uma vez que a fase síncrona é concluída, a API Cloud envia o comando para o ID do terminal específico definido na sua requisição.

1. **Interação:** O terminal solicita a ação ao usuário. O usuário insere seu cartão e digita seu PIN.  
2. **Geração de Resultado:** O terminal comunica o resultado (Aprovada, Negada, Cancelada) de volta para a Cloud.  
3. **Notificação:** A API Cloud envia uma requisição `POST` para a `urlNotificacion` que você definiu na sua requisição inicial.

Esta notificação contém o resultado **final** da transação, incluindo códigos de autorização, dados do recibo e detalhes do cartão.

### Fallback de Notificação

O sistema é projetado para garantir que você receba o resultado mesmo se o seu servidor estiver inacessível.

* **Canal Principal:** `urlNotificacion` (HTTP POST).  
* **Canal Secundário:** Se a chamada para a sua URL falhar (ex.: seu servidor está inoperante ou retorna um erro), o sistema tenta enviar um e-mail para o endereço definido em `correoNotificacion`.

## Requisitos do Sistema

Para participar desta arquitetura, sua integração deve atender a restrições específicas definidas no padrão.

### Rede e Segurança

* **Protocolo:** Todas as conexões devem ser protegidas via **TLS 1.2** ou superior.  
* **Acesso:** A conectividade é estabelecida por meio de linhas públicas de internet; não são necessárias VPNs ou linhas alugadas dedicadas para a interface REST.  
* **Codificação:** Todos os dados devem ser codificados em **UTF-8**.

### Restrições JSON

A API é rigorosa em relação aos tipos de dados para garantir a estabilidade em diferentes softwares de terminais.

* **Sem valores `null`:** Os campos nunca devem ser definidos explicitamente como `null`. Se um campo for opcional e não tiver valor, ele deve ser totalmente omitido do objeto JSON.  
* **Minimização:** Embora não seja estritamente obrigatório para o processamento (parsing), recomenda-se evitar espaços em branco excessivos, tabulações ou quebras de linha em payloads de produção para evitar problemas de verificação de assinatura.

## Próximos Passos

* [**Lógica de Assinatura e Segurança**](/pt/get-smart/get-smart-api-cloud/core-concepts/signature-logic-and-security)**:** Entenda o algoritmo de segurança que protege essas mensagens.  
* [**Configurar Webhooks e Notificações**](/pt/get-smart/get-smart-api-cloud/integration-guides/set-up-webhooks-and-notifications)**:** Aprenda como construir o endpoint para receber as notificações assíncronas descritas na Fase 2.