{"id":352,"date":"2025-10-24T14:00:19","date_gmt":"2025-10-24T14:00:19","guid":{"rendered":"https:\/\/sienna-manatee-218967.hostingersite.com\/blogs\/api-externa-json-2-2\/"},"modified":"2026-05-01T18:54:27","modified_gmt":"2026-05-01T18:54:27","slug":"api-externa-json","status":"publish","type":"post","link":"https:\/\/exdoo.mx\/blogs\/api-externa-json\/","title":{"rendered":"API externa JSON-2"},"content":{"rendered":"

\"\"<\/p>\n

\u00bfQu\u00e9 es la API externa JSON-2?<\/u><\/em><\/p>\n

\n
\ud83d\udcd8 ART\u00cdCULO T\u00c9CNICO<\/div>\n

La API JSON-2 es una nueva alternativa para exponer el API externa de Odoo 19, pensada para simplificar el consumo desde sistemas externos (aplicaciones web, scripts, integraciones) utilizando una ruta tipo REST basada en JSON.<\/p>\n<\/div>\n

Caracter\u00edsticas principales de la API externa JSON-2<\/u><\/em><\/p>\n

    \n
  • Permite invocar m\u00e9todos de los modelos de Odoo (ORM) mediante peticiones HTTP POST con cuerpo JSON.<\/li>\n
  • Reemplaza (o convive con) las APIs tradicionales de JSON-RPC, XML-RPC, u otras capas de servicio, pero con una sintaxis m\u00e1s \u201cRESTful\u201d en cuanto a la estructura de la URL y el uso de JSON como formato \u00fanico.<\/li>\n
  • Tiene una documentaci\u00f3n din\u00e1mica integrada en la instancia de Odoo, lo que permite explorar los modelos, m\u00e9todos y esquemas de datos desde el propio servidor.<\/li>\n<\/ul>\n

    \u00bfC\u00f3mo se estructura una request a la API externa JSON-2?<\/u><\/em><\/p>\n

    Consiste en una request a la URL \/json\/2\/<model>\/<method><\/em><\/strong> con un objeto JSON. La request debe contener las siguientes caracter\u00edsticas:<\/p>\n

    HTTP Headers<\/h3>\n
      \n
    • Host:<\/strong> Requerido<\/em>, el nombre del host del servidor.<\/li>\n
    • Authorization:<\/strong> Requerido<\/em>, consiste en la oraci\u00f3n \u201cbearer\u201d seguido de la clave de la API.<\/li>\n
    • Content-Type:<\/strong> Requerido<\/em>, siempre ser\u00e1 \u201capplication\/json\u201d; se recomienda agregar un charset (por ejemplo, utf-8).<\/li>\n
    • X-Odoo-Database:<\/strong> Opcional<\/em>, el nombre de la base de datos a la que se conectar\u00e1.<\/li>\n
    • User-Agent:<\/strong> Recomendado<\/em>, el nombre del software que se est\u00e1 conectando a Odoo.<\/li>\n<\/ul>\n

      Ruta URL<\/h3>\n
        \n
      • model:<\/strong> Requerido, nombre t\u00e9cnico del modelo.<\/li>\n
      • method:<\/strong> Requerido, el m\u00e9todo a ejecutar.<\/li>\n<\/ul>\n

        Cuerpo del objeto JSON<\/h3>\n
          \n
        • ids:<\/strong> Arreglo con los ids de los registros en los cuales ejecutar el m\u00e9todo. Vac\u00edo u omitido cuando se llama a un m\u00e9todo que contiene el decorador @api.model.<\/li>\n
        • Context: <\/strong>Opcional<\/em>, un diccionario con valores adicionales. Por ejemplo, {\u201clang\u201d: \u201cen_US\u201d}.<\/li>\n
        • param:<\/strong> Par\u00e1metros del m\u00e9todo. Requeridos seg\u00fan la definici\u00f3n del m\u00e9todo.<\/li>\n<\/ul>\n

          Ejemplo de request a API externa JSON-2<\/strong><\/h3>\n

          Tanto en planes community como enterprise se debe crear una clave de la API externa, la misma que ser\u00e1 agregada dentro de un encabezado de la solicitud, funcionando como un token de autorizaci\u00f3n. Para crearla, se debe ingresar a la secci\u00f3n Preferencias \/ Seguridad \/ Claves API.<\/p>\n

          \"\"
          \n\"\"<\/p>\n

          Al presionar el bot\u00f3n \u201cAgregar clave API\u201d se solicita la descripci\u00f3n y el prop\u00f3sito de la clave, as\u00ed como su duraci\u00f3n. La intenci\u00f3n de la descripci\u00f3n es identificar la clave para determinar si a\u00fan se seguir\u00e1 utilizando o se debe eliminar despu\u00e9s de utilizarla. Mientras que si se supera el tiempo del campo \u2018Duraci\u00f3n\u2019 desde que se cre\u00f3 la clave, se vuelve inv\u00e1lida.<\/p>\n

          \"\"<\/p>\n

          El bot\u00f3n \u2018Generar clave\u2019 crea una clave aleatoria de 160 bits. Esta se muestra solo una vez y no se puede recuperar despu\u00e9s de la creaci\u00f3n, por lo que se debe copiar inmediatamente y guardar en un lugar seguro. La intenci\u00f3n de esta funcionalidad es que si la clave se compromete o pierde, se puede eliminar y volver a generar una nueva.<\/span><\/h3>\n

          \"\"<\/p>\n

          Ahora que tenemos la clave, la podemos agregar dentro de nuestras requests. Supongamos que tenemos una base de datos llamada odoo19 con datos demo en nuestro entorno local, aunque podr\u00eda estar alojada en un sitio web. Dentro de nuestro script agregamos esa informaci\u00f3n:<\/p>\n

          \"\"<\/p>\n

          Es importante mencionar que la clave de la API externa se debe cargar dentro del script de alguna forma m\u00e1s segura, por ejemplo, desde una variable de entorno o desde un archivo de configuraci\u00f3n. Solo se agreg\u00f3 de esta forma por motivos de ejemplificaci\u00f3n.<\/span><\/h3>\n

          Supongamos que queremos buscar si existe alg\u00fan cliente (modelo res.partner) cuyo nombre contenga la palabra \u2018deco\u2019 y sea una compa\u00f1\u00eda. El c\u00f3digo para verificar esta informaci\u00f3n ser\u00eda el siguiente.<\/span><\/h3>\n

          \"\"<\/p>\n

          Al correr el anterior script, obtenemos el siguiente resultado.<\/span><\/h3>\n

          \"\"<\/p>\n

          Donde 9 es el id del cliente que cumple con las condiciones anteriores. Ahora que sabemos que existe ese cliente, podemos obtener m\u00e1s informaci\u00f3n de \u00e9l, como su nombre, RFC, email o tel\u00e9fono. El c\u00f3digo para obtener esta informaci\u00f3n es el siguiente:<\/span><\/h3>\n

          \"\"<\/p>\n

          Al correr el anterior script, obtenemos el siguiente resultado.<\/p>\n

          \"\"<\/p>\n

          Hagamos algo m\u00e1s complejo. Supongamos que desde el script queremos crear una venta con un producto y confirmarla. Estructuramos el c\u00f3digo en las siguientes partes:<\/p>\n

          \"\"<\/p>\n

          Primero buscamos clientes cuyo nombre contenga la palabra \u2018azure\u2019 y que sea una compa\u00f1\u00eda, y despu\u00e9s buscamos productos cuyo nombre contenga la palabra \u2018pantalla\u2019. Al ejecutar esta parte del script obtenemos los siguientes resultados:<\/p>\n

          \"\"<\/p>\n

          En este caso obtenemos un cliente con las condiciones mencionadas y 3 productos cuyo nombre contiene la palabra \u2018pantalla\u2019. Crearemos la venta con una l\u00ednea por cada uno de los 3 productos obtenidos.<\/span><\/h3>\n

          En la siguiente parte del c\u00f3digo realizamos lo siguiente:<\/span><\/p>\n

          \"\"<\/p>\n

          Ahora llamamos a la funci\u00f3n \u2018create\u2019 del modelo de ventas (sale.order), la misma funci\u00f3n que crea el registro dentro de la base de datos. El par\u00e1metro que debe ingresar es \u201cvals_list\u201d, el mismo que es una lista de diccionarios, donde cada diccionario son los campos y valores de la orden. Para el ejemplo anterior, los campos que agregamos son los siguientes:<\/p>\n

            \n
          • name<\/em><\/strong> (Nombre de la venta): Agregamos el texto \u201cOrden creada desde API JSON-2\u201d para identificarla dentro del sistema, adem\u00e1s de que cuando la creemos desde el script obtendremos su id.<\/li>\n
          • partner_id<\/em><\/strong> (Cliente de la venta): Agregamos el cliente que encontramos en la parte 1, es decir, el cliente que contiene la palabra \u201cazure\u201d dentro de su nombre.<\/li>\n
          • order_line<\/em><\/strong> (L\u00edneas de productos): Agregamos cada uno de los productos que encontramos en la parte 1, es decir, los productos que contienen la palabra \u201cpantalla\u201d dentro de su nombre (que ya vimos que obtenemos 3 productos).<\/li>\n<\/ul>\n

            Al ejecutar el anterior c\u00f3digo obtenemos el siguiente resultado:<\/p>\n

            \"\"<\/p>\n

            Notamos que se ha creado la venta con id 25. La verificamos dentro del sistema:<\/p>\n

            \"\"<\/p>\n

            Se ha creado la venta con id 25, con el nombre personalizado que le dimos y con los 3 productos cuyo nombre contiene la palabra \u201cpantalla\u201d.<\/p>\n

            En la siguiente parte tenemos el siguiente c\u00f3digo.<\/p>\n

            \"\"<\/p>\n

            Despu\u00e9s de crear la venta, la confirmamos llamando al m\u00e9todo \u201caction_confirm\u201d, que pertenece al m\u00f3dulo de ventas (sale). Recibe como par\u00e1metros el id de la venta (que se crea en la parte 2) y el contexto. Si eliminamos la venta que creamos anteriormente (ya que si volvemos a ejecutar el script completo, se volver\u00e1 a crear una venta con el mismo nombre, que choca con una condici\u00f3n que tiene el modelo de no permitir m\u00e1s de un registro con el mismo nombre) y volvemos a ejecutar el script, obtenemos lo siguiente: <\/span><\/h3>\n

            \"\"<\/p>\n

            Se ha creado una nueva orden con id 26 y se ha confirmado. Al verificar en el sistema, obtenemos:<\/p>\n

            \"\"<\/p>\n

            Ahora, \u00bfc\u00f3mo podemos saber los m\u00e9todos que podemos llamar desde la API externa, as\u00ed como sus par\u00e1metros? El sistema contiene el endpoint \/doc<\/em><\/strong>, donde podemos ver por cada modelo sus m\u00e9todos disponibles, as\u00ed como sus par\u00e1metros, todos estructurados por m\u00f3dulos. Por ejemplo, si quisi\u00e9ramos ver los par\u00e1metros y el tipo de respuesta del m\u00e9todo create del modelo de ventas (sale.order), lo vemos de la siguiente manera:<\/p>\n

            \"\"<\/p>\n

            Seleccionamos el modelo \u201cOrden de venta\u201d (sale.order) y los m\u00e9todos disponibles dentro del m\u00f3dulo core (que es la base de Odoo); aqu\u00ed encontramos el m\u00e9todo create, que se utiliza para crear y guardar registros, y la documentaci\u00f3n nos muestra un ejemplo de la request, con campos y valores de ejemplo, as\u00ed como sus par\u00e1metros, lo que responde y el tipo de la respuesta, as\u00ed como su descripci\u00f3n.<\/p>\n

            Supongamos que queremos ver el m\u00e9todo \u201caction_confirm\u201d para poder confirmar la venta dentro de la documentaci\u00f3n. Seleccionamos el m\u00f3dulo sale y buscamos el m\u00e9todo, el cual nos muestra la siguiente informaci\u00f3n:<\/p>\n

            \"\"<\/p>\n

            Nos muestra un ejemplo de la request, su descripci\u00f3n, par\u00e1metros y lo que nos devuelve el m\u00e9todo (que en este caso es un booleano).<\/span><\/h3>\n

            Notemos que el m\u00e9todo nos muestra la siguiente descripci\u00f3n:<\/span><\/p>\n

            \"\"<\/p>\n

            Esto es ya que la informaci\u00f3n se construye a partir de la descripci\u00f3n que se agrega en la definici\u00f3n del m\u00e9todo en Python. Es decir, la informaci\u00f3n anterior se construye a partir de la siguiente informaci\u00f3n dentro del archivo Python que define el m\u00e9todo.<\/p>\n

            \"\"<\/p>\n

            Modificamos la descripci\u00f3n y cambiamos la informaci\u00f3n del retorno, as\u00ed como su tipo a lo siguiente.<\/p>\n

            \"\"<\/p>\n

            Por lo que ahora estos cambios se ven en la documentaci\u00f3n al momento de actualizar el m\u00f3dulo api_doc.<\/span><\/h3>\n

            \"\"<\/p>\n

            Consejos r\u00e1pidos:<\/h3>\n
              \n
            • Evita enviar usuario y contrase\u00f1a. Genera una API key desde el perfil del usuario y \u00fasala en el header Authorization: bearer <API_KEY>.<\/li>\n
            • En entornos con varias bases, agrega el header X-Odoo-Database: nombre_base para evitar errores de conexi\u00f3n.<\/li>\n
            • Env\u00eda siempre Content-Type: application\/json. Toda la comunicaci\u00f3n se basa en JSON; no uses formularios ni multipart.<\/li>\n
            • La API respeta las reglas de acceso y permisos de Odoo. Aseg\u00farate de que el usuario tenga los permisos adecuados sobre los modelos a los que accede.<\/li>\n
            • La API devuelve errores con c\u00f3digos HTTP est\u00e1ndar (400, 403, 404, 500). \u00dasalos para manejar fallos de forma elegante en tu integraci\u00f3n.<\/li>\n
            • Odoo 19 incluye documentaci\u00f3n interactiva para explorar los m\u00e9todos disponibles en \/doc (si est\u00e1 activado). Aprov\u00e9chala para obtener informaci\u00f3n de los m\u00e9todos.<\/li>\n
            • Evita exponer la clave API en el frontend. Si tu integraci\u00f3n involucra un sitio web, haz las llamadas desde el backend para proteger las credenciales.<\/li>\n<\/ul>\n","protected":false},"excerpt":{"rendered":"

              \u00bfQu\u00e9 es la API externa JSON-2? \ud83d\udcd8 ART\u00cdCULO T\u00c9CNICO La API JSON-2 es una nueva alternativa para exponer el API externa de Odoo 19, pensada para simplificar el\u2026<\/p>\n","protected":false},"author":1,"featured_media":327,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[10],"tags":[],"class_list":["post-352","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-uncategorized"],"_links":{"self":[{"href":"https:\/\/exdoo.mx\/blogs\/wp-json\/wp\/v2\/posts\/352","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/exdoo.mx\/blogs\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/exdoo.mx\/blogs\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/exdoo.mx\/blogs\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/exdoo.mx\/blogs\/wp-json\/wp\/v2\/comments?post=352"}],"version-history":[{"count":3,"href":"https:\/\/exdoo.mx\/blogs\/wp-json\/wp\/v2\/posts\/352\/revisions"}],"predecessor-version":[{"id":1951,"href":"https:\/\/exdoo.mx\/blogs\/wp-json\/wp\/v2\/posts\/352\/revisions\/1951"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/exdoo.mx\/blogs\/wp-json\/wp\/v2\/media\/327"}],"wp:attachment":[{"href":"https:\/\/exdoo.mx\/blogs\/wp-json\/wp\/v2\/media?parent=352"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/exdoo.mx\/blogs\/wp-json\/wp\/v2\/categories?post=352"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/exdoo.mx\/blogs\/wp-json\/wp\/v2\/tags?post=352"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}