# Solução de problemas

> Causas e soluções para os problemas mais comuns na instalação e no uso do SDK no checkout.

URL: https://docs.proteside.com/pt-BR/docs/integration/troubleshooting

Antes de tudo, abra o checkout com as ferramentas de desenvolvedor do navegador e rode `Proteside.getStatus()` no
console. O resultado indica a maioria dos problemas abaixo. Veja [Verificar a instalação](https://docs.proteside.com/pt-BR/docs/integration/verify).

## Instalação
### O dashboard mostra Proteside não detectado

O dashboard só considera o SDK ativo quando recebe eventos de clientes reais. Confira, na ordem:

1. **O snippet está publicado?** Veja o código-fonte da página de checkout publicada e procure `Proteside Start`.
   Limpe caches do site, do tema e da CDN.
2. **Está no domínio certo?** O snippet precisa estar nas páginas em que o checkout roda de fato, que podem ficar em
   outro domínio ou subdomínio.
3. **Alguém abriu o checkout?** Abra a página você mesmo e recarregue o dashboard depois de alguns segundos.
4. **O SDK carrega?** Rode `Proteside.getStatus()` no console. Se der erro, veja o item seguinte.
5. **Os eventos saem?** Na aba **Rede**, as requisições para `app.proteside.com` devem responder com sucesso. Veja o
   item
   [O SDK roda, mas nada chega ao dashboard](#nada-chega-ao-dashboard).

Se a página **Saúde do SDK** mostra **Só verificação sintética**, o verificador do Proteside encontrou o snippet, mas
nenhum cliente real passou pelo checkout ainda.

### window.Proteside não existe no console

O `shield.js` não carregou. Causas comuns:

* o snippet não está publicado, ou só o bootstrapper foi colado;
* a Content Security Policy não permite `https://cdn.proteside.com` em `script-src` (o console mostra
  `Refused to load the script`);
* uma extensão de bloqueio de anúncios ou rastreadores bloqueou o arquivo (teste em uma janela anônima sem extensões);
* um plugin de otimização alterou ou removeu a tag.

### getStatus() mostra initialized: false

Espere alguns segundos: o SDK só termina de iniciar depois de carregar a configuração da loja. Se continuar `false`:

* **Falta o `data-key`** na tag do `shield.js`. Sem ele, o SDK não inicializa e não mostra aviso.
* **A chave tem formato inválido.** O console mostra `[Proteside] Initialization failed silently` com
  `Invalid apiKey format`. A chave começa com `pk_live_`.
* **A tag foi carregada como `type="module"`.** Remova esse atributo.

### Aviso de ordem de instalação (INSTALLATION_ORDER_WARNING)

O SDK envia esse aviso, e `getStatus().installationOrderValid` fica `false`, quando existe algum `<script>` na página
**antes** do snippet. O snippet deve ser o primeiro script do `<head>` para cobertura completa.

Para conferir, abra o código-fonte da página publicada (Ctrl+U) e veja se o bloco `<!-- Proteside Start -->` vem logo
depois da abertura do `<head>`, antes de qualquer outro `<script>`.

Como corrigir:

* **Há outro script antes do snippet.** Mova o snippet para o topo do `<head>` e publique de novo. Em Next.js, confira
  a ordem final das tags no código-fonte da página publicada.
* **O snippet é antigo.** Snippets antigos traziam a configuração inline numa tag `<script>` separada. Copie o snippet
  atual em **Páginas e Domínios** e substitua o bloco inteiro.
* **O script anterior vem do tema, de um plugin ou da própria plataforma e não pode ser movido.** A proteção continua
  funcionando, mas com cobertura parcial. Se você aceita essa situação, use **Não avisar mais nesta loja** no próprio
  alerta. Só proprietários e administradores veem essa opção. Para voltar a receber o aviso, escreva para
  [team@proteside.com](mailto:team@proteside.com).

Não edite o conteúdo do snippet para fazer o aviso sumir: as regras inline bloqueiam scripts desde o primeiro byte da
página.

Depois de corrigir, resolva o alerta no dashboard. Se ele não voltar no próximo acesso à página, a ordem está certa.

Esse aviso não entra no status de conformidade em **Evidências PCI DSS**.

### Só a tag do shield.js está na página

O snippet tem duas partes, e as duas são necessárias para cobertura completa. Se só a tag do `shield.js` foi colada,
ou se um plugin de otimização transformou o bootstrapper em arquivo externo ou adiado, recole o snippet completo e
exclua-o das otimizações de JavaScript.

Para conferir, abra o código-fonte da página publicada (Ctrl+U): entre `<!-- Proteside Start -->` e
`<!-- Proteside End -->` precisa haver um `<script>` inline seguido da tag do `shield.js`.

### Troquei o canal e a versão do SDK não mudou

A URL do `shield.js` (canal `stable` ou `latest`) está escrita no snippet. Depois de trocar o canal em
**Proteção do pagamento**, copie o snippet de novo em **Páginas e Domínios** e publique.

Se a **Saúde do SDK** mostra mais de uma versão ativa por alguns dias, verifique se todas as páginas usam o mesmo
snippet. Logo depois de uma atualização, é normal ver duas versões por causa do cache do navegador e da CDN.

## Bloqueios e regras
### O navegador bloqueia o Proteside (Content Security Policy)

Mensagens comuns no console e o que liberar:

| Mensagem                                                   | O que falta                                          |
| ---------------------------------------------------------- | ---------------------------------------------------- |
| `Refused to load the script 'https://cdn.proteside.com/…'` | `https://cdn.proteside.com` em `script-src`          |
| `Refused to execute inline script`                         | hash, nonce ou `'unsafe-inline'` para o bootstrapper |
| `Refused to connect to 'https://app.proteside.com/…'`      | `https://app.proteside.com` em `connect-src`         |

A mensagem de script inline informa o hash `'sha256-…'` a incluir. Veja
[Content Security Policy e headers](https://docs.proteside.com/pt-BR/docs/integration/csp).

### GA4 ou Google Ads pararam depois de ativar a lista de containers GTM

Com **Containers GTM permitidos** preenchido, tags do Google Analytics 4 (`G-…`) e do Google Ads (`AW-…`) podem ser
barradas, inclusive quando disparadas pelo próprio GTM. A lista só aceita IDs `GTM-…`, então não há como liberar esses
IDs.

Para resolver:

1. Em **Proteção do pagamento**, passo **O que é normal no seu checkout**, esvazie a lista **Containers GTM
   permitidos** e clique em **Salvar esta etapa**.
2. Copie o snippet de novo em **Páginas e Domínios** e publique. A lista também fica gravada no snippet e continua
   bloqueando no início do carregamento até você recolar.

O bloqueio vale nos dois modos de proteção, **Monitorar** e **Bloquear**.

### Bloqueei um script e ele continua carregando

* **O script está no HTML da página.** Em **Scripts**, ele aparece com o aviso de que continua carregando pelo HTML.
  Remova a tag na origem (HTML ou tema).
* **A regra é por Hash de conteúdo.** O bloqueio no navegador vale para scripts carregados por endereço; scripts
  inline devem ser removidos na origem. Use uma regra por **Domínio** ou **URL do script**.
* **A regra está inativa.** Ative a regra em **Regras**.
* **A mudança ainda não chegou.** Veja [Uma mudança no dashboard não chegou ao checkout](#mudanca-nao-chegou).

### O checkout quebrou depois de criar uma regra ou ativar o modo Bloquear

1. Em **Regras**, desative a regra que casa com o script afetado. Lembre-se de que uma regra por **Domínio** bloqueia
   o domínio inteiro e todos os subdomínios.
2. Copie o snippet de novo em **Páginas e Domínios** e publique: as regras ficam gravadas no snippet.
3. Se ligou o modo **Bloquear**, volte para **Monitorar** enquanto investiga.

Ligar o **Modo desenvolvedor** não desfaz os bloqueios gravados no snippet. Veja
[Pausa e modo desenvolvedor](https://docs.proteside.com/pt-BR/docs/integration/configuration#pausa-e-modo-desenvolvedor).

## Dados no dashboard
### Os scripts aparecem como Precisa revisão

É o esperado. Todo script novo encontrado pelo SDK entra no inventário com o status **Precisa revisão** e espera a
sua decisão. Para cumprir o PCI DSS 4.0, requisito 6.4.3, autorize cada script legítimo com uma justificativa ou
bloqueie os indevidos. Você pode autorizar todos os scripts próprios de uma vez e criar políticas para automatizar
decisões recorrentes.

Um script autorizado volta para **Precisa revisão** quando o conteúdo muda ou quando a validade da autorização vence.
Veja [Scripts](https://docs.proteside.com/pt-BR/docs/guide/scripts) e [Políticas](https://docs.proteside.com/pt-BR/docs/guide/policies).

### Uma mudança no dashboard não chegou ao checkout

* **Tempo de propagação:** as alterações chegam ao checkout em poucos minutos. Aguarde e recarregue o checkout.
* **Regras e containers GTM:** ficam gravados no snippet. Recole o snippet depois de mudá-los.
* **Canal de release:** exige recolar o snippet.

### O SDK roda, mas nada chega ao dashboard

Veja as respostas das requisições para `app.proteside.com` na aba **Rede**:

| Resposta             | Causa                                                                            | O que fazer                                                                                                                                                                             |
| -------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Erro 4xx             | Problema de chave ou de conta.                                                   | Confira em **Saúde do SDK**. Se você trocou a chave, copie o snippet atual em **Páginas e Domínios**. Se a assinatura não está vigente, veja [Cobrança](https://docs.proteside.com/pt-BR/docs/guide/settings/billing). |
| Requisição bloqueada | CSP sem `https://app.proteside.com` em `connect-src`, ou bloqueador de anúncios. | Veja [CSP e headers](https://docs.proteside.com/pt-BR/docs/integration/csp).                                                                                                                                                        |

### Recebi o alerta SDK silencioso

Um domínio que já enviou eventos parou de receber sessões reais. O alerta aparece em até um dia. Verifique se o snippet ainda está publicado (uma
atualização de tema ou de template pode removê-lo) e se o checkout recebeu visitas no período. O alerta é resolvido
sozinho quando o tráfego volta.

## Pagamento
### O Pix fica em AGUARDANDO na Integridade de Pagamento

* **Nenhum cliente pagou com Pix ainda** com o SDK na página. O status muda quando o SDK valida o primeiro código.
* **O código Pix não aparece como texto visível.** Para cobertura completa, exiba o código de pagamento como texto
  visível ou informe-o com `registerPaymentPayload()`. Veja [Integridade de pagamento e Pix](https://docs.proteside.com/pt-BR/docs/integration/payment-integrity).
* **O snippet não está na página que mostra o Pix**, por exemplo uma página de pagamento separada do checkout.

### Recebedor NÃO confere com a lista confiável

O recebedor lido no código não está entre os **Recebedores confiáveis**. Antes de tratar como ataque, confira:

* se a chave cadastrada é a mesma que aparece no código copia e cola gerado pelo seu provedor de pagamento. Alguns
  provedores geram o código com uma chave própria, diferente da chave da loja. Nesse caso, confirme o recebedor em
  **Recebedores vistos no seu checkout** com **É da minha loja**;
* se todas as chaves usadas pela loja estão cadastradas e ativas.

Se a chave do código não pertence à loja nem ao seu provedor, trate como incidente: abra o alerta em **Alertas**.

### Pix dinâmico aparece fora da lista confiável

No Pix dinâmico gerado por um provedor de pagamento, o código traz o endereço do provedor no lugar da chave da loja.
Confirme o recebedor em **Proteção do pagamento → Recebedores vistos no seu checkout** com **É da minha loja**: a
chave usada pelo provedor costuma não ser a que você conhece. A verificação de recebedor se aplica aos códigos que
trazem o recebedor.

Se o código traz o valor, informe também o valor esperado com
[`Proteside.expectPayment()`](https://docs.proteside.com/pt-BR/docs/integration/javascript-api#expectpaymentexpectation).

## Ainda com problemas?
Junte o resultado de `Proteside.getStatus()`, as respostas das requisições para `app.proteside.com` na aba **Rede** e
o endereço da página afetada, e escreva para [team@proteside.com](mailto:team@proteside.com).
