Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 39 ยท Reports and Integration

External API: XML-RPC and JSON-RPC

Connect to Odoo from outside: authenticate over XML-RPC, call search_read, create, write and unlink with execute_kw, understand the wire format and API keys, with Python stand-ins.

Not every integration lives inside Odoo. A webshop may push orders in, a spreadsheet script may pull customers out, and a data warehouse may read invoices every night. For all of these Odoo exposes its ORM over the network, using XML-RPC and JSON-RPC. Both give you the same operations: log in, then call model methods such as search_read, create, write and unlink.

A live Odoo server is not available on this site, so the client code is shown read-only. The runnable stand-ins use the real xmlrpc.client marshalling from Python's standard library to show what travels over the wire, and a fake server object to practise the call flow.

The two endpoints

An Odoo server publishes these XML-RPC services:

  • /xmlrpc/2/common: unauthenticated helpers: version() and authenticate(db, login, password, {}).
  • /xmlrpc/2/object: model calls through execute_kw(db, uid, password, model, method, args, kwargs).

Odoo also accepts JSON-RPC at /jsonrpc with the services common, object and db, and recent versions add a newer JSON-2 style API under /json/2/... with bearer API keys. Because the details change between versions, check the external API page of your version, but the concepts below are stable.

Authenticating

Python
import xmlrpc.client

url, db = "https://mycompany.odoo.com", "mycompany"
username, api_key = "[email protected]", "KEY-FROM-USER-PREFERENCES"

common = xmlrpc.client.ServerProxy(f"{url}/xmlrpc/2/common")
print(common.version())                      # server version info
uid = common.authenticate(db, username, api_key, {})

uid is the numeric user ID. Use an API key instead of the account password: in a user's Preferences, Account Security tab, create a key with a description, and use it wherever a password is expected. Keys can be revoked individually, and they are required if two-factor authentication is on. Treat them like passwords and keep them out of source control, for example in environment variables.

Calling the ORM

Python
models = xmlrpc.client.ServerProxy(f"{url}/xmlrpc/2/object")

# read
books = models.execute_kw(db, uid, api_key, "library.book", "search_read",
    [[["state", "=", "available"]]],
    {"fields": ["name", "isbn"], "limit": 5, "order": "name"})

# count
n = models.execute_kw(db, uid, api_key, "library.book", "search_count", [[]])

# create returns the new ID
new_id = models.execute_kw(db, uid, api_key, "library.book", "create",
    [{"name": "Dune", "isbn": "9780441013593"}])

# update and delete take a list of IDs
models.execute_kw(db, uid, api_key, "library.book", "write",
    [[new_id], {"state": "lost"}])
models.execute_kw(db, uid, api_key, "library.book", "unlink", [[new_id]])

# discover fields
info = models.execute_kw(db, uid, api_key, "library.book", "fields_get",
    [], {"attributes": ["string", "type", "required"]})

The positional args list holds the method's positional parameters: for search_read, the domain wrapped in a list ([domain]). The kwargs dictionary holds options such as fields, limit, offset and order. Domains travel as lists of lists; a tuple becomes a list in XML-RPC anyway (List, Search and Kanban Views).

Everything runs as the authenticated user, so access rights and record rules apply (Record Rules). Relational values are returned as [id, "display name"] pairs for many2one fields and lists of IDs for x2many. To write relations, use the same command tuples as in Python: [(0, 0, vals)] to create, [(4, id)] to link and [(6, 0, ids)] to replace.

sequenceDiagram
    participant C as Client script
    participant S as Odoo server
    C->>S: common.authenticate(db, login, key)
    S-->>C: uid
    C->>S: object.execute_kw(db, uid, key, model, method, args, kwargs)
    S-->>C: result (records, ids, or true)

One login call gives a user ID; each ORM call repeats the credentials.

What an XML-RPC call looks like

You can see the exact text that would be sent without a server, using the standard library:

Python Marshal an execute_kw call

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The reply has the same format. The next stand-in plays the server: it holds records, answers authenticate and execute_kw, and enforces a simple access rule, so you can write client code against it.

Python A fake Odoo server and client

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Good integration habits

  • Batch. One create call can take a list of dictionaries in recent versions, and search_read with fields is far faster than many single reads.
  • Page results. Use limit and offset; never read a whole large table in one call.
  • Be idempotent. Store the external system's ID in a custom field (or use ir.model.data external IDs) and search before creating, so a retry does not duplicate an order.
  • Handle faults. XML-RPC errors arrive as xmlrpc.client.Fault with the server traceback in faultString.
  • Use a dedicated integration user with only the groups the job needs, and an API key for it.
  • Mind rate and size. Long calls can time out; run bulk jobs in the background or as queued Odoo jobs.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which XML-RPC endpoint is used to log in and obtain the user id?

    authenticate lives on the common service; execute_kw lives on the object service.
  2. 2. What is the best credential for an integration script?

    API keys can be revoked individually and work with two-factor authentication.
  3. 3. How is the domain passed to search_read through execute_kw?

    args holds positional parameters; the domain is the first, and it is itself a list of conditions.
  4. 4. Which rights apply to calls made through the external API?

    The ORM runs as the authenticated user, so groups, access rows and record rules all apply.

Summary

  • XML-RPC and JSON-RPC expose the ORM: authenticate once, then execute_kw with model, method, args and kwargs.
  • Use API keys and a dedicated integration user.
  • search_read, create, write, unlink and fields_get cover most integrations.
  • Calls run as the authenticated user, so security still applies.
  • Page, batch and make writes idempotent.

Next: Automated Actions, Cron Jobs and Email