# Configurar Webhooks y notificaciones

Debido a que las interacciones con los terminales físicos requieren tiempo (p. ej., esperar a que se introduzca un PIN), Get Smart API Cloud devuelve el resultado final de una transacción de forma asíncrona.

Para recibir este resultado, debes exponer un endpoint HTTP público (Webhook) en tu servidor. API Cloud enviará una petición `POST` a esta URL que contendrá los detalles finales de la transacción, los códigos de autorización y los datos del recibo.

## Configuración

Defines dónde enviar la notificación **por petición**. Esto significa que puedes enrutar diferentes transacciones a diferentes endpoints si es necesario.

En cada llamada a la API (Pago, Devolución, Preautorización), incluye el objeto `notificacion`:

```json
{
  "info": {
    "notificacion": {
      "urlNotificacion": "https://your-server.com/api/webhooks/payments",
      "correoNotificacion": "admin@merchant.com"
    },
    ...
  }
}
```

* `urlNotificacion`: El canal principal. Debe ser una URL HTTPS accesible públicamente.  
* `correoNotificacion`: El canal de respaldo. Si tu servidor está inactivo o devuelve un error (distinto de 200), el sistema enviará el resultado por correo electrónico a esta dirección.

## El payload de notificación

Cuando el terminal termina de procesar, tu servidor recibirá un payload JSON.

**Método:** `POST`

**Content-Type:** `application/json`

### Ejemplo de payload

```json
{
  "info": {
    "comercio": "777888991",
    "terminal": 1,
    "timeStamp": "20250428 111500",
    "datosRespuesta": {
      "tipoPago": "PAGO",
      "importe": "25.50",
      "moneda": "978",
      "factura": "ORD-2025-001",
      "resultado": "Autorizada",
      "codigoRespuesta": "998877",
      "estado": "F",
      "tarjetaClienteRecibo": "************1234",
      "marcaTarjeta": "1",
      "Literales": {
         "autenticadoPorPin": "OPERACION CON PIN. FIRMA NO NECESARIA."
      }
    }
  },
  "signature": "INCOMING_SERVER_SIGNATURE"
}
```

### Campos clave a procesar

| Campo | Descripción |
| :--- | :--- |
| `resultado` | El resultado legible por humanos: `Autorizada` o `Denegada`. |
| `codigoRespuesta` | El código de autorización (si se aprueba) o código de error (si se deniega). Guárdalo para la conciliación. |
| `estado` | `F` (Finalizada), `A` (Cancelada), `G` (Denegada), `T` (Error técnico). |
| `Literales` | Contiene el texto obligatorio que debe imprimirse en el recibo (p. ej., "Verificación por PIN"). |
| `datosDCC` | Presente únicamente si se ha producido Dynamic Currency Conversion (DCC). Contiene los detalles del tipo de cambio. |
| `paisTarjeta` | El código numérico ISO-3166 de 3 dígitos del país de la tarjeta (p. ej., `840` para EE. UU., `724` para España). Útil para analítica o lógica de fraude. |

## Securizar su Webhook

Dado que la URL de tu webhook es pública, cualquiera podría, en teoría, enviarte peticiones falsas. **Debes verificar la firma de cada notificación entrante.**

### Pasos de verificación

1. **Capturar el cuerpo en bruto (Raw Body):** Lee el cuerpo JSON entrante.  
2. **Extraer `info`:** Separa el objeto `info` de la `signature`.  
3. **Calcular el hash:** * Minimiza la cadena JSON de `info` (elimina los espacios en blanco).  
   * Añade tu **clave del comercio**.  
   * Calcula el SHA256.  
4. **Comparar:** Comprueba si tu hash calculado coincide con la `signature` del payload.

> **Advertencia de seguridad**: Si las firmas no coinciden, **descarta la petición inmediatamente**. No actualices el estado de tu pedido ni entregues los bienes.

## Mejores prácticas

### 1. Idempotencia

Los reintentos de red pueden provocar que reciba la misma notificación dos veces. Asegúrate de que tu sistema pueda gestionar peticiones duplicadas para la misma `factura` (ID de factura) sin cobrar al cliente dos veces o corromper tu base de datos.

### 2. Acuse de recibo rápido

Tu servidor debe devolver un estado `200 OK` inmediatamente después de recibir y almacenar los datos del webhook. Si tarda demasiado en responder, API Cloud podría considerar que la entrega ha fallado y activar el respaldo por correo electrónico.

### 3. Gestionar respaldos

Si recibes una notificación por correo electrónico (porque tu servidor estaba inactivo), contendrá los mismos datos en un formato legible por humanos. Es posible que necesites un proceso manual para actualizar los pedidos en función de estos correos electrónicos si tu sistema automatizado falla.

## Solución de problemas

| Problema | Posible causa |
| :---- | :---- |
| **Fallo de coincidencia de firma** | Podría estar utilizando la clave de entorno incorrecta (Test frente a Producción), o tu parser JSON está reordenando los campos antes de que calcules el hash. |
| **No se recibe notificación** | Comprueba la configuración de tu firewall. Asegúrate de que tu servidor acepta conexiones de Internet en el puerto especificado. |
| **Se recibe correo electrónico en su lugar** | Tu servidor devolvió un error 4xx/5xx o se agotó el tiempo de espera (timeout), activando el mecanismo de respaldo. |

## Próximos pasos

* [**Consultar el historial de transacciones**](/es/get-smart/get-smart-api-cloud/integration-guides/query-transaction-history)**:** Si se ha perdido un webhook, utiliza el endpoint Query (Consulta) para recuperar el estado manualmente.  
* [**Especificaciones de impresión de recibos**](/es/get-smart/get-smart-api-cloud/reference/receipt-printing-specifications)**:** Aprende a formatear los datos de `Literales` y `datosDCC` en tickets impresos.