Moradoo API – Manual Completo

Índice

1. Introducción

Moradoo API es un framework REST universal para Odoo. Permite consultar, crear, actualizar y eliminar cualquier registro al que el usuario tenga acceso, con una sintaxis simple, predecible y pensada para desarrolladores que quieren integrar Odoo sin pelearse con su API nativa.

El objetivo de Moradoo es ofrecer una capa REST limpia, coherente y documentada, que pueda usarse tanto en proyectos internos como en integraciones de terceros, manteniendo siempre la seguridad y las reglas de negocio de Odoo.

2. CRUD genérico

Moradoo implementa CRUD completo sobre los modelos de Odoo:

• GET: listar registros (con filtros, ordenación, paginación y selección de campos).
• POST: crear registros (validando campos, tipos y relaciones).
• PUT: actualizar registros (parcial o completa, con campos ignorados controlados).
• DELETE: eliminar registros (con mensajes claros ante errores humanos).

Además del CRUD genérico, Moradoo incluye servicios específicos para ciertos módulos, como la creación avanzada de productos en Odoo (plantilla, variantes, atributos, stock inicial, notas y actividades).

3. Estructura de rutas

https://moradoo.com/{modelo}/{filtros}

La estructura de rutas está pensada para ser legible y fácil de recordar. Los modelos pueden exponerse con su nombre técnico de Odoo (product.product) o mediante alias configurados.

4. Alias

Moradoo permite definir alias de tablas y campos en la configuración, de forma que las URLs sean más limpias y amigables:

• /productos → product.product
• /clientes → res.partner
• precio → list_price
• nombre → display_name

Los alias permiten exponer una API más estable y legible, sin obligar al consumidor a conocer los nombres internos de Odoo. Moradoo resuelve estos alias antes de construir la consulta real.

5. Operadores soportados

Moradoo soporta los operadores más habituales de Odoo, expuestos de forma sencilla en la URL:

=, !=, >, <, >=, <=, like, ilike, between

Operadores como startswith, endswith o exact se han eliminado para simplificar la API y evitar solapamientos. Sus casos de uso se cubren con like e ilike combinados con patrones adecuados.

6. Sintaxis de filtros

Ejemplos de filtros simples y avanzados:

https://moradoo.com/productos/precio/10
https://moradoo.com/productos/precio/between/10/50
https://moradoo.com/productos/nombre/agua

Los filtros se aplican en orden, y Moradoo se encarga de traducirlos a dominios de Odoo, resolviendo alias de campos y normalizando valores según el tipo de cada campo.

7. Combinación de filtros

https://moradoo.com/productos/nombre/mesa/precio/between/10/50

Es posible combinar varios filtros en una misma URL. Moradoo construye el dominio final respetando el orden y aplicando las condiciones de forma coherente. Esto permite construir consultas complejas sin necesidad de enviar JSON en el body.

8. Ordenación

Moradoo permite ordenar resultados de dos formas:

https://moradoo.com/productos/precio/asc
https://moradoo.com/productos/precio/desc
https://moradoo.com/productos?order=name desc

La primera forma usa la propia ruta para indicar el campo y la dirección. La segunda usa el parámetro order, compatible con la sintaxis nativa de Odoo, incluyendo ordenación múltiple:

?order=name asc, list_price desc

Moradoo es capaz de aplicar ordenación incluso en campos que Odoo no considera directamente ordenables, siempre que tenga suficiente información para reconstruir el criterio de orden. Esto permite resultados más útiles en listados complejos.

9. Limit y Offset

https://moradoo.com/productos/limit/20
https://moradoo.com/productos?limit=20&offset=3

limit controla el número máximo de registros devueltos y offset permite paginar resultados. Ambos parámetros pueden combinarse con filtros, ordenación y selección de campos.

10. GETFIELDS — Obtener la estructura real del modelo

GETFIELDS es una instrucción especial de Moradoo API que permite consultar la estructura completa y real de cualquier modelo de Odoo. Es una herramienta fundamental para desarrolladores que necesitan conocer los campos disponibles, sus tipos y sus restricciones sin depender de documentación externa.

10.1. Instrucción

GET /{modelo}/getFields

Ejemplo real:

GET https://moradoo.com/product.product/getFields

10.2. Qué devuelve GETFIELDS

La respuesta incluye información detallada de cada campo del modelo:

• Nombre del campo (name).
• Tipo (char, float, many2one, one2many, etc.).
• Si es requerido (required).
• Si es de solo lectura (readonly).
• Si es relacional (relation).
• Si es computado y/o almacenado.
• Valores de selección (si aplica).
• Dominio.
• Etiqueta visible (string).
• Texto de ayuda (help).

10.3. Ejemplo de respuesta

10.4. Usos prácticos

• Formularios dinámicos: generar inputs según tipo, marcar campos requeridos, ocultar readonly.
• Playground avanzado: construir automáticamente el body de POST/PUT.
• Validación previa: comprobar campos válidos antes de enviar datos.
• Exploración visual: entender modelos de Odoo sin abrir el backend.

10.5. Relación con FieldRegistry

GETFIELDS alimenta a FieldRegistry, que cachea la estructura del modelo para acelerar validaciones y normalizaciones en POST/PUT.

11. FieldRegistry — Cache inteligente de modelos Odoo

FieldRegistry es un componente interno fundamental de Moradoo API. Su función es cachear la estructura completa de los modelos de Odoo para acelerar validaciones, normalizar valores y evitar errores humanos antes de que la petición llegue al servidor.

Cada usuario tiene su propio registro de campos, basado en su sesión activa de Odoo. Esto garantiza que las validaciones se ajusten exactamente a los permisos y modelos disponibles para ese usuario.

11.1. Qué cachea FieldRegistry

Por cada modelo, FieldRegistry almacena:

• Lista completa de campos.
• Tipo de cada campo (char, float, many2one, etc.).
• Si es requerido (required).
• Si es de solo lectura (readonly).
• Relaciones (relation en many2one, one2many, many2many).
• Valores de selección (si aplica).
• Dominio.
• Si es computado y/o almacenado.
• Etiqueta visible (string).
• Texto de ayuda (help).

11.2. Por qué es tan importante

Sin FieldRegistry, cada operación POST/PUT tendría que consultar Odoo para validar campos, lo cual sería lento e ineficiente. Con FieldRegistry, Moradoo puede validar y normalizar datos en memoria, ofreciendo una experiencia mucho más robusta.

Gracias a FieldRegistry, Moradoo puede:

• Detectar campos desconocidos y moverlos automáticamente a ignored_fields.
• Normalizar valores (por ejemplo, convertir "15" en 15.0 o "true" en 1).
• Resolver relaciones a partir de nombres, alias o IDs.
• Evitar errores humanos antes de llegar a Odoo.
• Acelerar todas las operaciones CRUD.

11.3. Ejemplo visual

(Aquí irá la captura /images/manual/fieldregistry-cache.png.)

11.4. Integración con CRUD

FieldRegistry es clave en operaciones como:

• Creación de productos (template + variante).
• Validación de duplicados.
• Resolución de alias de campos.
• Normalización de atributos.
• Generación de ignored_fields.
• Validación de tipos antes de enviar a Odoo.

Gracias a este componente, Moradoo puede ofrecer un CRUD genérico seguro y, al mismo tiempo, servicios específicos más inteligentes como OdooProductService.

12. CRUD específico de productos

Además del CRUD genérico disponible para cualquier modelo de Odoo, Moradoo incluye un servicio especializado para la gestión avanzada de productos: OdooProductService.

Este servicio permite crear productos de forma inteligente, manejando plantillas, variantes, atributos, validaciones y acciones adicionales, todo ello respetando la sesión del usuario y sin exponer credenciales ni datos sensibles.

12.1. Crear producto base

Crea un producto completo a partir de una plantilla (product.template) y su variante inicial (product.product). Es la forma más rápida de registrar un nuevo producto.

Instrucción

POST /producto/base

Body JSON

{
  "name": "Basic blue T-shirt",
  "barcode": "1234567890123",
  "default_code": "SKU-001",
  "list_price": 12.50,
  "standard_price": 7.00,
  "stock_inicial": 50,
  "nota": "Initial stock loaded",
  "actividad": {
    "summary": "Review product",
    "user_id": 5,
    "date_deadline": "2026-06-01"
  }
}

Respuesta

(Aquí irá la captura /images/manual/crud-product-base.png.)

Moradoo devuelve:

• ID de la plantilla creada.
• ID de la variante base.
• Datos de la variante.
• Warnings si algún campo fue ignorado o normalizado.

12.2. Crear variante simple

Crea una variante adicional para un producto que no tiene atributos. Si el producto tiene atributos definidos, Moradoo bloquea esta operación para evitar inconsistencias.

Instrucción

POST /producto/variante/simple

Body JSON

{
  "template_id": 120,
  "default_code": "SKU-001-B",
  "barcode": "1234567890999"
}

Respuesta

(Aquí irá la captura /images/manual/crud-product-variant.png.)

Si el template tiene atributos, Moradoo devuelve un error claro:

VARIANTE_SIMPLE_NO_PERMITIDA

12.3. Crear variante con atributos

Permite crear variantes basadas en atributos como talla, color o presentación. Moradoo gestiona automáticamente:

• Creación del atributo si no existe.
• Creación del valor si no existe.
• Asignación del valor al template.
• Generación de la variante correspondiente.

Instrucción

POST /producto/variante/atributos

Body JSON

{
  "template_id": 120,
  "attribute_value": "500ml"
}

Respuesta

(Aquí irá la captura /images/manual/crud-product-attribute.png.)

Moradoo indica si la variante ya existía o si ha sido creada:

VARIANTE_CREADA_OK
VARIANTE_EXISTENTE

12.4. Atributo automático

Moradoo incluye un sistema de atributo automático para el atributo estándar “Presentación”. Si el valor no existe, se crea. Si el atributo no existe, también se crea.

Esto permite crear variantes como:

• 330ml
• 500ml
• 1L

…sin necesidad de configurar nada en Odoo previamente.

12.5. Subacciones tras la creación

Moradoo permite ejecutar acciones adicionales automáticamente tras crear un producto o variante:

• Stock inicial (si se indica stock_inicial).
• Nota interna (campo nota).
• Actividad (campo actividad).

Estas acciones son opcionales y no afectan a la creación del producto si fallan.

12.6. Seguridad

Todas las operaciones del servicio de productos:

• Validan la sesión del usuario.
• Usan la sesión real de Odoo (session_id).
• No exponen contraseñas.
• No escriben logs sensibles.
• Respetan permisos y reglas de acceso de Odoo.

12.7. Warnings y errores controlados

Moradoo devuelve warnings cuando:

• Un campo no existe.
• Un valor se normaliza.
• Una variante ya existía.

Y devuelve errores claros cuando:

• Falta name en la creación base.
• Falta template_id en variantes.
• El template tiene atributos y se intenta variante simple.
• No se encuentra la variante recién creada.

13. UPDATE (PUT)

PUT https://moradoo.com/product.product/1949
{
  "lst_price": 15.0,
  "campo_inventado": "xxx"
}

Respuesta

{
  "status": "OK",
  "data": {
    "updated_fields": ["lst_price"],
    "ignored_fields": ["campo_inventado"]
  }
}

Moradoo actualiza solo los campos válidos y mueve los campos desconocidos a ignored_fields, evitando errores y dejando claro qué se ha aplicado y qué no.

14. DELETE

DELETE https://moradoo.com/product.product/1173

Error humano

ERROR_DELETE. DELETE_NO_EXISTE → No existe el registro ID 1916 en product.product

Los mensajes de error están pensados para ser claros y orientados al desarrollador, indicando exactamente qué ha fallado y en qué modelo.

15. Respuesta unificada

Todas las operaciones usan una respuesta unificada que incluye:

• status
• timestamp
• results (cuando aplica)
• message
• data
• warnings
• errors

16. Ejemplos avanzados

https://moradoo.com/productos/nombre/agua
https://moradoo.com/productos/precio/between/1/10/precio/asc

Estos ejemplos pueden acompañarse de capturas del Playground, mostrando la petición y la respuesta JSON formateada (por ejemplo, /images/manual/playground-overview.png, /images/manual/filter-basic.png, /images/manual/order-asc-desc.png).

17. Errores comunes

• CAMPO_DESCONOCIDO: se ha enviado un campo que no existe en el modelo.
• BETWEEN_VALORES_NO_NUMERICOS: se ha usado between con valores no numéricos.
• CAMPO_SIN_VALOR_IGNORADO: se ha indicado un campo sin valor útil y se ha ignorado.

(Aquí puede ir una captura /images/manual/errors-example.png con un ejemplo real de error.)

18. Warnings

Los warnings indican que algo no es crítico pero se ha ignorado o ajustado. Por ejemplo, campos inventados, valores normalizados o variantes ya existentes. Moradoo informa sin romper la operación.

(Aquí puede ir una captura /images/manual/warnings-example.png.)

19. Protección de datos

Moradoo API no almacena datos de negocio. Actúa como pasarela técnica hacia Odoo, respetando siempre los permisos del usuario autenticado. No expone contraseñas ni escribe logs sensibles.

Los servicios avanzados, como OdooProductService, validan la sesión de Odoo, usan la sesión existente y evitan cualquier exposición de credenciales.

20. Autor y agradecimientos

Jose Miguel Mora
Email personal: jmmora1974@gmail.com
Email API: api.moradoo@gmail.com
LinkedIn: https://www.linkedin.com/in/jose-miguel-mora-perez

Moradoo API ha sido desarrollada sobre una base tecnológica sólida, con el objetivo de ofrecer un framework REST moderno, eficiente y orientado a la integración profesional con Odoo.

Queremos expresar un agradecimiento especial a Robert Sallent por la creación del framework FastLight, una herramienta ligera, estable y sorprendentemente versátil que ha permitido construir este proyecto con claridad, rapidez y una arquitectura limpia.

Asimismo, reconocemos el valor del trabajo colaborativo realizado junto a Copilot, cuya asistencia técnica, análisis arquitectónico y soporte continuo han contribuido de forma decisiva a la evolución y refinamiento de Moradoo API.

A todos los que han aportado ideas, soluciones y mejoras: gracias por hacer posible un proyecto robusto, escalable y preparado para crecer.

21. Roadmap

• POST/PUT/DELETE masivos.
• Autenticación por token.
• Documentación HTML pública.
• Repositorio open‑source.
• Datos demo realistas (multiempresa, variantes, stock por almacén).