Conecta tu tienda WooCommerce con FacturaLibre

Antes de empezar

Necesitas cuatro cosas, y casi seguro ya las tienes:

• Un negocio en FacturaLibre. Si todavía no lo tienes, regístralo. Puedes probar el plugin desde el primer día con una clave de pruebas, sin validez tributaria; cuando el negocio está en producción, creas una clave de producción y la pegas (paso 2).
• Acceso de administrador a tu WordPress, con WordPress 6.0 o superior, WooCommerce 7.0 o superior y PHP 7.4 o superior. Lo ves en Escritorio → Actualizaciones y en WooCommerce → Estado.
• La tienda vende en pesos chilenos. Un pedido en otra moneda queda sin emitir, con el motivo anotado en el pedido.
• El hosting corre las tareas programadas de WordPress (WP-Cron), como casi todos. Si las tiene apagadas, el plugin te lo avisa en el administrador y te dice qué pedir al hosting.

Quien instala puede ser tú o tu agencia; no hay que programar nada. Y si prefieres que lo hagamos contigo, escríbenos por WhatsApp con el nombre de tu tienda.

1. Descarga e instala el plugin

2. Crea tu clave de API

La clave es lo que le permite a tu tienda emitir a nombre de tu negocio. La crea quien administra el negocio en FacturaLibre.

¿Dos tiendas de la misma empresa? Una clave por tienda, cada una con su nombre. Un negocio admite hasta cinco claves activas a la vez.

3. Conecta y elige cuándo emitir

En tu WordPress: WooCommerce → Ajustes → Integración → FacturaLibre. Son cinco ajustes; dos de ellos no hay que tocarlos.

Aprieta Guardar los cambios. Al guardar, el plugin prueba la conexión sin emitir nada y arriba aparece «FacturaLibre conectado: tu negocio (su RUT), en producción» —o «en pruebas», con una clave de pruebas: mientras esté puesta, los ajustes lo recuerdan arriba—. Si dice que no se pudo conectar, revisa que la clave esté completa, sin espacios al principio ni al final.

4. Haz un pedido de prueba

• Compra algo en tu tienda y págalo, o toma un pedido pendiente y cámbialo a Procesando desde el administrador.
• Un momento después, en WooCommerce → Pedidos, la columna Documento SII muestra el tipo y el folio, y el pedido tiene una nota con el detalle.
• En app.facturalibre.cl → Ventas → Documentos está el documento con su PDF, y el comprador lo recibió por correo.

Si tu clave es real (fl_live_), el documento es real. Si fue solo una prueba, anúlalo con una nota de crédito desde la ficha del documento en Documentos, dentro del mismo mes. Si prefieres no emitir nada real para probar, usa una clave de pruebas (fl_test_): la columna dice «PRUEBA · Boleta N° …» y el documento queda en el ambiente de pruebas del portal (Configuración → Ambiente).

Qué pasa en cada venta

1. El comprador paga y el pedido pasa a «Procesando». El checkout termina ahí: nadie espera al SII.
2. Un momento después, en segundo plano, el plugin manda la venta tal como WooCommerce la cobró: cada producto con su cantidad y su precio final, el despacho, los recargos y los descuentos, el número de pedido y los datos del comprador. El documento suma exactamente lo cobrado, peso a peso.
3. FacturaLibre decide boleta o factura, toma el folio, firma y timbra el documento, lo envía al SII y le manda el PDF al comprador por correo, con su código de verificación.
4. El folio y el tipo quedan anotados en el pedido. Si el SII está lento o caído, el documento igual queda timbrado y FacturaLibre lo reintenta hasta que el Servicio lo reciba.

Si lo que falla es tu hosting o la red, el plugin reintenta solo: a los 1, 5, 15 y 30 minutos, y luego 1, 2, 4 y 8 horas. Y como el servidor reconoce cada pedido por su número, un reintento nunca duplica un documento.

Boleta o factura

• Boleta electrónica por defecto: es lo que corresponde a una venta a consumidor final, y le llega al comprador por correo.
• Factura electrónica si el comprador completó en el checkout los tres campos que agrega el plugin: «RUT de la empresa», «Razón social» y «Giro». Escribir el RUT exige los otros dos, así la factura sale a nombre de la empresa y no de la persona. Funciona en el checkout por bloques y en el clásico.
• Tus precios llevan el IVA incluido, como en toda tienda; en la factura se separan neto e IVA. Si al separarlos el redondeo moviera un peso, el total del pedido manda y queda anotado.
• Si tu tienda vende solo a empresas o solo a personas, fíjalo en «Documento a emitir» (paso 3).

Si algo falla

La columna «Documento SII» del pedido dice en qué está cada documento:

• «Emitir documento en FacturaLibre» está en las acciones del pedido: sirve para reintentar después de corregir lo que faltaba. No emitas ese pedido a mano en el portal: lo duplicarías.
• Aviso de WP-Cron. Si un pedido lleva más de 15 minutos esperando su documento, el plugin avisa en el administrador que las tareas programadas de WordPress no están corriendo. Revísalo en WooCommerce → Estado → Acciones programadas o pide a tu hosting que active el cron.
• Copia de pruebas de la tienda. Un clon en otro dominio (staging) no emite y lo avisa: así una copia no genera documentos reales. Si la tienda cambió de dirección de verdad, vuelve a guardar los ajustes de FacturaLibre en el sitio nuevo.
• «No se pudo conectar». La clave está incompleta o fue revocada: crea otra en el portal y pégala.

Devoluciones

Cuando reembolsas o cancelas un pedido que ya tiene documento, el plugin deja una nota en el pedido recordando anularlo. La anulación es una nota de crédito que emites desde Ventas → Documentos, en la ficha del documento. El plugin no la emite solo, porque una devolución parcial o un cambio de producto no siempre anulan el documento entero.

Lo que el plugin no hace todavía

• La nota de crédito automática al reembolsar: se emite desde el portal (arriba).
• Boletas sobre 135 UF: la ley exige informar el medio de pago y el plugin no lo envía, así que esa boleta queda «Sin emitir» con el motivo. Se emite desde el portal.
• Productos exentos de IVA: todo viaja como afecto.
• Pedidos en otra moneda que el peso chileno.

Preguntas frecuentes

¿Cuánto cuesta el plugin de WooCommerce?

Nada: va incluido en cualquier plan de FacturaLibre, igual que la API. El plan parte en $19.990 + IVA al mes para ventas hasta $10 millones al mes, con 10.000 documentos al mes incluidos: una temporada alta no encarece la cuenta.

¿Puedo probar sin emitir documentos de verdad?

Sí, siempre: crea una clave de pruebas (fl_test_) en Integraciones → API y pégala en tu tienda o en una copia de staging. Emite contra el ambiente de pruebas de tu negocio —el motor real con un SII simulado—, sin validez tributaria y sin correo al comprador (te llega a ti). El plugin avisa en sus ajustes que está en modo pruebas y marca cada pedido con «PRUEBA». Para vender de verdad, cambia la clave por una de producción (fl_live_). Si alguna vez pruebas con una clave real, anula el documento con una nota de crédito desde Documentos, dentro del mismo mes.

¿Qué datos salen de mi tienda?

Solo lo que el documento necesita: el número de pedido, los productos con su cantidad y precio, el despacho, y los datos del comprador (nombre y correo; si pidió factura, además RUT, razón social, giro, dirección y comuna). Al guardar los ajustes se envía la clave para probar la conexión. Todo viaja por https a app.facturalibre.cl y nada más sale del sitio.

¿Sirve si tengo dos tiendas de la misma empresa?

Sí. Cada sitio se identifica solo, así que dos tiendas no se pisan la numeración ni los reintentos. Crea una clave por tienda, con su nombre: si un día hay que revocar una, sabes cuál.

¿Qué pasa si el SII está caído o lento?

Nada que debas hacer. El documento se firma y timbra igual, queda con su folio y FacturaLibre lo reintenta hasta que el SII lo reciba. El comprador nunca espera al SII en el checkout: la emisión corre en segundo plano, un momento después del pago.

¿Tengo que administrar los folios?

No. Los folios (CAF) se piden al SII antes de que se acaben, también de noche y en fin de semana. Es la parte que más problemas da cuando se administra a mano en una tienda que vende a toda hora.

¿Funciona con el checkout por bloques y con el clásico?

Con los dos. En ambos agrega los campos para pedir factura (RUT, razón social y giro), opcionales salvo que elijas «Siempre factura». También es compatible con el almacenamiento de pedidos de alto rendimiento (HPOS) de WooCommerce.

¿Quién lo instala?

Tú o tu agencia, en minutos: son los cuatro pasos de esta guía. Y si prefieres, durante la puesta en marcha lo instalamos contigo, sin costo adicional: escríbenos por WhatsApp con el nombre de tu tienda.

Mi tienda es Shopify, Jumpseller, Wix o PrestaShop, o vendo por Mercado Libre

Las conectamos contigo durante la puesta en marcha, incluido en tu plan. Si tu tienda está hecha a medida, se conecta por nuestra API REST, que es pública y está documentada en facturalibre.cl/docs.

Para agencias y desarrolladores

• El plugin es un cliente delgado de POST /api/v1/eventos (la referencia): junta lo que WooCommerce sabe de la venta y lo manda; boleta o factura, IVA, folios y reintentos ante el SII los decide el servidor. Un solo archivo PHP, GPLv2, que viene en el ZIP. No expone endpoints propios y la clave solo viaja por https a app.facturalibre.cl.
• Idempotencia del servidor por (origen, referencia): el origen es propio de cada sitio (wc- + 12 caracteres del md5 del dominio) y la referencia es el número de pedido. Dos tiendas de la misma empresa no se pisan; un reintento no duplica.
• Los datos de factura quedan en el pedido: en el checkout clásico como _billing_rut, _billing_razon_social y _billing_giro; en el de bloques como campos adicionales de WooCommerce con el prefijo facturalibre/.
• La emisión corre en Action Scheduler (grupo facturalibre); en PHP-FPM y LiteSpeed, en la misma petición del pago después de responderle al comprador, así que sale en segundos sin depender de WP-Cron. Compatible con HPOS y declarado para el checkout por bloques.
• ¿Otra plataforma? La misma llamada sirve desde cualquier sistema: documentación de la API.