Getnet DocsGetnet Docs

Lógica de Assinatura e Segurança

View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page
Connect to CursorUse these docs in CursorConnect to VS CodeUse these docs in VS Code

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