# API JavaScript

> Métodos do objeto window.Proteside para consultar o status e informar pagamentos.

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

O SDK expõe o objeto global `window.Proteside`. Para a maioria das lojas, ele não é necessário: o snippet sozinho já
protege o checkout. Use a API quando o checkout é uma aplicação de página única, quando você quer informar o valor
esperado de um pagamento, ou para diagnóstico.

Todos os métodos são protegidos contra erros e **nunca lançam exceção**: se algo falhar, a chamada é ignorada.

## Esperar o SDK carregar
`window.Proteside` passa a existir assim que o `shield.js` executa, mas o SDK só termina de iniciar depois de carregar
a configuração da loja.

> **Não há evento de pronto**
>
> O SDK não dispara evento, promise ou callback quando fica pronto. Com exceção de `getStatus()`, os métodos chamados
> **antes** de o SDK terminar de iniciar são ignorados sem aviso, inclusive `expectPayment()`.

Para chamar a API com segurança, aguarde `getStatus().initialized` ficar `true`:

```js title="whenProtesideReady.js"
function whenProtesideReady(timeoutMs = 5000) {
  return new Promise((resolve) => {
    const start = Date.now();
    (function check() {
      const sdk = window.Proteside;
      if (sdk && sdk.getStatus().initialized) return resolve(sdk);
      if (Date.now() - start > timeoutMs) return resolve(null); // SDK ausente ou bloqueado
      setTimeout(check, 100);
    })();
  });
}

// Uso
whenProtesideReady().then((sdk) => {
  if (!sdk) return; // siga o checkout normalmente sem o SDK
  sdk.expectPayment({ method: 'pix', amount: '19,90' });
});
```

Nunca condicione o funcionamento do checkout à presença do SDK: um bloqueador de anúncios ou uma falha de rede pode
impedir o carregamento.

## Métodos
### `getStatus()````ts
Proteside.getStatus(): SDKStatus
```

Retorna o estado atual do SDK. Pode ser chamado a qualquer momento: antes de o SDK iniciar, retorna
`initialized: false`.

```ts
interface SDKStatus {
  initialized: boolean            // o SDK terminou de iniciar
  version: string                 // ex.: '1.2.0'
  installationOrderValid: boolean // false = há script antes do snippet
}
```

```js
const { initialized, version, installationOrderValid } = Proteside.getStatus();
```

### `pageChanged(path)````ts
Proteside.pageChanged(path: string): void
```

Para aplicações de página única (React, Vue, Next.js, Nuxt). Avise o SDK quando a rota mudar sem recarregar a
página. O SDK limpa as referências de pagamento e os valores esperados da rota anterior, relê os headers de segurança
e envia um `PAGEVIEW` da nova rota.

```js
// Ex.: no listener de mudança de rota do seu framework
Proteside.pageChanged('/checkout/pagamento');
```

A referência da página e o inventário de scripts valem para o carregamento inteiro.

### `expectPayment(expectation)````ts
Proteside.expectPayment(expectation: {
  method: PaymentMethod
  amount?: string | number
}): void
```

Informa o valor que o checkout espera do pagamento desta página.

* `amount`: valor esperado, na mesma unidade do código (reais, para Pix e boleto). Aceita `19.9`, `'19,90'` ou
  `'R$ 19,90'`, comparados com duas casas decimais. Se o código exibido tiver outro valor, o SDK emite
  `AMOUNT_TAMPERED`.

```js
Proteside.expectPayment({ method: 'pix', amount: '19,90' });
```

Chame **antes** de inserir o código de pagamento na página. Os recebedores confiáveis são cadastrados só no
dashboard. Veja [Integridade de pagamento e Pix](https://docs.proteside.com/pt-BR/docs/integration/payment-integrity).

### `registerPaymentPayload(payload)````ts
Proteside.registerPaymentPayload(payload: {
  method: PaymentMethod
  fields: Record<string, string>
}): void
```

Registra a referência de um método de pagamento. Use quando o código de pagamento não aparece como texto visível na
página. Para servir de comparação, `fields` precisa trazer o recebedor: `pixKey` (Pix), `address` (carteiras cripto),
`vpa` (UPI) ou `walletId` (carteiras QR).

```js
Proteside.registerPaymentPayload({ method: 'pix', fields: { pixKey: 'pix@minhaloja.com.br' } });
```

Sempre que possível, exiba o código como texto visível na página, o que dá a validação completa.

## Métodos de pagamento
O tipo `PaymentMethod` aceita: `pix`, `boleto`, `card`, `bitcoin`, `ethereum`, `tron`, `solana`, `upi`, `paynow`,
`promptpay`, `duitnow`, `qrph`, `hkfps`, `transferencias3`, `codi` e `qr_wallet`.

## O que não faz parte da API
* Não há inicialização manual: o SDK se inicializa sozinho a partir da tag `<script>` do snippet.
* Não há callbacks de ameaça (como `onThreat`) nem modo de depuração. A única mensagem de console é
  `[Proteside] Initialization failed silently`, quando a inicialização falha (por exemplo, chave com formato inválido).
* Use só os métodos documentados nesta página. Qualquer outra propriedade do SDK é interna e pode mudar sem aviso.

## Próximos passos
* [Integridade de pagamento e Pix](https://docs.proteside.com/pt-BR/docs/integration/payment-integrity)
* [Eventos e detecções](https://docs.proteside.com/pt-BR/docs/integration/events)
