# API de JavaScript

> Métodos del objeto window.Proteside para consultar el estado e informar pagos.

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

El SDK expone el objeto global `window.Proteside`. Para la mayoría de las tiendas no es necesario: el snippet por sí
solo ya protege el checkout. Usa la API cuando el checkout es una aplicación de página única, cuando quieres informar el
monto esperado de un pago, o para diagnóstico.

Todos los métodos están protegidos contra errores y **nunca lanzan excepciones**: si algo falla, la llamada se ignora.

## Esperar a que cargue el SDK
`window.Proteside` existe en cuanto se ejecuta el `shield.js`, pero el SDK solo termina de iniciar después de cargar la
configuración de la tienda.

> **No hay evento de listo**
>
> El SDK no dispara ningún evento, promise ni callback cuando está listo. Con excepción de `getStatus()`, los métodos
> llamados **antes** de que el SDK termine de iniciar se ignoran sin aviso, incluido `expectPayment()`.

Para llamar a la API de forma segura, espera a que `getStatus().initialized` sea `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 o bloqueado
      setTimeout(check, 100);
    })();
  });
}

// Uso
whenProtesideReady().then((sdk) => {
  if (!sdk) return; // continúa el checkout con normalidad sin el SDK
  sdk.expectPayment({ method: 'pix', amount: '19,90' });
});
```

Nunca condiciones el funcionamiento del checkout a la presencia del SDK: un bloqueador de anuncios o una falla de red
puede impedir que cargue.

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

Devuelve el estado actual del SDK. Se puede llamar en cualquier momento: antes de que el SDK inicie, devuelve
`initialized: false`.

```ts
interface SDKStatus {
  initialized: boolean            // el SDK terminó de iniciar
  version: string                 // p. ej.: '1.2.0'
  installationOrderValid: boolean // false = hay un script antes del snippet
}
```

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

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

Para aplicaciones de página única (React, Vue, Next.js, Nuxt). Avisa al SDK cuando la ruta cambia sin recargar la
página. El SDK limpia las referencias de pago y los valores esperados de la ruta anterior, vuelve a leer los headers de
seguridad y envía un `PAGEVIEW` de la nueva ruta.

```js
// P. ej.: en el listener de cambio de ruta de tu framework
Proteside.pageChanged('/checkout/pagamento');
```

La referencia de la página y el inventario de scripts valen para toda la carga.

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

Informa el monto que el checkout espera del pago de esta página.

* `amount`: monto esperado, en la misma unidad del código (reales, para Pix y boleto). Acepta `19.9`, `'19,90'` o
  `'R$ 19,90'`, comparados con dos decimales. Si el código mostrado tiene otro monto, el SDK emite `AMOUNT_TAMPERED`.

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

Llámalo **antes** de insertar el código de pago en la página. Los destinatarios confiables se registran solo en el
dashboard. Consulta [Integridad de pagos y Pix](https://docs.proteside.com/es/docs/integration/payment-integrity).

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

Registra la referencia de un método de pago. Úsalo cuando el código de pago no aparece como texto visible en la
página. Para que sirva de comparación, `fields` debe incluir el destinatario: `pixKey` (Pix), `address` (billeteras
cripto), `vpa` (UPI) o `walletId` (billeteras QR).

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

Siempre que sea posible, muestra el código como texto visible en la página, lo que da la validación completa.

## Métodos de pago
El tipo `PaymentMethod` acepta: `pix`, `boleto`, `card`, `bitcoin`, `ethereum`, `tron`, `solana`, `upi`, `paynow`,
`promptpay`, `duitnow`, `qrph`, `hkfps`, `transferencias3`, `codi` y `qr_wallet`.

## Qué no forma parte de la API
* No hay inicialización manual: el SDK se inicializa solo a partir de la etiqueta `<script>` del snippet.
* No hay callbacks de amenaza (como `onThreat`) ni modo de depuración. El único mensaje en la consola es
  `[Proteside] Initialization failed silently`, cuando la inicialización falla (por ejemplo, una clave con formato
  inválido).
* Usa solo los métodos documentados en esta página. Cualquier otra propiedad del SDK es interna y puede cambiar sin
  aviso.

## Próximos pasos
* [Integridad de pagos y Pix](https://docs.proteside.com/es/docs/integration/payment-integrity)
* [Eventos y detecciones](https://docs.proteside.com/es/docs/integration/events)
