VTEX: vincular la cuenta

BillerPro se conecta a VTEX con un par AppKey/AppToken de solo lectura de pedidos y un hook que VTEX dispara cuando el pago se aprueba.

1. Crear las credenciales en VTEX (3 minutos)

1. En el Admin de VTEX: Configuración de la cuenta → Gestión de la cuenta → Claves de aplicación.
2. Crea una clave nueva con nombre BillerPro.
3. Asigna un rol con permiso OMS – Ver pedidos (lectura). No necesita más.
4. Copia el AppKey (vtexappkey-cuenta-XXXX) y el AppToken. El token solo se muestra una vez.

2. Vincular en BillerPro (1 minuto)

1. En tu panel: Conectar canal → VTEX.
2. Escribe el account name (el subdominio de tu tienda, p. ej. mitienda si entras por mitienda.myvtex.com), el AppKey y el AppToken.
3. Pulsa Vincular VTEX. Te devolvemos la URL del hook (con un token privado). Cópiala.

Las credenciales se guardan cifradas; nunca se muestran de nuevo.

3. Registrar el hook en VTEX (2 minutos)

VTEX avisa por hook cada cambio de estado de un pedido. Regístralo con la API de Orders Feed (o pídele a tu agencia):

POST https://{account}.vtexcommercestable.com.br/api/orders/hook/config
X-VTEX-API-AppKey: {AppKey}
X-VTEX-API-AppToken: {AppToken}
Content-Type: application/json

{
  "filter": { "status": ["payment-approved"] },
  "hook": { "url": "https://billerpro.store/hooks/vtex/hook?token=…" }
}

BillerPro emite solo cuando el estado es payment-approved; cualquier otro estado se reconoce (200) y se ignora.

Boleta o factura

VTEX ya captura el tipo de comprador en el checkout:

• isCorporate = true → factura al RUC de corporateDocument, con corporateName como razón social.
• Persona natural → boleta al document (DNI) del cliente.

Impuestos, envío y gratuitas

• Las líneas se emiten gravadas con IGV. El envío (shipping en los totales) va como línea gravada.
• Los ítems con precio 0 (regalos, promociones) se emiten como gratuitos con el precio de lista como referencia, como exige SUNAT.
• Los descuentos ya vienen aplicados en el precio de VTEX y se respetan al céntimo.

Ventas en dólares

Si el pedido está en USD, el comprobante sale en dólares con el tipo de cambio oficial de SUNAT del día.

Problemas comunes

El hook responde 401: el token de la URL no es válido o la vinculación fue eliminada. Vuelve a vincular en el panel y actualiza la URL en VTEX.

No se emite nada: confirma que el filtro del hook incluye payment-approved y que el pedido efectivamente pasó por ese estado (los pedidos con pago manual a veces saltan a ready-for-handling).

Quiero varias cuentas VTEX: vincula cada una desde el panel; todas facturan con el mismo RUC.