Depurar problemas de firma y conectividad

La integración con Get Smart API Cloud suele ser sencilla, pero los estrictos requisitos de red y seguridad pueden hacer que, en ocasiones, las peticiones fallen. Esta guía aborda las dos categorías de errores más comunes: Fallos de validación de firma y Problemas de conectividad/tiempos de espera (timeouts).

Escenario 1: “Firma Incorrecta” (TPC0101)

El código de error TPC0101 (“Firma Incorrecta”) es el problema más frecuente al que se enfrentan los desarrolladores. Significa que el hash que has calculado en tu servidor no coincide con el hash calculado por API Cloud.

La lista de comprobación de diagnóstico

Si recibes este error, comprueba estos cinco errores comunes:

1. Minimización de JSON

El problema: Estás calculando el hash de una cadena JSON con formato (“pretty-printed”, con espacios y saltos de línea), pero enviando una versión minimizada (o viceversa).

La solución: La cadena de la que calculas el hash debe ser idéntica a la cadena en el campo info.

• Incorrecto: Calcular el hash de {"importe": "10"} pero enviar {"importe": "10" } (nota el espacio adicional).
• Mejor práctica: Serializa primero tu objeto en una cadena, calcula el hash de esa cadena y, a continuación, coloca esa cadena exacta en el cuerpo de tu petición.

2. Ordenación de campos

El problema: JSON no está ordenado por defecto. Tu biblioteca JSON podría reordenar los campos (p. ej., colocando terminal antes de comercio) al serializar.

La solución: Aunque la API procesa (parsea) JSON de forma flexible, la verificación de la firma es una comparación byte a byte. Asegúrate de que la cadena de la que calculas el hash tenga los campos en el mismo orden exacto que la cadena que envía a través de la red.

3. Incompatibilidad de clave de entorno

El problema: Estás enviando una petición a la URL de Test pero firmándola con tu clave de producción (o viceversa).

La solución: Verifica tus variables de configuración.

• URL de Test: https://tpvpc-i.redsys.es... requiere la clave de test (a menudo AAABBB en la documentación, pero es única para ti).
• URL de Producción: https://tpvpc.redsys.es... requiere tu clave de producción.

4. Codificación de caracteres

El problema: Tu ID de factura (factura) contiene caracteres especiales (p. ej., “Café-001”) y se está calculando su hash como ASCII en lugar de UTF-8.

La solución: Asegúrate de que las entradas de tu función hash estén codificadas explícitamente como UTF-8.

5. Caracteres de escape

El problema: Tu serializador JSON escapa las barras diagonales (p. ej., https:\/\/).

La solución: Si tu serializador añade escapes a la urlNotificacion, esos escapes forman parte de la cadena y deben incluirse en el cálculo del hash.

Escenario 2: Tiempos de espera de conectividad (Timeouts)

Si tu aplicación se bloquea o recibes errores de conexión antes de obtener una respuesta JSON, comprueba tu configuración de red.

1. Cortafuegos y puertos (Firewall)

El Entorno de Test se ejecuta en un puerto no estándar.

• Puerto de Test: 27443
• Puerto de Producción: 443 (HTTPS estándar)
• Acción: Asegúrate de que tu cortafuegos de salida permite el tráfico hacia tpvpc-i.redsys.es en el puerto 27443.

2. Versión de TLS

La API requiere TLS 1.2 o superior.

• Síntoma: “Handshake Failure” o “Connection Reset”.
• Acción: Si estás utilizando un servidor más antiguo (p. ej., Java 7 antiguo, .NET 4.5), puede que necesites habilitar explícitamente TLS 1.2 en la configuración de tu cliente HTTP.

Escenario 3: “Bad Request” o errores genéricos

Si la API devuelve un error HTTP estándar (400, 415, 500) sin un código de error JSON específico:

Códigos de error lógicos comunes

Una vez que la conectividad y las firmas estén funcionando, podría enfrentarse a errores lógicos del terminal.

Próximos pasos

• Estándares generales de la API y cabeceras: Revisa las estrictas reglas de formato JSON.
• Catálogo de códigos de error y denegación: Una lista completa de los códigos de error de TPVPC para una depuración más profunda.