VTEX: vincular la cuenta

¿Todavía no usas BillerPro? Mira qué hace BillerPro en una tienda VTEX o la guía cómo facturar tus pedidos VTEX con SUNAT.

BillerPro se conecta a VTEX con un par AppKey/AppToken y un hook de pedidos. Con eso:

• Al aprobarse el pago sale la boleta o factura a SUNAT.
• Cuando el pedido pasa a Preparando envío (handling) y SUNAT ya aceptó el comprobante, BillerPro lo registra en el pedido de VTEX: el pedido pasa a Facturado y el comprador ve el número y un enlace para verificarlo. VTEX solo acepta la factura en ese estado.
• Si el pedido se cancela (VTEX solo lo permite antes de Facturado) con el comprobante ya aceptado, sale la nota de crédito por anulación.

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 de OMS con dos permisos: ver pedidos y notificar la factura del pedido (es el que lo pasa a Facturado). Sin el segundo, BillerPro igual emite el comprobante; solo falta marcar el pedido como facturado en VTEX.
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": { "type": "FromWorkflow", "status": ["payment-approved", "ready-for-handling", "handling", "canceled"] },
  "hook": { "url": "https://billerpro.store/hooks/vtex/hook?token=…" }
}

Qué hace BillerPro con cada estado:

• payment-approved: emite la boleta o factura.
• ready-for-handling: si el pago fue manual y el pedido saltó payment-approved, emite aquí.
• handling (Preparando envío): registra el comprobante aceptado en el pedido y lo pasa a Facturado. Si todavía no existía, primero lo emite.
• canceled: si el pedido tenía comprobante aceptado, emite la nota de crédito por anulación (tipo 01). Si no tenía, no hace nada.

Cualquier otro estado se reconoce (200) y se ignora. Un mismo pedido nunca se emite ni se registra dos veces.

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.

El enlace que ve el comprador

El comprobante queda en el pedido de VTEX con su número (p. ej. B001-00000042) y un enlace a la consulta pública con los datos ya puestos: el comprador lo abre y ve el estado ante SUNAT y el PDF.

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 los cuatro estados de arriba y que el pedido pasó por alguno de ellos.

El pedido no pasa a Facturado: revisa que el pedido haya llegado a Preparando envío y que la clave de VTEX tenga el permiso para notificar la factura (paso 1). VTEX también exige que el valor facturado sea igual al del pedido: si editaste el pedido después del pago, revisa el comprobante en el panel.

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

Devoluciones de un pedido ya facturado: VTEX no deja cancelar un pedido Facturado; la devolución se registra aparte. La nota de crédito de esa devolución se emite desde el panel de BillerPro, con la acción «Nota de crédito» de ese comprobante.