Getnet DocsGetnet Docs

Lógica de firma y seguridad

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

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