Odoo 19 en het einde van XML-RPC: migreren naar JSON-2

Wie ooit iets aan Odoo heeft gekoppeld — een webshop, een BI-tool, een eigen script — heeft vrijwel zeker XML-RPC gebruikt. Die API bestaat al sinds de OpenERP-tijd, en aan dat tijdperk komt een einde: vanaf Odoo 19 zijn XML-RPC en zijn broertje JSON-RPC officieel deprecated. De vervanger heet JSON-2: een moderne HTTP+JSON-API die eenvoudiger is dan wat hij vervangt.

De tijdlijn

De oude endpoints blijven voorlopig werken, maar de verwijdering is aangekondigd:

Het gaat om de endpoints /xmlrpc, /xmlrpc/2 en /jsonrpc. Draai je self-hosted, dan bepaal je zelf wanneer je upgradet en heb je de meeste speelruimte. Op Odoo Online word je automatisch geüpgraded — daar is winter 2027 een harde deadline.

Wat er verandert

De JSON-2 API breekt met de gewoontes van XML-RPC:

• Authenticatie via API-sleutel — geen login/wachtwoord-flow met authenticate() meer, maar een Authorization: bearer-header met een API-sleutel (aan te maken in je gebruikersprofiel onder API-sleutels).
• Model en methode in de URL — je roept aan op /json/2/<model>/<methode> in plaats van alles door één generieke execute_kw te sturen.
• Alleen named arguments — alle argumenten gaan als JSON-object in de request-body (met ids en context als vaste velden). Positionele argumenten bestaan niet meer; dat scheelt een klasse aan subtiele bugs.
• Echte HTTP-foutcodes — fouten komen terug als 4xx/5xx met een JSON-foutobject, in plaats van een fault verpakt in een 200-antwoord.
• Ingebouwde documentatie — elke database krijgt een /doc-pagina waarop je de beschikbare modellen en methodes kunt verkennen en voorbeeldrequests kunt uitproberen.

Oud en nieuw naast elkaar

Dezelfde aanroep — zoek de eerste vijf bedrijven op — in beide werelden. Eerst het vertrouwde XML-RPC in Python:

import xmlrpc.client

url, db = "https://odoo.example.nl", "productie"
common = xmlrpc.client.ServerProxy(f"{url}/xmlrpc/2/common")
uid = common.authenticate(db, "gebruiker", "wachtwoord", {})

models = xmlrpc.client.ServerProxy(f"{url}/xmlrpc/2/object")
partners = models.execute_kw(
    db, uid, "wachtwoord",
    "res.partner", "search_read",
    [[["is_company", "=", True]]],
    {"fields": ["name", "email"], "limit": 5},
)

En hetzelfde met JSON-2 — geen library nodig, elke HTTP-client volstaat:

curl -s https://odoo.example.nl/json/2/res.partner/search_read \
  -H "Authorization: bearer $ODOO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": [["is_company", "=", true]],
    "fields": ["name", "email"],
    "limit": 5
  }'

Records bijwerken gaat net zo: ids in de body, de rest als named arguments:

curl -s https://odoo.example.nl/json/2/res.partner/write \
  -H "Authorization: bearer $ODOO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": [42], "vals": {"phone": "+31 85 303 9420"}}'

Zo pak je de migratie aan

1. Inventariseer je koppelingen. Niet alleen je eigen scripts — ook integratieplatformen (n8n, Zapier, Make), webshopkoppelingen en BI-tools praten vaak nog XML-RPC. Kijk in je Odoo-logs welke clients op /xmlrpc binnenkomen.
2. Maak API-sleutels aan per koppeling, met een eigen technische gebruiker per integratie. Dan kun je rechten beperken én per koppeling intrekken.
3. Herschrijf de aanroepen naar /json/2/... met named arguments. De methodes zelf (search_read, create, write, unlink) blijven gelijk — het is vooral de envelop die verandert.
4. Vang fouten op statuscode af in plaats van op fault-parsing; dat maakt de foutafhandeling meestal eenvoudiger dan hij was.
5. Test tegen /doc — de ingebouwde API-verkenner van je eigen database is de snelste manier om een request kloppend te krijgen.

Tip: combineer de migratie met je eerstvolgende versie-upgrade. Je test dan toch al elke koppeling door, en je voorkomt dat de API-migratie ooit een spoedklus wordt.

Koppelingen laten bouwen of migreren?

Wij bouwen en onderhouden Odoo-koppelingen — van webshops en voorraadsystemen tot maatwerkintegraties — en nemen bij beheer van je Odoo-omgeving de API-migratie gewoon mee in het onderhoudsplan. Liever zelf doen met een vangnet? Ook prima: we kijken mee waar je dat wilt.