Conector de Odoo

El conector deja que Odoo emita e-CF sin escribir código: al confirmar una factura, Odoo asigna el e-NCF y avisa a FiscalFlow; FiscalFlow arma el XML, lo firma, lo transmite a la DGII y devuelve el resultado a la factura, con el PDF fiscal y el XML firmado como adjuntos.

El módulo de Odoo, l10n_do_ecf_connect, no contiene lógica fiscal: asigna el número, llama y muestra el resultado. Todo lo pesado ocurre en FiscalFlow. Por eso es un módulo de puros datos y se instala desde la interfaz web, sin tocar el servidor.

Antes de empezar

Necesitas cuatro cosas:

Acceso de administrador al Odoo.
El certificado digital del contribuyente en .p12, con su contraseña.
Los rangos de e-NCF que la DGII autorizó, con su fecha de vencimiento, tal como aparecen en la Oficina Virtual.
El módulo base_automation instalado en Odoo.

base_automation tiene que estar instalado antes.

El conector depende de las reglas de automatización de Odoo; sin ellas, la importación del zip falla con un error de dependencia. En Odoo Community se instala desde Aplicaciones, buscando Automation Rules. En un servidor con gente trabajando esa instalación necesita bloquear tablas y puede fallar con un lock timeout: no es un dano, es la base de datos ocupada. Se resuelve reintentando en un momento de menos uso, o reiniciando el servicio de Odoo e instalandolo justo después.

Revisa que otros módulos fiscales tiene el Odoo.

Muchos Odoo dominicanos ya traen una localización propia, con menus de NCF, 606 y 607. Ese es el riesgo más subestimado de esta instalación: si el módulo existente también asigna numeración al confirmar la factura, los dos se pisan y puedes quemar un NCF autorizado en una factura de prueba. Antes de emitir nada, averigua cuándo asigna numeración ese módulo — automáticamente al validar, o solo al marcar alguna casilla. Hay que comprobarlo caso por caso.

En un Odoo multi-empresa, si vas a emitir bajo un RNC distinto al del negocio que ya opera ahí, crea una empresa nueva en vez de cambiarle el RNC a la existente. Aisla el RNC, las secuencias y el interruptor de e-CF, y deja intacta la contabilidad que ya hay.

1. Crear la empresa en FiscalFlow

Se empieza por aquí porque el pareo posterior necesita que la empresa exista.

En el panel de FiscalFlow, crea la empresa con su RNC, razón social y dirección fiscal.
Elige el ambiente DGII. Para todas las pruebas, testecf. Producción (ecf) solo cuando el ciclo completo esté validado.
Sube el certificado .p12 con su contraseña. Se guarda cifrado.

La dirección va en una sola línea. Un salto de línea se convierte en un caracter de control dentro del XML, y PHP y .NET lo normalizan distinto: la firma deja de validar del lado de la DGII y el rechazo no dice nada útil. Escríbela corrida, con espacios simples.

El RNC de la empresa tiene que ser exactamente el del titular del certificado. FiscalFlow los compara en cada emisión y refuerza la comprobación contra el RNC de la empresa en Odoo.

2. Instalar el módulo en Odoo

Activa el modo desarrollador. Lo normal es Ajustes → Ajustes generales → Herramientas de desarrollador, pero muchos Odoo personalizados reemplazan esa pantalla; el atajo que siempre funciona es abrir https://tu-odoo/odoo?debug=1.
Aplicaciones → Importar módulo y sube l10n_do_ecf_connect.zip.

Para actualizar a una versión nueva no hay que desinstalar nada: se sube el zip encima y Odoo lo procesa como actualización, conservando las secuencias y las URLs configuradas. Hazlo siempre por la interfaz: importado desde la terminal, el servidor en marcha se queda con el registro viejo y los campos nuevos fallan con errores incomprensibles hasta reiniciarlo.

3. Configurar la empresa en Odoo

Ajustes → Usuarios y empresas → Empresas, y abre la que va a emitir:

Pais República Dominicana, para que se cargue la localización fiscal y exista el ITBIS 18%.
NIF/RNC: exactamente el del certificado.
Dirección en una sola línea. Moneda DOP.
En la sección Facturación Electrónica (e-CF), marca el interruptor.

El indicador de ambiente que aparece ahí es de solo lectura: lo escribe FiscalFlow al parear y cada vez que el ambiente cambia. FiscalFlow es la única fuente de verdad de ese ajuste.

Si una factura no dispara nada, mira primero la empresa. La automatización filtra por empresa y se salta en silencio las que no tienen el interruptor. Si confirmas una factura y el contador de intentos queda en 0 con el estado vacío, casi siempre es que la factura pertenece a otra empresa.

4. Cargar las secuencias e-NCF

Facturación → Facturación Electrónica → Secuencias e-NCF. Para cada tipo que se vaya a emitir, copia el rango autorizado por la DGII:

Campo	Qué poner
Numero siguiente	El primero del rango autorizado que aún no se ha usado.
Fin del rango	El último número autorizado.
Vencimiento del rango	La fecha de vencimiento de la autorización, copiada de la Oficina Virtual.

Las secuencias son de tipo estandar, no "sin salto": la DGII autoriza un rango y no exige numeración contigua, y una numeración sin salto podría emitir dos veces el mismo e-NCF tras un rollback.

El vencimiento no es decorativo.

Viaja dentro del XML como FechaVencimientoSecuencia y la DGII lo valida contra la autorización real. Si no coincide, rechaza con el código 145 y nada en el mensaje apunta a la causa. Cópialo, no lo inventes. Lo mismo con los números: un e-NCF ya usado se rechaza con "Este número de secuencia ya ha sido utilizado", y si el mismo RNC emite desde varios sistemas, hay que reservar un bloque distinto para cada uno.

5. Crear el usuario de conexión y su API key

FiscalFlow entra a Odoo por JSON-RPC para leer la factura y escribir el resultado. Necesita un usuario propio y una API key.

Crea el usuario — por ejemplo ffs-connector — con perfil de administrador y ponle contraseña.
Entra a Odoo como ese usuario, en una ventana privada para no perder tu sesión.
My Preferences → Security → Add API Key. Confirma la contraseña, ponle nombre y copia la clave: solo se muestra una vez.

La API key se crea siempre para el usuario que está conectado, no para el usuario cuyo formulario tengas abierto. Si la generas como administrador desde la ficha de otro usuario, la clave sale a tu nombre.

Por que administrador, y que implica.

En Odoo 19 la duración de una API key está limitada por los permisos de su dueño: un usuario normal no puede emitir claves de más de 90 días. Al vencer, el pareo deja de funcionar. Solo los administradores pueden emitir claves sin vencimiento, y por eso el procedimiento recomendado usa un usuario administrador: para que la integración no se caiga sola cada tres meses.

El costo hay que decirlo claro: una API key de administrador da acceso total al ERP, no solo a facturación. Quien la tenga puede leer y escribir cualquier dato, exportar la contabilidad completa e instalar módulos. FiscalFlow pasa a custodiar una credencial con ese alcance.

En la práctica: usa un usuario dedicado y no la cuenta personal de nadie, y rota la clave si alguna vez se comparten logs o accesos. Si ese alcance no es aceptable, la alternativa es un usuario con permisos de facturación más el grupo técnico e-CF: conector FFS: funciona igual, con el costo de renovar la clave cada 90 días.

6. Congelar la URL base

Ajustes → Técnico → Parámetros del sistema → Nuevo: clave web.base.url.freeze, valor True.

Odoo sobrescribe web.base.url cada vez que un administrador inicia sesión, con la URL que ese administrador usó. FiscalFlow fija ese valor como huella de la instancia para detectar copias restauradas de la base de datos, así que sin congelarlo basta con que alguien entre por la IP del servidor, por http en vez de https o por un dominio alterno, para que todas las emisiones empiecen a fallar creyendo que es un clon.

Congelado, el guardián funciona como debe: la instancia legítima nunca cambia su URL, y una copia levantada en otro servidor si queda con una distinta.

7. Parear en FiscalFlow

En FiscalFlow, dentro de la empresa, entra a Integraciones y llena la tarjeta de Odoo:

Campo	Valor
URL de Odoo	La URL base, sin ninguna ruta después: `https://odoo.ejemplo.com`.
Base de datos	El nombre exacto, respetando mayusculas. Con el modo desarrollador activo aparece bajo el nombre de usuario, arriba a la derecha.
Usuario	El login del usuario de conexión del paso 5.
API key de Odoo	La clave del paso 5. Se guarda cifrada y nunca sale en una respuesta de la API.

Guarda y pulsa Probar conexión. FiscalFlow entra por RPC, lee el database.uuid y la web.base.url de esa instancia y las fija como huella. Desde ese momento, solo esa base de datos puede emitir bajo esta empresa: una copia restaurada en otro servidor se detecta y se bloquea antes de gastar un e-NCF.

Comprobación rápida: vuelve al formulario de la empresa en Odoo y mira el indicador de ambiente. Debe haberse llenado solo. Si aparece, el canal funciona en las dos direcciones. Una empresa de FiscalFlow se parea con un solo Odoo; apuntarla a otro servidor o a otra base de datos borra la huella anterior y desconecta el pareo previo.

8. Pegar las URLs en Odoo

La pantalla de Integraciones muestra dos URLs. Cópialas a Ajustes → Técnico → Acciones de servidor, filtrando por e-CF: las dos de tipo webhook son "notificar emisión a FFS" y "notificar anulación a FFS".

POST  https://api.fiscalflowsupport.com/api/v1/integrations/odoo/emit/{token}
POST  https://api.fiscalflowsupport.com/api/v1/integrations/odoo/cancel/{token}

La de emisión recibe la URL de emisión; la de anulación, la de anulación. No las cruces.

Esas URLs son credenciales. Llevan el token de conexión incrustado y es lo único que autentica la llamada: quien tenga la URL puede pedir emisiones bajo ese RNC. Trátalas como contrasenas, no las pegues en tickets, capturas ni chats. Si se filtran, rota el token desde FiscalFlow y vuelve a pegarlas — el token viejo deja de servir en el acto.

9. Emitir la primera factura

Empieza por una E32 de monto bajo: por debajo de RD$250,000 viaja por el canal síncrono y la DGII responde en segundos, así que sabes de inmediato si el certificado, el RNC y la secuencia están bien. Los demás tipos son asíncronos y su veredicto tarda unos minutos.

Factura de cliente nueva, en DOP, con una línea con ITBIS 18%.
Si el cliente tiene RNC, el módulo elige E31; si no, E32. Puedes forzar el tipo en la pestaña e-CF de la factura.
Confirma la factura. La automatización corre al confirmar: en borrador no pasa nada.

Cuando la DGII resuelve, FiscalFlow escribe el resultado en la factura — estado, código de seguridad, fecha de firma y el mensaje de error si lo hubo — y adjunta el PDF fiscal y el XML firmado.

"Enviar e imprimir" manda el PDF equivocado. Ese boton envía el PDF estandar de Odoo, que no es el documento fiscal: no lleva el código QR de la DGII ni el código de seguridad. El documento valido es el PDF que FiscalFlow adjunta a la factura.

Como se comporta el conector

Son detalles que no hacen falta para instalarlo, pero explican lo que verás cuando algo salga mal.

Un intento a la vez por factura. Mientras un envío anterior de esa misma factura siga sin resolverse, un intento nuevo se ignora. Esto evita el caso que se vio en producción: cuatro documentos sobre la misma factura, todos con el mismo e-NCF, todos rechazados por secuencia ya utilizada.
Un intento rechazado se descarta antes de reenviar. Si corriges la factura y vuelves a confirmarla, el documento rechazado anterior se descarta y el corregido entra limpio.
Los errores de datos se escriben en la factura, no en la respuesta HTTP. La llamada desde Odoo devuelve 202 casi siempre; si la factura no se puede convertir en un e-CF valido, el motivo aparece en la pestaña e-CF, en español y diciendo que corregir.
Si la DGII consumió el número de un documento rechazado, el e-NCF se limpia de la factura para que Odoo tome uno nuevo en el siguiente intento. Si no lo consumió, el número se conserva.

Si algo no funciona

Síntoma	Causa habitual
Se confirma la factura y no pasa nada: estado vacío, intentos en 0.	La automatización no llegó a correr. Casi siempre el interruptor de e-CF está apagado en esa empresa; si no, revisa que las dos reglas de automatización esten activas.
"La factura está en USD. Solo se pueden emitir e-CF en pesos dominicanos (DOP)."	El conector solo emite en DOP. Cambia la moneda de la factura.
"El RNC de la compañía en Odoo no coincide con el RNC del certificado configurado en FiscalFlow."	El NIF/RNC de la empresa en Odoo no es el del titular del certificado. En multi-empresa, suele ser que la factura pertenece a otra empresa.
"La secuencia e-NCF de este tipo de comprobante no tiene fecha de vencimiento del rango autorizado."	Falta el campo "Vencimiento del rango" en la secuencia. Si el campo no aparece, el módulo está desactualizado: vuelve a importar el zip.
Rechazo con código 145, "fecha de vencimiento de secuencia inválida".	El vencimiento cargado en la secuencia no es el que la DGII tiene autorizado.
"Este número de secuencia ya ha sido utilizado."	Ese e-NCF ya se emitió con ese RNC, casi siempre desde otro sistema. Adelanta el número siguiente a un bloque libre.
"Una nota de crédito requiere el e-NCF del comprobante que modifica."	Falta la referencia al comprobante original en la pestaña e-CF de la nota.
"La línea X tiene un importe negativo."	Un e-CF no admite líneas negativas. Para descontar, emite una nota de crédito.
"Esta instancia de Odoo no es la que está emparejada con FiscalFlow."	Cambio la huella. O se movió el dominio — vuelve a parear — o se restauro una copia de la base de datos en otro servidor, que es justo lo que el guardián evita.
"El formato del XML no es valido."	Un dato no cumple el esquema de la DGII. Suele ser una fecha o un campo de referencia. El XML que se envío queda guardado en FiscalFlow.
Se queda enviando más de unos minutos.	La DGII aún no resuelve. Es normal en los tipos asíncronos; FiscalFlow consulta el veredicto cada cinco minutos por su cuenta.

Cuando el rechazo venga de la DGII y el mensaje no baste, el XML firmado que se envío queda guardado en FiscalFlow. Compararlo contra el esquema es lo que resuelve estos casos en minutos en vez de a ciegas. La lista completa de rechazos esta en Errores y rechazos.