Introducción
Los campos Binary no llaman la atención, pero están presentes en casi cualquier proyecto Odoo. Cada vez que un usuario sube un contrato firmado, adjunta una ficha técnica o guarda el logo de la empresa en un registro, detrás hay un campo Binary gestionando ese archivo. Saber qué guarda exactamente, dónde termina ese contenido y cuándo conviene usar otro tipo de campo es clave al diseñar formularios y extender modelos en Odoo.
Esta guía explica qué almacena un campo Binary, cómo el modo de adjunto influye en el rendimiento y la ubicación del fichero, cómo añadirlo con Odoo Studio o con código Python, y ejemplos prácticos en CRM, RR. HH., inventario y otras áreas habituales.
¿Qué es el campo Binary en Odoo?
En el ORM de Odoo, un campo Binary (fields.Binary) representa datos binarios crudos: documentos, imágenes o cualquier fichero que el usuario suba a una ficha. En la interfaz aparece como un control para subir y descargar archivos: subes el archivo desde el formulario y, con el mismo control, lo recuperas con un clic.
El aspecto técnico más relevante es dónde se guarda ese contenido. En versiones recientes, el modo por defecto usa el sistema de adjuntos: el contenido del fichero se almacena en la tabla ir.attachment y en el filestore del servidor, mientras que la columna del modelo sólo guarda una referencia al adjunto. Así se evita inflar las tablas principales y Odoo maneja los ficheros de forma más eficiente.
En Odoo Studio, el campo Binary aparece como File en el selector de campos y actúa como un control sencillo de subida/descarga. Para imágenes, Odoo ofrece además fields.Image, que incorpora redimensionado automático y vista previa en miniatura; trataremos ese tipo en su sección correspondiente.
Ejemplo práctico en definición Python
from odoo import fields, models
class ResPartner(models.Model):
_inherit = 'res.partner'
x_signed_contract = fields.Binary(
string='Signed Contract',
attachment=True,
)
x_signed_contract_filename = fields.Char(
string='Signed Contract Filename',
)
Fíjate en el campo complementario x_signed_contract_filename: es habitual acompañar un Binary con un Char que contenga el nombre original del archivo. Odoo usa ese sufijo _filename para mostrar el nombre correcto en la interfaz; sin él, las descargas suelen salir con un nombre genérico.
Cómo funciona el campo
Cuando añades un Binary al modelo, Odoo crea la columna en la base de datos al instalar o actualizar el módulo. No necesitas ejecutar SQL manualmente.
Modos de almacenamiento
El parámetro attachment en un Binary determina dónde se guardan realmente los bytes del fichero:
- attachment=True (recomendado): El contenido del fichero se guarda en ir.attachment y se vincula al registro por modelo y ID; la columna del modelo solo referencia ese adjunto. Mantiene las tablas del modelo ligeras y aprovecha el filestore de Odoo.
- attachment=False: Los datos en base64 se guardan directamente en la columna del modelo. Esto hace que las tablas crezcan mucho y las consultas se ralenticen. Evítalo salvo para miniaturas muy pequeñas.
Formato de los datos
Los Binary almacenan y devuelven datos en base64. Si accedes mediante el ORM o la API XML-RPC obtendrás un string en base64; al escribir, debes proporcionar también un string base64.
En la práctica esto implica codificar antes de escribir y decodificar al leer:
import base64
# Escritura de un fichero en un Binary
with open('document.pdf', 'rb') as f:
encoded = base64.b64encode(f.read()).decode('utf-8')
record.write({'x_signed_contract': encoded})
# Lectura de un fichero desde un Binary
raw_bytes = base64.b64decode(record.x_signed_contract)
Atributos clave del campo
Estas son las opciones más relevantes que puedes configurar en un Binary dentro del framework de Odoo:
- attachment: Booleano. Indica si se usa ir.attachment (True) o la columna directa (False). En versiones recientes, el valor por defecto es True.
- string: Etiqueta que se muestra en la interfaz.
- required: Convierte el campo en obligatorio antes de guardar.
- compute: Permite calcular el valor mediante un método Python, por ejemplo generar un PDF al vuelo.
- store: Usado con compute, indica si el valor calculado se persiste en la base de datos.
- groups: Restringe el acceso a determinados grupos de usuarios. Útil para documentos sensibles.
- copy: Controla si el valor se duplica al copiar un registro; el comportamiento por defecto puede variar según el modo attachment y la versión.
La subclase fields.Image
fields.Image es una variante de fields.Binary introducida en Odoo 13 pensada para imágenes: aplica redimensionado automático hasta un máximo configurable, ofrece un tamaño de preview para miniaturas y muestra la imagen en el formulario. Para fotos de producto, retratos o logos, emplea fields.Image en lugar de un Binary normal: evita subidas excesivas y mejora la experiencia de usuario.
Presentación en vistas
En formularios, el widget por defecto de un Binary es un control de subida/descarga. Para ver miniaturas de imágenes usa el widget image. En vistas de lista no conviene mostrar el campo Binary tal cual, porque cargar el contenido completo de cada fila genera transferencia innecesaria: lo normal es mostrar un icono o un booleano que indique si existe adjunto.
Casos de uso en la empresa
Dónde se usa en la práctica
CRM: Almacenar NDAs o contratos firmados en el registro del cliente
En ventas es habitual adjuntar contratos o acuerdos firmados al cliente o a la oportunidad. Añadir un Binary en res.partner o crm.lead da acceso inmediato al documento desde la ficha comercial, evitando herramientas externas y manteniendo todo junto en el flujo de ventas.
RR. HH.: Documentación de empleados
RR. HH. suele necesitar guardar DNI, permisos de trabajo, contratos firmados o certificados de formación. Un Binary en hr.employee permite almacenar esos ficheros bajo las reglas de acceso de Odoo. Usando el parámetro groups restringes quién puede ver los documentos (por ejemplo solo responsables de RR. HH.) mientras otros perfiles ven el resto de la ficha sin acceder a los archivos.
Inventario: Fichas técnicas y hojas de seguridad
Productos técnicos requieren PDF de especificaciones, hojas de seguridad o certificados. Añadir un Binary a product.template facilita que compras y almacén consulten la documentación directamente en la ficha del artículo. Es una petición común en empresas manufactureras y de distribución y su implementación es sencilla con Studio o un módulo Python.
Comercial: Sello o firma autorizada para presupuestos
Algunas empresas necesitan incluir un sello o una firma en los documentos impresos. Un fields.Image en res.company guarda ese recurso gráfico y lo referencia en plantillas QWeb para que presupuestos y albaranes impresos lleven la firma automáticamente, evitando manipulación manual y errores en procesos con gran volumen de documentos.
Contabilidad: Comprobantes escaneados en gastos
En la gestión de gastos es habitual adjuntar el recibo o factura escaneada como comprobante. Aunque el sistema de adjuntos nativo de Odoo ya cubre muchos casos, en modelos personalizados o integraciones externas un Binary específico permite almacenar el PDF o la imagen en el registro del gasto e integrarlo en la lógica de aprobaciones.
Crear o personalizar un campo Binary
Formas de añadir un Binary
Hay tres vías para incorporar un Binary según cuánto control necesites y el contexto técnico.
Con Odoo Studio (sin código)
- Odoo Studio es la herramienta low-code integrada. Pasos básicos para añadir un Binary sin tocar código:
- Abre Odoo Studio desde el menú principal.
- Ve al formulario donde quieres el campo.
- Arrastra un campo File desde el selector al formulario.
- Configura la etiqueta y condiciones de visibilidad en el panel de propiedades.
Guarda y cierra Studio. Studio crea el campo con prefijo x_studio_ y, por defecto, usa attachment=True. Es la forma más accesible para usuarios de negocio que necesitan subir archivos sin desarrolladores.
Con Python en un módulo personalizado
Para desarrollos versionados y desplegables en múltiples entornos, la forma recomendada es definir Binary en código Python dentro de un módulo:
from odoo import fields, models
class HrEmployee(models.Model):
_inherit = 'hr.employee'
x_id_document = fields.Binary(
string='ID Document',
attachment=True,
groups='hr.group_hr_user',
)
x_id_document_filename = fields.Char(
string='ID Document Filename',
)
Tras declarar el campo, añádelo en la vista de formulario con widget binary y el atributo filename apuntando al Char complementario. Odoo crea las columnas automáticamente al instalar o actualizar el módulo, y este enfoque es compatible con despliegues en Odoo.sh y on‑premise.
Mediante la API XML-RPC
Si gestionas la configuración de forma remota (scripts de aprovisionamiento o notebooks), puedes crear campos Binary vía XML-RPC:
field_id = models.execute_kw(
ODOO_DB, uid, ODOO_API_KEY,
'ir.model.fields', 'create',
[{
'name': 'x_custom_document',
'field_description': 'Custom Document',
'model_id': model_id,
'ttype': 'binary',
'state': 'manual',
}]
)
El estado state: 'manual' indica que el campo se creó de forma manual y no por un módulo. En versiones actuales, los campos creados por la API también usan attachment=True por defecto. Es útil en scripts de automatización y despliegues remotos.
Buenas prácticas
1. Usa siempre attachment=True
Salvo que tengas una razón técnica muy concreta para lo contrario, emplea attachment=True. Mantiene las tablas ligeras, evita consultas lentas y aprovecha el filestore. Para cualquier fichero mayor que una miniatura, el modo adjunto es la opción correcta.
2. Acompaña el Binary con un campo Char para el nombre de fichero
Incluye siempre un campo _filename junto al Binary. Sin él, al descargar el fichero los usuarios reciben un nombre genérico. Es una línea de código que mejora notablemente la experiencia.
3. Usa fields.Image para imágenes
Si guardas fotos de producto, retratos o logotipos, emplea fields.Image: limita el tamaño, genera miniaturas y evita cargas innecesarias. Elegir el tipo adecuado según el contenido es esencial para un modelo de datos limpio.
4. Controla acceso con groups
Documentos sensibles deben restringirse con el parámetro groups para limitar lectura/escritura a roles concretos. Es clave para privacidad y requisitos de auditoría.
5. Maneja el base64 con cuidado en el código
Al leer o escribir Binary programáticamente, controla explícitamente la codificación: usa base64.b64encode(file_bytes).decode('utf-8') al escribir y base64.b64decode(value) al leer. Suponer el formato correcto es una fuente frecuente de errores que aparecen al procesar ficheros reales.
Errores comunes
Problemas por usar attachment=False en ficheros grandes
Guardar contenido en la columna del modelo puede inflar la tabla PostgreSQL rápidamente. Unos pocos PDFs con attachment=False añaden cientos de megas, ralentizando todas las consultas. Migrar después a attachment=True exige scripts y planificación; por eso es una equivocación de alto impacto desde el inicio.
Olvidar el campo de nombre de fichero
Sin el Char complementario, las descargas salen con nombres genéricos, una molestia constante que hace que la implementación parezca inacabada. Añadir el campo es rápido y debería ser estándar en cualquier Binary visible al usuario.
Confundir Binary con Image
Usar un Binary para imágenes evita las ventajas de fields.Image (redimensionado, miniaturas) y puede llevar a subidas masivas que ralentizan formularios. Al revés, usar fields.Image para PDFs o documentos provoca errores porque Odoo intentará tratarlos como imágenes. La regla: asigna el tipo acorde al contenido esperado.
Incluir Binarys en vistas de lista
Mostrar un Binary en una vista de lista obliga a cargar el contenido completo de cada fila visible. En listados de 50 registros puede suponer transferir megas innecesarios. Mejor mostrar un booleano calculado o un icono que indique existencia de adjunto.
No comprobar False antes de procesar
Un Binary sin valor devuelve False en Python. Intentar decodificarlo directamente provoca TypeError. Siempre comprueba: if record.x_document: data = base64.b64decode(record.x_document). Esto aplica en métodos compute, acciones servidor y cualquier procesamiento condicional.
Conclusión
El campo Binary es sencillo pero fundamental en el modelo de datos de Odoo. Permite integrar el almacenamiento de ficheros con la interfaz, el sistema de adjuntos y los controles de acceso de la plataforma.
Las prácticas esenciales: usar attachment=True, añadir el Char para el nombre del fichero, optar por fields.Image para contenido visual, proteger documentos sensibles con groups y gestionar el base64 correctamente en el código. Estas pautas evitan los problemas más comunes antes de que lleguen a producción.
Tanto si añades un campo de archivo con Odoo Studio, desarrollas un módulo en Python o creas campos vía la API, acertar con los Binary desde el principio conduce a una implementación más ordenada y fiable.
En Dasolo acompañamos a empresas en la implantación, personalización y optimización de Odoo en todas las áreas. Si necesitas diseñar un modelo de datos apropiado, crear flujos de gestión de ficheros o desarrollar un módulo a medida, nuestro equipo puede ayudarte. Contacta con nosotros y hablemos de tu proyecto Odoo.