Integrar planilla con Odoo: diseño seguro para una pyme

Define qué se integra y qué no

Empieza por el asiento canónico: devengo de salarios, retenciones, aportes, préstamos y provisiones según el catálogo acordado. El pago y el reverso son procesos distintos; no mezcles el banco con el devengo solo porque ocurren en la misma quincena. Decide si el primer paso será un archivo de revisión, una importación controlada o una API, y deja el asiento en borrador mientras el contador valida las cuentas.

La referencia oficial del modelo account.move muestra que Odoo tiene un objeto para movimientos contables, pero los campos y reglas dependen de la instalación. No mapees por la etiqueta visible de una cuenta si el identificador puede repetirse entre compañías. Guarda el ID remoto, el hash del lote, la versión del mapeo y el resultado de la sincronización.

• Catálogo de cuentas y centros de costo activos por empresa.
• Conceptos canónicos de planilla y su tratamiento contable.
• Separación entre devengo, pago, reverso y corrección.
• Usuario técnico con permisos mínimos y clave rotada.
• Identidad idempotente para período, compañía y lote.

Usa la API con controles de acceso y reconciliación

Odoo 19 documenta solicitudes a la ruta JSON-2 con una clave API y controles estándar de acceso, reglas de registros y campos. La misma documentación recomienda claves dedicadas y rotación. No pongas una clave en el navegador ni en un archivo de configuración compartido. Guarda el secreto en un almacén seguro, limita la cuenta técnica y revoca la clave cuando termine una prueba.

La idempotencia merece una decisión explícita. Si un timeout ocurre después de crear un asiento, repetir la llamada puede duplicarlo. Usa una referencia externa o mecanismo de unicidad que haya sido probado en la instancia; si no existe, registra intención, consulta el estado remoto y concilia antes de enviar otra vez. No confíes en una búsqueda seguida de creación concurrente como única protección.

1. Confirma versión, edición, plan y acceso a la documentación de la base.
2. Lee cuentas, diarios y dimensiones autorizadas en una instancia de prueba.
3. Valida un lote balanceado y déjalo en borrador para revisión.
4. Registra ID remoto, hash, estado y evidencia de la importación.
5. Prueba timeout, doble envío, cuenta inactiva, permiso insuficiente y reverso.

Ejemplo hipotético: empresa de servicios con dos compañías

Ejemplo hipotético: una empresa administra una operación local y otra compañía relacionada en la misma instancia de Odoo. Ambas tienen una cuenta llamada «salarios», pero sus IDs, diarios y centros de costo son diferentes. Un exportador que solo compara nombres podría enviar el asiento al libro equivocado.

El piloto lee el catálogo por compañía, guarda el mapeo aprobado y genera un asiento de devengo en borrador con referencia estable. Un segundo envío recibe la misma identidad y se concilia en lugar de crear otro movimiento. El contador publica en Odoo solo después de revisar. Si luego se confirma un pago bancario, se registra como asiento separado; aprobar o enviar el borrador no ejecuta la transferencia.

Checklist accionable

Pide al contador y al administrador de Odoo que firmen esta lista para la instancia concreta. Una API accesible no implica que el mapeo contable sea correcto.

• Se confirmó Odoo 19 u otra versión real, edición, hosting y plan.
• La empresa entregó una instancia de prueba y catálogo de cuentas vigente.
• Cada concepto tiene cuenta, centro, vigencia y responsable.
• El usuario técnico tiene permisos mínimos y clave fuera del navegador.
• La clave expira, rota y puede revocarse sin perder trazabilidad.
• El asiento de devengo está separado del asiento de pago.
• La identidad de lote impide duplicados y se probó después de un timeout.
• Débitos y créditos concilian antes y después de importar.
• Un cambio remoto o cuenta archivada bloquea, no se corrige silenciosamente.
• Publicar en Odoo y registrar pago son acciones explícitas y autorizadas.

Qué acordar antes de contratar el proyecto

Antes de contratar, solicita un alcance escrito que identifique quién configura las cuentas, quién revisa los asientos y qué ocurre si cambia la instalación de Odoo. Incluye una muestra de planilla, una importación de prueba y una forma de corregir errores sin duplicar movimientos. StaffPass todavía no ofrece un conector Odoo disponible; esta guía explica los requisitos de un proyecto de integración, no una función incluida actualmente en los planes.

La aceptación real requiere importar en un entorno autorizado, revisar el asiento y conciliarlo con la planilla. Un endpoint que responde o un CSV que abre no demuestra que el sistema contable aceptó el movimiento ni que el resultado fiscal sea correcto.