← Semua artikel

Artikel

Odoo External API: Perbandingan JSON-RPC, XML-RPC, JSON-2

Cara mengintegrasikan Odoo dengan sistem lain lewat external API: XML-RPC, JSON-RPC dan JSON-2 yang baru, plus batasan plan, API key, dan saran migrasi.

7 menit baca
  • mid
  • odoo

Kalau Anda ingin Odoo bertukar data dengan webshop, tool BI, sistem gudang, atau aplikasi internal, Anda akan memakai external API Odoo. Jawaban singkatnya untuk 2026: bangun integrasi baru di atas JSON-2 API (diperkenalkan di Odoo 19), dan rencanakan pemindahan integrasi XML-RPC dan JSON-RPC lama sebelum endpoint lamanya dihapus. Endpoint lama masih berfungsi saat ini, tetapi secara resmi sudah deprecated.

Panduan ini membahas apa saja ketiga API tersebut, batasan plan-nya, cara kerja autentikasi, dan kesalahan umum yang sebaiknya dihindari.

Tiga API, dalam bahasa sederhana

Odoo membuka model-modelnya (customer, sales order, invoice, stock move) agar bisa diakses program luar. Seiring waktu, ini hadir dalam tiga bentuk.

APIEndpointStatus
XML-RPC/xmlrpc/2/common dan /xmlrpc/2/objectDeprecated sejak Odoo 19
JSON-RPC/jsonrpcDeprecated sejak Odoo 19
JSON-2/json/2/model/methodTerbaru, baru di Odoo 19

Ketiganya memberi kemampuan dasar yang sama: membaca, membuat, mengubah, dan menghapus record, serta memanggil method model seperti search_read, create, write dan unlink. Yang berbeda adalah format data, autentikasi, dan cara error dikembalikan.

Dokumentasi Odoo 20.0 tentang RPC API lama menandai endpoint /xmlrpc, /xmlrpc/2 dan /jsonrpc sebagai deprecated sejak 19.0, dan mengarahkan ke External JSON-2 API sebagai penggantinya. Perlu dicatat, deprecation ini menyangkut endpoint eksternal generik; controller JSON-RPC kustom yang ditulis developer adalah hal yang terpisah.

Cek plan Anda dulu

Sebelum menulis kode, pastikan Anda memang berhak memakai API. Dokumentasi Odoo menyatakan bahwa akses data lewat external API hanya tersedia di Custom Odoo pricing plan. Artinya:

  • Odoo Online: Anda memerlukan plan Custom. Plan One App Free dan Standard tidak mencakup akses external API.
  • Odoo.sh dan on-premise: pembatasan plan ini terkait paket hosting resmi Odoo, jadi pastikan syarat kontrak Anda dengan Odoo atau partner Anda.

Banyak tiket “API tidak jalan” ternyata hanya soal ini. Jika autentikasi gagal di database Online, periksa plan sebelum men-debug kode. Harga dan nama plan bisa berubah, jadi verifikasi di halaman pricing Odoo yang terbaru.

Cara kerja autentikasi

Untuk jalur XML-RPC lama, Anda butuh empat hal: URL server, nama database, username, serta password atau API key. Sejak Odoo 14, API key dapat menggantikan password di script, dan dokumentasi mencatat bahwa key hanya ditampilkan sekali dan tidak bisa dipulihkan bila hilang. Di Odoo Online, user tidak punya password lokal secara default, jadi administrator menetapkannya, atau lebih baik lagi Anda memakai API key.

Alur lama terdiri dari dua langkah. Anda memanggil authenticate di endpoint common untuk mendapat user ID, lalu menyertakan ID tersebut beserta kredensial pada setiap panggilan ke endpoint object lewat execute_kw.

JSON-2 menyederhanakannya. Menurut dokumentasi JSON-2:

  • Anda mengirim POST request ke /json/2/ diikuti model dan method.
  • API key dikirim lewat header Authorization: bearer.
  • Header opsional X-Odoo-Database menentukan database bila host melayani beberapa database.
  • Argumen dikirim sebagai field bernama dalam body JSON, dengan ids dan context sebagai field tetap.
  • Jika berhasil, API mengembalikan HTTP 200 berisi hasil method dalam format JSON.

Berikut bentuk panggilan untuk menampilkan beberapa customer:

curl -X POST https://your-odoo.example.com/json/2/res.partner/search_read \
  -H "Authorization: bearer YOUR_API_KEY" \
  -H "X-Odoo-Database: your_database" \
  -H "Content-Type: application/json" \
  -d '{"domain": [["is_company", "=", true]], "fields": ["name", "email"], "limit": 5}'

Panggilan yang sama di API lama memerlukan login dua langkah dan argumen posisional di dalam execute_kw. Gaya argumen bernama pada JSON-2 lebih mudah dibaca dan di-debug.

Menurut ringkasan sebuah integrator di Belanda tentang perubahan Odoo 19, setiap database juga menyediakan halaman /doc untuk menjelajahi model dan method serta mencoba request. Anggap ini cara tercepat untuk menemukan nama field pada kustomisasi Anda.

Mengapa pindah ke JSON-2 penting

Tiga perbedaan praktis:

  1. HTTP status code yang sebenarnya. Error dikembalikan sebagai respons 4xx atau 5xx dengan objek error JSON, bukan fault yang dibungkus dalam respons 200. Monitoring dan logika retry jadi jauh lebih sederhana.
  2. Tooling standar. Klien HTTP apa pun bisa dipakai. Tidak perlu library XML-RPC, yang penting untuk tool no-code dan front end modern.
  3. Ada tanggal penghapusan. Deprecation ini bukan sekadar kosmetik. Menurut dokumentasi 20.0, layanan common dan object dijadwalkan dihapus di Odoo 22 (musim gugur 2028) dan di Odoo Online 21.1 (musim dingin 2027); ringkasan integrator Belanda tersebut menyebut hal yang sama. Layanan db sudah dihapus di Odoo 20 (musim gugur 2026) dan Online 19.1. Pastikan tanggal pastinya di dokumentasi resmi Odoo sebelum menetapkan timeline, karena jadwal bisa berubah.

Jika Anda saat ini di Odoo 17 atau 18, endpoint lama adalah satu-satunya pilihan, dan itu tidak masalah. Cukup simpan kode integrasi dalam satu modul kecil agar perpindahannya menjadi perubahan yang terkendali saat upgrade.

Merancang integrasi yang tahan lama

API-nya sendiri bagian yang mudah. Keputusan berikut yang menentukan apakah integrasi bertahan di tahun pertamanya.

Pakai user integrasi khusus. Buat satu user teknis dan satu API key per integrasi. Beri hanya hak akses yang dibutuhkan. Saat key bocor atau hubungan dengan vendor berakhir, Anda cukup mencabut satu key tanpa merusak yang lain. Jangan pernah memakai key pribadi administrator di konektor produksi.

Hormati access rights dan record rules. API bertindak sebagai user pemilik key, sehingga keamanan normal Odoo berlaku. Ini fitur, tetapi juga menjelaskan mengapa sebuah panggilan bisa berhasil untuk admin namun gagal untuk user integrasi.

Buat operasi tulis bersifat idempotent. Jaringan bisa gagal. Jika webshop mengirim order lalu respons timeout, Anda harus bisa mengulang tanpa membuat duplikat. Simpan ID order eksternal pada record Odoo, misalnya di field kustom atau ref, dan cari dulu sebelum membuat record baru.

Gunakan batch dan filter di sisi server. Tarik hanya data yang berubah, dengan filter domain pada write_date dan limit, bukan mengunduh semua record secara terjadwal. Menarik seluruh tabel setiap jam adalah cara klasik memperlambat database produksi.

Catat log dan pasang alert. Rekam setiap panggilan yang gagal beserta payload dan HTTP status-nya. Kegagalan integrasi yang diam-diam biasanya baru muncul berminggu-minggu kemudian sebagai masalah rekonsiliasi di keuangan.

Pilih event untuk alur yang sensitif waktu. External API adalah antarmuka request-response. Untuk kebutuhan real-time, automated action Odoo dapat memanggil webhook saat record berubah, sehingga sistem lain tidak perlu polling.

Bangun sendiri, beli, atau pakai konektor?

Tidak semua integrasi perlu kode kustom. Panduan kasarnya:

  • Konektor standar tersedia dan dipelihara (platform e-commerce umum, penyedia pembayaran, kurir): pakai, tetapi pastikan mendukung versi Odoo Anda dan siapa yang memeliharanya.
  • Volume rendah, pemetaan sederhana: script kecil atau platform integrasi yang memanggil JSON-2 biasanya cukup.
  • Volume tinggi, aturan rumit, atau kritis bagi bisnis: layanan khusus dengan antrean, retry, dan monitoring sepadan dengan biayanya.

Apa pun pilihannya, ajukan satu pertanyaan pada setiap konektor: apakah ia memakai endpoint yang deprecated? Konektor berbasis XML-RPC mungkin baik-baik saja hari ini dan butuh penyesuaian pada upgrade mayor berikutnya.

Checklist migrasi untuk integrasi yang sudah ada

Jika Anda sudah punya integrasi XML-RPC atau JSON-RPC, urutan kerja yang masuk akal:

  1. Inventarisasi. Daftar semua sistem yang berbicara dengan Odoo, termasuk script yang terlupakan dan tool pihak ketiga. Log server yang menunjukkan request ke /xmlrpc akan menemukan sisa-sisanya.
  2. Pisahkan kredensial. Pindahkan tiap integrasi ke user dan API key sendiri.
  3. Tulis ulang panggilan ke JSON-2. Nama method tetap sama; transport, autentikasi, dan gaya argumen yang berubah.
  4. Tangani error berdasarkan HTTP status. Perbarui logika retry dan alert Anda.
  5. Uji di salinan staging database sebelum cutover.
  6. Lakukan bersama upgrade. Gabungkan migrasi dengan upgrade versi berikutnya, jangan menunggu tenggat.

Di mana kami bisa membantu

Jika Anda sedang merencanakan integrasi Odoo, atau mewarisi kumpulan script yang tidak ingin disentuh siapa pun, kami senang melihatnya bersama Anda. Kami bisa meninjau yang ada, menyampaikan mana yang layak dipertahankan, dan menyusun pendekatan, tanpa biaya untuk percakapan pertama. Hubungi kami lewat halaman kontak kapan pun Anda siap.


Sumber: Dokumentasi Odoo 18, External API; Dokumentasi Odoo 20, External RPC API (deprecated); Dokumentasi Odoo 20, External JSON-2 API; Xyphen IT, Odoo 19 XML-RPC deprecated. Batasan plan, endpoint, dan tanggal penghapusan berubah antar rilis; verifikasi ke dokumentasi dan pricing resmi Odoo yang terbaru sebelum Anda membangun.