# Lógica de Assinatura e Segurança

Na Get Smart API Cloud, a segurança não é tratada por um token de sessão persistente ou um cabeçalho de autenticação Bearer padrão. Em vez disso, cada mensagem — seja uma requisição enviada por você ou uma resposta enviada pela nuvem — é protegida usando uma **Assinatura Digital** (Digital Signature).

Este guia explica o embasamento teórico desse mecanismo, conhecido como **Keyed-Hash**, e por que ele é fundamental para a integridade das transações financeiras.

## O Propósito da Assinatura

A assinatura atende a dois objetivos principais de segurança:

1. **Autenticação (Quem enviou?):** Como a assinatura é gerada usando uma **Chave Secreta** (Secret Key) conhecida apenas por você e pela API Cloud, uma assinatura válida prova que a mensagem se originou de uma fonte confiável.  
2. **Integridade (Foi alterado?):** A assinatura é um checksum matemático do conteúdo da mensagem. Se um único caractere no payload JSON for alterado (ex.: mudar um valor de `10.00` para `1.00`), a assinatura não corresponderá mais, e a requisição será rejeitada.

## O Algoritmo: Concatenação SHA-256

Embora semelhante em propósito ao HMAC (Hash-Based Message Authentication Code), a implementação específica nesta API usa um método **SHA-256 baseado em concatenação**.

### Fluxo Lógico

Signature = SHA256 (JSON String + Secret Key)

1. **A Mensagem:** A string JSON bruta (raw) do objeto `info`. Isso representa o "estado" que você deseja transmitir (ID do Estabelecimento, Valor, Número da Fatura).  
2. **O Segredo:** Sua Chave do Estabelecimento (Merchant Key). Ela atua como o "salt" que impede um invasor de gerar assinaturas válidas, mesmo que conheça o algoritmo de hash.  
3. **O Hash:** A função SHA-256 é uma função criptográfica de via única (one-way). É fácil gerar o hash a partir da mensagem, mas impossível fazer a engenharia reversa da mensagem (ou da chave) a partir do hash.

## Segurança Bidirecional

A segurança nesta API é **bidirecional**.

### Saída (Assinatura de Requisição)

Quando você envia uma requisição para `/pago`, você a assina para provar à API Cloud que você é o estabelecimento autorizado. Se a assinatura for inválida, a API retorna o código de erro `TPC0101` ("Firma Incorrecta").

### Entrada (Verificação de Resposta)

Quando a API Cloud envia uma resposta (síncrona) ou uma notificação (assíncrona), ela assina essa mensagem usando a **sua** Chave Secreta.

> **Não Confie em Ninguém**: Você deve **sempre** calcular a assinatura das notificações recebidas localmente e compará-la com o campo `signature` recebido. Isso protege você contra "ataques de repetição" (replay attacks) ou agentes mal-intencionados que tentem injetar confirmações falsas de pagamento em seu sistema.

## Melhores Práticas de Gerenciamento de Chaves

Como a segurança de todo o sistema depende da Chave Secreta, ela deve ser tratada com extremo cuidado.

* **Apenas Backend:** A geração deve ocorrer no seu servidor seguro. Nunca envie a Chave Secreta em um aplicativo móvel ou em um bundle JavaScript no lado do cliente (client-side).  
* **Segregação de Ambientes:** Use a chave específica atribuída para o ambiente (Teste vs. Produção). Usar uma chave de Teste em Produção (ou vice-versa) resultará em falhas de validação de assinatura.

## Próximos Passos

* [**Autenticar Requisições**](/pt/get-smart/get-smart-api-cloud/first-steps/authtenticate-requests)**:** Veja a implementação prática em código desta lógica.  
* [**Depurar Problemas de Assinatura e Conectividade**](/pt/get-smart/get-smart-api-cloud/integration-guides/debug-signature-and-connectivity-issues)**:** Aprenda como solucionar erros `TPC0101` comuns.