Proteside Docs

API de JavaScript

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

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:

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()

Proteside.getStatus(): SDKStatus

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

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
}
const { initialized, version, installationOrderValid } = Proteside.getStatus();

pageChanged(path)

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.

// 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)

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.
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.

registerPaymentPayload(payload)

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).

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

En esta página