Timbrar CFDI desde Dolibarr con Facty

Si llevas tu operación en Dolibarr, no tiene mucho sentido capturar cada factura dos veces: una en el ERP y otra en el portal de facturación. El módulo de Facty para Dolibarr te deja timbrar desde la propia ficha de la factura, con los datos que ya capturaste.

Esta guía cubre la instalación, la configuración de los dos ambientes y el primer timbrado.

Qué hace, y qué no

Vale la pena decirlo antes de que inviertas tiempo.

Sí:

• Facturas (Ingreso) y notas de crédito (Egreso)
• Complementos de pago (REP)
• Cancelación con los cuatro motivos del SAT y su acuse
• Consulta del estatus ante el SAT
• XML y PDF timbrados, guardados en la pestaña Documentos de la factura
• CFDI relacionados y factura global

Todavía no: Complemento Carta Porte, Comercio Exterior, nómina ni retenciones locales. Si tu operación necesita Carta Porte, el módulo aún no te sirve para eso.

Antes de empezar

• Dolibarr 18 o superior, con PHP 8.1+
• Tu servidor de Dolibarr con salida a internet (respeta el proxy que ya tengas configurado)
• Una cuenta de Facty con tu CSD cargado y saldo de timbres

Si todavía no tienes el CSD en Facty, empieza por cómo subir tu CSD.

Una idea que conviene entender primero

El módulo no timbra: manda los datos de tu factura a Facty, y Facty timbra.

Eso significa que tu certificado (CSD) y tu contraseña del SAT nunca se guardan en tu servidor de Dolibarr. Viven en Facty. Lo que se guarda en Dolibarr es una llave de API que puedes revocar en cualquier momento sin tocar tu certificado.

Si tu servidor de Dolibarr se ve comprometido, quien entre no se lleva tu sello digital.

Paso 1: instalar el módulo

1. Descarga el ZIP del módulo.
2. En Dolibarr: Inicio → Configuración → Módulos → Desplegar módulo externo.
3. Sube el ZIP.
4. Busca Facty en la lista de módulos y actívalo.

Si tu Dolibarr no permite desplegar módulos desde la interfaz (algunos hosting lo desactivan), descomprime el ZIP dentro de htdocs/custom/ en el servidor.

Paso 2: crear tus llaves en Facty

En Facty: Configuración → API Keys → Nueva llave.

Dale los permisos que el módulo necesita:

invoices.create   invoices.read   invoices.cancel   invoices.send
clients.create    clients.read    clients.update
products.create   products.read   products.update
payments.create   payments.read
accounts.read     billing.read

La llave se muestra una sola vez. Cópiala en ese momento; si la pierdes, generas otra y revocas la anterior.

Fíjate en lo que no lleva: nada de administración de la organización, ni de miembros, ni de compras. Una llave con estos permisos puede facturar, pero no puede tocar la configuración de tu cuenta ni gastar dinero comprando timbres.

Paso 3: configurar los dos ambientes

En Dolibarr: Inicio → Configuración → Módulos → Facty.

Vas a ver dos bloques, y los dos se configuran a la vez:

| Ambiente | Para qué | |---|---| | Pruebas | Comprobantes sin validez fiscal. Para verificar que todo funciona. | | Producción | CFDI reales ante el SAT. |

Pega cada llave en su bloque y usa Probar conexión en cada uno.

Si todo está bien, verás el nombre de tu empresa, tu RFC, tu régimen, la vigencia de tu CSD y tu saldo de timbres.

La comprobación que te va a salvar

Al probar la conexión, el módulo verifica que la llave corresponda al ambiente donde la estás guardando, y se niega a guardarla si no coincide.

Es la protección más importante de esta pantalla: pegar la llave de producción en el campo de pruebas significa emitir CFDI reales creyendo que estás probando — comprobantes con validez fiscal, con folio consumido, que después sólo se arreglan cancelando.

Mientras estés en pruebas, todas las pantallas del módulo llevan una banda naranja visible y los documentos quedan marcados. No es adorno.

Paso 4: completar los datos del SAT

El SAT pide datos que Dolibarr no maneja de forma nativa. El módulo trae una pantalla que te dice exactamente qué falta: Facty → Qué falta.

• Productos: clave de producto/servicio y clave de unidad. La pestaña Datos SAT de cada producto tiene un buscador — no hace falta que te sepas las claves de memoria.
• Clientes: RFC, código postal y régimen fiscal, en la pestaña Datos fiscales CFDI.

Si tienes muchos, esa pantalla te deja descargar un CSV, llenarlo en tu hoja de cálculo y volverlo a subir.

Hazlo ahora y no cuando vayas a timbrar. Descubrir que a trescientos productos les falta la clave cuando ya tienes un cliente esperando su factura es la peor manera de enterarse.

Paso 5: mapear las formas de pago

En Facty → Valores por omisión vas a ver tus modos de pago de Dolibarr junto a un campo para la clave del SAT.

Las más usadas:

| Clave | Forma de pago | |---|---| | 01 | Efectivo | | 02 | Cheque nominativo | | 03 | Transferencia electrónica | | 04 | Tarjeta de crédito | | 28 | Tarjeta de débito | | 99 | Por definir (obligatoria en facturas PPD) |

La pantalla te avisa cuáles faltan por mapear.

Paso 6: tu primera factura de prueba

Con el ambiente en Pruebas:

1. Crea y valida una factura en Dolibarr como siempre.
2. Entra a la pestaña CFDI.
3. Revisa el resumen: si falta algo, la pantalla lo enumera antes de dejarte timbrar.
4. Elige uso del CFDI y método de pago.
5. Timbrar.

El XML y el PDF se descargan solos y quedan en la pestaña Documentos de la factura.

Timbra también una nota de crédito y un complemento de pago antes de pasar a producción. Son los flujos donde más fácil se descubre que falta un dato.

Complementos de pago

Si facturas en PPD (parcialidades o diferido), el SAT te obliga a emitir un complemento por cada abono.

Al registrar el pago en Dolibarr, entra a la pestaña Complemento de Pago. El módulo calcula solo la parcialidad, el saldo anterior y el saldo insoluto a partir del historial real de pagos de esa factura, y te los enseña antes de timbrar. Revísalos: son exactamente los números que van al SAT.

Pasar a producción

Cuando lo de arriba funcione en pruebas:

1. Cambia el ambiente a Producción y guarda.
2. Vuelve a Probar conexión.
3. Verifica que la banda naranja desapareció.
4. Timbra una factura real y revisa el XML.

Los documentos que timbraste en pruebas se quedan en pruebas. No se mezclan, y las listas del módulo sólo te muestran los del ambiente activo.

Si algo sale mal

Facty → Diagnóstico te muestra las últimas llamadas con su error y una referencia. Si escribes a soporte, mándala: con ella encontramos tu petición exacta; sin ella, empezamos de cero.

Dos mensajes que conviene entender:

• "Timbrado en proceso" — no se pudo confirmar el resultado. No vuelvas a timbrar. Puede que el CFDI sí se haya emitido; el módulo lo verifica solo en unos minutos y actualiza el estado. Volver a intentarlo podría emitir un comprobante duplicado y gastar otro timbre.
• "Sin timbres disponibles" — recarga tu saldo en Facty y vuelve a intentar.

Cancelaciones

Desde la pestaña CFDI, con los cuatro motivos del SAT. El motivo 01 te pide el folio de la factura que sustituye a la cancelada.

Cancelar consume un timbre y no se puede deshacer. Si quieres entender cuándo aplica cada motivo, tenemos una guía dedicada: cómo cancelar un CFDI.

Si ya usas otro módulo de facturación

Puedes tener los dos instalados mientras haces la transición, pero pruébalo primero en una copia de tu Dolibarr, no en producción: algunos instaladores modifican campos que no crearon.

Ten en cuenta que los CFDI que emitiste antes con otra herramienta no se pueden cancelar ni complementar desde aquí — falta el identificador que se genera al timbrar. Lo práctico es elegir una fecha de corte: a partir de ahí todo con Facty, y conservas la herramienta anterior mientras tengas documentos vivos emitidos con ella.

¿Necesitas ayuda?

Escríbenos con la versión de tu Dolibarr, la de PHP y la referencia del diagnóstico. Con eso normalmente sabemos qué pasó sin pedirte más datos.