# Solución de problemas

> Causas y soluciones de los problemas más comunes en la instalación y el uso del SDK en el checkout.

URL: https://docs.proteside.com/es/docs/integration/troubleshooting

Antes que nada, abre el checkout con las herramientas para desarrolladores del navegador y ejecuta
`Proteside.getStatus()` en la consola. El resultado indica la mayoría de los problemas de abajo. Consulta
[Verificar la instalación](https://docs.proteside.com/es/docs/integration/verify).

## Instalación
### El dashboard muestra Proteside no detectado

El dashboard solo considera activo el SDK cuando recibe eventos de clientes reales. Revisa, en este orden:

1. **¿El snippet está publicado?** Mira el código fuente de la página de checkout publicada y busca `Proteside Start`.
   Limpia las cachés del sitio, del tema y de la CDN.
2. **¿Está en el dominio correcto?** El snippet debe estar en las páginas en las que realmente se ejecuta el checkout,
   que pueden estar en otro dominio o subdominio.
3. **¿Alguien abrió el checkout?** Abre la página tú mismo y recarga el dashboard después de unos segundos.
4. **¿El SDK carga?** Ejecuta `Proteside.getStatus()` en la consola. Si da error, consulta el siguiente punto.
5. **¿Salen los eventos?** En la pestaña **Red**, las solicitudes a `app.proteside.com` deben responder con éxito.
   Consulta el punto
   [El SDK se ejecuta, pero no llega nada al dashboard](#nada-chega-ao-dashboard).

Si la página **Salud del SDK** muestra **Solo verificación sintética**, el verificador de Proteside encontró el
snippet, pero todavía ningún cliente real pasó por el checkout.

### window.Proteside no existe en la consola

El `shield.js` no cargó. Causas comunes:

* el snippet no está publicado, o solo se pegó el bootstrapper;
* la Content Security Policy no permite `https://cdn.proteside.com` en `script-src` (la consola muestra
  `Refused to load the script`);
* una extensión de bloqueo de anuncios o rastreadores bloqueó el archivo (prueba en una ventana de incógnito sin
  extensiones);
* un plugin de optimización modificó o eliminó la etiqueta.

### getStatus() muestra initialized: false

Espera unos segundos: el SDK solo termina de iniciar después de cargar la configuración de la tienda. Si sigue en
`false`:

* **Falta el `data-key`** en la etiqueta del `shield.js`. Sin él, el SDK no se inicializa y no muestra ningún aviso.
* **La clave tiene un formato inválido.** La consola muestra `[Proteside] Initialization failed silently` con
  `Invalid apiKey format`. La clave empieza con `pk_live_`.
* **La etiqueta se cargó como `type="module"`.** Quita ese atributo.

### Aviso de orden de instalación (INSTALLATION_ORDER_WARNING)

El SDK envía este aviso, y `getStatus().installationOrderValid` queda en `false`, cuando hay algún `<script>` en la
página **antes** del snippet. El snippet debe ser el primer script del `<head>` para una cobertura completa.

Para comprobarlo, abre el código fuente de la página publicada (Ctrl+U) y revisa si el bloque
`<!-- Proteside Start -->` viene justo después de la apertura del `<head>`, antes de cualquier otro `<script>`.

Cómo corregirlo:

* **Hay otro script antes del snippet.** Mueve el snippet al inicio del `<head>` y vuelve a publicar. En Next.js,
  revisa el orden final de las etiquetas en el código fuente de la página publicada.
* **El snippet es antiguo.** Los snippets antiguos traían la configuración inline en una etiqueta `<script>` separada.
  Copia el snippet actual en **Páginas y Dominios** y reemplaza el bloque completo.
* **El script anterior viene del tema, de un plugin o de la propia plataforma y no se puede mover.** La protección
  sigue funcionando, pero con cobertura parcial. Si aceptas esa situación, usa **No avisar más en esta tienda** en la
  propia alerta. Solo los propietarios y administradores ven esta opción. Para volver a recibir el aviso, escribe a
  [team@proteside.com](mailto:team@proteside.com).

No edites el contenido del snippet para que desaparezca el aviso: las reglas inline bloquean scripts desde el primer
byte de la página.

Después de corregirlo, resuelve la alerta en el dashboard. Si no vuelve en el siguiente acceso a la página, el orden es
correcto.

Este aviso no cuenta para el estado de cumplimiento en **Evidencias PCI DSS**.

### Solo la etiqueta del shield.js está en la página

El snippet tiene dos partes, y ambas son necesarias para una cobertura completa. Si solo se pegó la etiqueta del
`shield.js`, o si un plugin de optimización convirtió el bootstrapper en un archivo externo o diferido, vuelve a pegar
el snippet completo y exclúyelo de las optimizaciones de JavaScript.

Para comprobarlo, abre el código fuente de la página publicada (Ctrl+U): entre `<!-- Proteside Start -->` y
`<!-- Proteside End -->` debe haber un `<script>` inline seguido de la etiqueta del `shield.js`.

### Cambié el canal y la versión del SDK no cambió

La URL del `shield.js` (canal `stable` o `latest`) está escrita en el snippet. Después de cambiar el canal en
**Protección del pago**, vuelve a copiar el snippet en **Páginas y Dominios** y publícalo.

Si la **Salud del SDK** muestra más de una versión activa durante algunos días, verifica que todas las páginas usen el
mismo snippet. Justo después de una actualización, es normal ver dos versiones por la caché del navegador y de la CDN.

## Bloqueos y reglas
### El navegador bloquea Proteside (Content Security Policy)

Mensajes comunes en la consola y qué habilitar:

| Mensaje                                                    | Qué falta                                            |
| ---------------------------------------------------------- | ---------------------------------------------------- |
| `Refused to load the script 'https://cdn.proteside.com/…'` | `https://cdn.proteside.com` en `script-src`          |
| `Refused to execute inline script`                         | hash, nonce o `'unsafe-inline'` para el bootstrapper |
| `Refused to connect to 'https://app.proteside.com/…'`      | `https://app.proteside.com` en `connect-src`         |

El mensaje del script inline indica el hash `'sha256-…'` que debes incluir. Consulta
[Content Security Policy y headers](https://docs.proteside.com/es/docs/integration/csp).

### GA4 o Google Ads dejaron de funcionar después de activar la lista de contenedores GTM

Con **Contenedores GTM permitidos** completo, las etiquetas de Google Analytics 4 (`G-…`) y de Google Ads (`AW-…`)
pueden bloquearse, incluso cuando las dispara el propio GTM. La lista solo acepta IDs `GTM-…`, así que no hay forma de
habilitar esos IDs.

Para resolverlo:

1. En **Protección del pago**, paso **Qué es normal en tu checkout**, vacía la lista **Contenedores GTM permitidos** y
   haz clic en **Guardar esta etapa**.
2. Vuelve a copiar el snippet en **Páginas y Dominios** y publícalo. La lista también queda guardada en el snippet y
   sigue bloqueando al inicio de la carga hasta que lo vuelvas a pegar.

El bloqueo aplica en ambos modos de protección, **Monitorear** y **Bloquear**.

### Bloqueé un script y sigue cargándose

* **El script está en el HTML de la página.** En **Scripts**, aparece con el aviso de que sigue cargándose desde el
  HTML. Quita la etiqueta en el origen (HTML o tema).
* **La regla es por Hash de contenido.** El bloqueo en el navegador aplica a los scripts cargados por dirección; los
  scripts inline deben eliminarse en el origen. Usa una regla por **Dominio** o **URL del script**.
* **La regla está inactiva.** Activa la regla en **Reglas**.
* **El cambio todavía no llegó.** Consulta [Un cambio en el dashboard no llegó al checkout](#mudanca-nao-chegou).

### El checkout se rompió después de crear una regla o activar el modo Bloquear

1. En **Reglas**, desactiva la regla que coincide con el script afectado. Recuerda que una regla por **Dominio**
   bloquea el dominio completo y todos sus subdominios.
2. Vuelve a copiar el snippet en **Páginas y Dominios** y publícalo: las reglas quedan guardadas en el snippet.
3. Si activaste el modo **Bloquear**, vuelve a **Monitorear** mientras investigas.

Activar el **Modo desarrollador** no deshace los bloqueos guardados en el snippet. Consulta
[Pausa y modo desarrollador](https://docs.proteside.com/es/docs/integration/configuration#pausa-y-modo-desarrollador).

## Datos en el dashboard
### Los scripts aparecen como Requiere revisión

Es lo esperado. Todo script nuevo que encuentra el SDK entra en el inventario con el estado **Requiere revisión** y
espera tu decisión. Para cumplir con PCI DSS 4.0, requisito 6.4.3, autoriza cada script legítimo con una
justificación o bloquea los indebidos. Puedes autorizar todos los scripts propios de una vez y crear políticas para
automatizar decisiones recurrentes.

Un script autorizado vuelve a **Requiere revisión** cuando su contenido cambia o cuando vence la vigencia de la
autorización. Consulta [Scripts](https://docs.proteside.com/es/docs/guide/scripts) y [Políticas](https://docs.proteside.com/es/docs/guide/policies).

### Un cambio en el dashboard no llegó al checkout

* **Tiempo de propagación:** los cambios llegan al checkout en pocos minutos. Espera y recarga el checkout.
* **Reglas y contenedores GTM:** quedan guardados en el snippet. Vuelve a pegar el snippet después de cambiarlos.
* **Canal de release:** exige volver a pegar el snippet.

### El SDK se ejecuta, pero no llega nada al dashboard

Mira las respuestas de las solicitudes a `app.proteside.com` en la pestaña **Red**:

| Respuesta           | Causa                                                                           | Qué hacer                                                                                                                                                                                        |
| ------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Error 4xx           | Problema de clave o de cuenta.                                                  | Revisa la **Salud del SDK**. Si cambiaste la clave, copia el snippet actual en **Páginas y Dominios**. Si la suscripción no está vigente, consulta [Facturación](https://docs.proteside.com/es/docs/guide/settings/billing). |
| Solicitud bloqueada | CSP sin `https://app.proteside.com` en `connect-src`, o bloqueador de anuncios. | Consulta [CSP y headers](https://docs.proteside.com/es/docs/integration/csp).                                                                                                                                                             |

### Recibí la alerta SDK silencioso

Un dominio que ya envió eventos dejó de recibir sesiones reales. La alerta aparece en un plazo de un día. Verifica si el snippet sigue publicado (una
actualización del tema o de la plantilla puede quitarlo) y si el checkout recibió visitas en el período. La alerta se
resuelve sola cuando vuelve el tráfico.

## Pago
### El Pix queda en ESPERANDO en Integridad de Pagos

* **Todavía ningún cliente pagó con Pix** con el SDK en la página. El estado cambia cuando el SDK valida el primer código.
* **El código Pix no aparece como texto visible.** Para una cobertura completa, muestra el código de pago como texto
  visible o infórmalo con `registerPaymentPayload()`. Consulta [Integridad de pagos y Pix](https://docs.proteside.com/es/docs/integration/payment-integrity).
* **El snippet no está en la página que muestra el Pix**, por ejemplo una página de pago separada del checkout.

### El destinatario NO coincide con la lista confiable

El destinatario leído en el código no está entre los **Destinatarios confiables**. Antes de tratarlo como un ataque,
revisa:

* si la clave registrada es la misma que aparece en el código copia y pega que genera tu proveedor de pagos. Algunos
  proveedores generan el código con una clave propia, distinta de la clave de la tienda. En ese caso, confirma el
  destinatario en **Destinatarios vistos en tu checkout** con **Es de mi tienda**;
* si todas las claves que usa la tienda están registradas y activas.

Si la clave del código no pertenece a la tienda ni a tu proveedor, trátalo como un incidente: abre la alerta en
**Alertas**.

### Un Pix dinámico aparece fuera de la lista confiable

En el Pix dinámico generado por un proveedor de pagos, el código trae la dirección del proveedor en lugar de la clave
de la tienda. Confirma el destinatario en **Protección del pago → Destinatarios vistos en tu checkout** con
**Es de mi tienda**: la clave que usa el proveedor suele no ser la que conoces. La verificación de destinatario se
aplica a los códigos que traen el destinatario.

Si el código trae el monto, informa también el monto esperado con
[`Proteside.expectPayment()`](https://docs.proteside.com/es/docs/integration/javascript-api#expectpaymentexpectation).

## ¿Sigues con problemas?
Reúne el resultado de `Proteside.getStatus()`, las respuestas de las solicitudes a `app.proteside.com` en la pestaña
**Red** y la dirección de la página afectada, y escribe a [team@proteside.com](mailto:team@proteside.com).
