# Lógica de firma y seguridad

En Get Smart API Cloud, la seguridad no se gestiona mediante un token de sesión persistente o una cabecera de autenticación Bearer estándar. En su lugar, cada mensaje —ya sea una petición que envías o una respuesta enviada por la nube— está asegurado mediante una **Firma digital** (Digital Signature).

Esta guía explica la base teórica de este mecanismo, conocido como **Keyed-Hash**, y por qué es crítico para la integridad de las transacciones financieras.

## El propósito de la firma

La firma cumple dos objetivos principales de seguridad:

1. **Autenticación (¿Quién lo envió?):** Debido a que la firma se genera utilizando una **clave del comercio** conocida solo por ti y por API Cloud, una firma válida demuestra que el mensaje se originó de una fuente de confianza.  
2. **Integridad (¿Ha cambiado?):** La firma es un checksum matemático del contenido del mensaje. Si un solo carácter en el payload JSON es alterado (p. ej., cambiar un importe de `10.00` a `1.00`), la firma ya no coincidirá y la petición será rechazada.

## El algoritmo: Concatenación SHA256

Aunque de propósito similar a HMAC (Hash-Based Message Authentication Code), la implementación específica en esta API utiliza un método **SHA256 basado en concatenación**.

### Flujo lógico

Signature = SHA256 (JSON String + Merchant Key)

1. **El mensaje:** La cadena JSON bruta (raw) del objeto `info`. Esto representa el "estado" que quieres transmitir (ID de comercio, Importe, Número de factura).  
2. **El secreto:** Tu clave del comercio. Esta actúa como el "salt" que impide a un atacante generar firmas válidas, incluso si conoce el algoritmo de hash.  
3. **El hash:** La función SHA256 es una función criptográfica unidireccional (one-way). Es fácil generar el hash a partir del mensaje, pero imposible aplicar ingeniería inversa al mensaje (o a la clave) a partir del hash.

## Seguridad bidireccional

La seguridad en esta API es **bidireccional**.

### Salida (Firma de peticiones)

Cuando envías una petición a `/pago`, la firmas para demostrar a API Cloud que eres el comercio autorizado. Si la firma es inválida, la API devuelve el código de error `TPC0101` ("Firma Incorrecta").

### Entrada (Verificación de respuestas)

Cuando API Cloud te envía una respuesta (síncrona) o una notificación (asíncrona), firma ese mensaje utilizando **tu** clave del comercio.

> **No confíes en nadie**: Debes **siempre** calcular la firma de las notificaciones entrantes localmente y compararla con el campo `signature` recibido. Esto te protege de "ataques de repetición" (replay attacks) o actores maliciosos que intenten inyectar confirmaciones de pago falsas en tu sistema.

## Mejores prácticas de gestión de claves

Debido a que la seguridad de todo el sistema recae en la clave del comercio, debe ser tratada con extremo cuidado.

* **Solo backend:** La generación debe ocurrir en tu servidor seguro. Nunca envíes la clave del comercio en una aplicación móvil o en un bundle JavaScript en el lado del cliente (client-side).  
* **Segregación de entornos:** Utiliza la clave específica asignada para el entorno (Test frente a Producción). El uso de una clave de Test en Producción (o viceversa) resultará en fallos de validación de firma.

## Próximos pasos

* [**Autenticar peticiones**](/es/get-smart/get-smart-api-cloud/first-steps/authtenticate-requests)**:** Consulta la implementación práctica en código de esta lógica.  
* [**Depurar problemas de firma y conectividad**](/es/get-smart/get-smart-api-cloud/integration-guides/debug-signature-and-connectivity-issues)**:** Aprende a solucionar errores `TPC0101` comunes.