Odoo API Entegrasyonu: REST, JSON-RPC ve XML-RPC Kılavuzu

Odoo 19, basit veri alımından karmaşık iş akışı otomasyonuna kadar her şeyi kapsayan üç API arayüzünü kullanıma sunuyor. İster özel bir mobil uygulama oluşturuyor olun, ister üçüncü taraf bir platformla senkronizasyon yapıyor olun, ister Odoo'nun yeteneklerini harici mikro hizmetlerle genişletiyor olun, Odoo API katmanında uzmanlaşmak her türlü ciddi entegrasyon projesinin temelini oluşturur.

Bu kılavuz, Odoo 19 Enterprise'da bulunan üç ana arayüz olan REST, JSON-RPC ve XML-RPC entegrasyonları için çalışma kodu örnekleri, kimlik doğrulama akışları ve mimari öneriler sağlar.

Önemli Çıkarımlar

• Odoo 19, REST (OpenAPI 3.0), JSON-RPC 2.0 ve XML-RPC arayüzlerini sunar
• Kimlik doğrulama, API anahtarlarını (önerilir) veya oturum tabanlı oturum açmayı kullanır
• JSON-RPC, karmaşık işlemler için en kapsamlı özelliklere sahip arayüzdür
• REST API, OpenAPI 3.0 spesifikasyonunu takip eder ve standart HTTP fiillerini destekler
• XML-RPC eskidir ancak geriye dönük uyumluluk açısından hâlâ tam olarak desteklenmektedir
• İstemci tarafında hız sınırlaması ve hata yönetimi uygulanmalıdır
• Odoo 19'daki web kancaları, kayıt değişikliklerinde verileri harici sistemlere aktarır
• Tüm API çağrıları Odoo'nun erişim haklarına ve kayıt kurallarına uygundur

---

API Arayüzü Karşılaştırması

Tek satır kod yazmadan önce kullanım durumunuz için doğru API arayüzünü seçin:

REST ne zaman kullanılmalı: Mobil uygulama oluşturma, webhook yerel platformlarıyla (Shopify, Stripe) entegrasyon veya ekibinizin REST kuralları konusunda daha rahat olduğu zamanlar.

JSON-RPC ne zaman kullanılmalı: Karmaşık Odoo sunucu tarafı yöntemlerini yürütme, etki alanı filtreleriyle büyük veri kümelerini okuma veya REST aracılığıyla kullanıma sunulmayan yöntemlere erişmeniz gerektiğinde.

XML-RPC ne zaman kullanılmalı: REST kullanıma sunulmadan önce veya platformunuzda olgun XML-RPC istemci kitaplıkları bulunduğunda oluşturulan mevcut entegrasyonların bakımı.

---

Kimlik Doğrulama

API Anahtarı Kimlik Doğrulaması (Önerilen)

Odoo 19, her üç arayüz için de API anahtarı kimlik doğrulamasını destekler. Ayarlar → Kullanıcılar → Kullanıcınız → API Anahtarları altında bir API anahtarı oluşturun.

import requests

ODOO_URL = "https://your-odoo.com"
API_KEY = "your_api_key_here"
DATABASE = "your_database"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

API anahtarlarının kapsamı belirli bir kullanıcıya yöneliktir ve bu kullanıcının erişim haklarını devralır. Entegrasyon hesapları için gereken minimum izinlere sahip özel hizmet kullanıcıları oluşturun.

Oturum Tabanlı Kimlik Doğrulama (JSON-RPC / XML-RPC)

JSON-RPC için, bir oturum oluşturduktan sonra /web/dataset/call_kw uç noktasını kullanarak kimlik doğrulaması yapın:

import requests
import json

session = requests.Session()

# Authenticate
auth_payload = {
    "jsonrpc": "2.0",
    "method": "call",
    "params": {
        "db": "your_database",
        "login": "admin",
        "password": "your_password"
    }
}

response = session.post(
    f"{ODOO_URL}/web/session/authenticate",
    json=auth_payload
)
uid = response.json()['result']['uid']
print(f"Authenticated as UID: {uid}")

XML-RPC için standart iki adımlı kimlik doğrulamayı kullanın:

import xmlrpc.client

url = "https://your-odoo.com"
db = "your_database"
username = "admin"
password = "your_password"

# Step 1: Get UID
common = xmlrpc.client.ServerProxy(f"{url}/xmlrpc/2/common")
uid = common.authenticate(db, username, password, {})

# Step 2: Use UID for subsequent calls
models = xmlrpc.client.ServerProxy(f"{url}/xmlrpc/2/object")

---

REST API'si: OpenAPI 3.0

Odoo 19, OpenAPI 3.0 spesifikasyonuna sahip tam bir REST API sunuyor. İnteraktif belgelere https://your-odoo.com/api/docs adresinden erişin.

Kayıtları Listeleme

# GET /api/sale.order — list all sales orders
response = requests.get(
    f"{ODOO_URL}/api/sale.order",
    headers=headers,
    params={
        "domain": '[["state", "=", "sale"]]',
        "fields": '["name", "partner_id", "amount_total", "state"]',
        "limit": 50,
        "offset": 0
    }
)
orders = response.json()

Tek Bir Kayıt Okuma

# GET /api/sale.order/{id}
order_id = 123
response = requests.get(
    f"{ODOO_URL}/api/sale.order/{order_id}",
    headers=headers
)
order = response.json()

Kayıt Oluşturma

# POST /api/sale.order
payload = {
    "partner_id": 42,
    "order_line": [
        {
            "product_id": 7,
            "product_uom_qty": 5,
            "price_unit": 100.0
        }
    ]
}
response = requests.post(
    f"{ODOO_URL}/api/sale.order",
    headers=headers,
    json=payload
)
new_order = response.json()

Bir Kaydı Güncelleme

# PATCH /api/sale.order/{id}
response = requests.patch(
    f"{ODOO_URL}/api/sale.order/{order_id}",
    headers=headers,
    json={"note": "Rush order — priority handling required"}
)

Bir Kaydı Silme

# DELETE /api/sale.order/{id}
response = requests.delete(
    f"{ODOO_URL}/api/sale.order/{order_id}",
    headers=headers
)

---

JSON-RPC Arayüzü

JSON-RPC, REST aracılığıyla kullanıma sunulmayan sunucu tarafı yöntemleri de dahil olmak üzere Odoo Python API'sinin tamamına erişim sağlar. Birincil uç nokta /web/dataset/call_kw'dir.

Temel Arama ve Okuma

def call_kw(model, method, args, kwargs=None):
    payload = {
        "jsonrpc": "2.0",
        "method": "call",
        "params": {
            "model": model,
            "method": method,
            "args": args,
            "kwargs": kwargs or {}
        }
    }
    response = session.post(
        f"{ODOO_URL}/web/dataset/call_kw",
        json=payload
    )
    return response.json().get('result')

# Search for confirmed sales orders
order_ids = call_kw(
    "sale.order",
    "search",
    [[["state", "=", "sale"]]],
    {"limit": 100, "order": "date_order desc"}
)

# Read specific fields
orders = call_kw(
    "sale.order",
    "read",
    [order_ids],
    {"fields": ["name", "partner_id", "amount_total", "date_order"]}
)

Arama Okuma (Birleşik)

orders = call_kw(
    "sale.order",
    "search_read",
    [[["partner_id.country_id.code", "=", "US"]]],
    {
        "fields": ["name", "partner_id", "amount_total"],
        "limit": 50,
        "offset": 0,
        "order": "amount_total desc"
    }
)

Kayıt Oluşturma

new_id = call_kw(
    "sale.order",
    "create",
    [{
        "partner_id": 42,
        "order_line": [
            (0, 0, {
                "product_id": 7,
                "product_uom_qty": 10,
                "price_unit": 150.0
            })
        ]
    }]
)

Sunucu Tarafı Yöntemlerini Çağırma

JSON-RPC, Odoo modellerinde tanımlanan tüm Python yöntemlerine erişim sağlar:

# Confirm a sales order (triggers workflow)
call_kw("sale.order", "action_confirm", [[order_id]])

# Validate an inventory transfer
call_kw("stock.picking", "button_validate", [[picking_id]])

# Get the action for a button (useful for understanding what a button does)
action = call_kw("sale.order", "action_quotations_with_onboarding", [[]])

---

XML-RPC Arayüzü

XML-RPC, orijinal Odoo API'sidir ve tamamen desteklenmeye devam etmektedir. Arayüz iki uç noktadan oluşur:

• /xmlrpc/2/common — kimliği doğrulanmamış yöntemler (kimlik doğrulama, sürüm)
• /xmlrpc/2/object — tüm model işlemleri (UID gerektirir)

import xmlrpc.client

url = "https://your-odoo.com"
db, username, password = "mydb", "admin", "mypassword"

common = xmlrpc.client.ServerProxy(f"{url}/xmlrpc/2/common")
uid = common.authenticate(db, username, password, {})
models = xmlrpc.client.ServerProxy(f"{url}/xmlrpc/2/object")

# Search for products
product_ids = models.execute_kw(
    db, uid, password,
    'product.template', 'search',
    [[['sale_ok', '=', True]]],
    {'limit': 100}
)

# Read product data
products = models.execute_kw(
    db, uid, password,
    'product.template', 'read',
    [product_ids],
    {'fields': ['name', 'list_price', 'categ_id']}
)

# Create a new product
new_product_id = models.execute_kw(
    db, uid, password,
    'product.template', 'create',
    [{
        'name': 'My New Product',
        'list_price': 99.99,
        'type': 'consu'
    }]
)

---

Etki Alanı Filtreleri

Odoo'nun etki alanı filtre sözdizimi üç API türünün tamamında kullanılır. Etki alanlarını anlamak, verimli veri alımı için çok önemlidir.

# Basic operators: =, !=, >, <, >=, <=, like, ilike, in, not in, child_of
domain = [
    ["state", "in", ["sale", "done"]],      # Confirmed or done orders
    ["amount_total", ">=", 1000],            # Total at least 1000
    ["partner_id.country_id.code", "=", "US"] # US customers (related field)
]

# Logical operators: & (AND, default), | (OR), ! (NOT)
domain = [
    "|",
    ["state", "=", "draft"],
    ["state", "=", "cancel"]
]

# Complex: orders from US or UK customers with total > 5000
domain = [
    "|",
    ["partner_id.country_id.code", "=", "US"],
    ["partner_id.country_id.code", "=", "GB"],
    ["amount_total", ">", 5000]
]

---

Web Kancaları ve Olay Odaklı Entegrasyon

Odoo 19, kayıt değişiklikleriyle tetiklenen giden web kancalarını destekler. Ayarlar → Teknik → Web Kancaları altında web kancalarını yapılandırın.

Web kancası yapılandırması:

1. Ayarlar → Teknik → Web Kancaları → Oluştur seçeneğine gidin
2. Modeli ayarlayın (ör. sale.order)
3. Tetikleyici'yi seçin: oluşturun, yazın, bağlantıyı kaldırın veya özel yöntem
4. Alıcı hizmetinizin Uç Nokta URL'sini girin
5. Hangi kayıtların webhook'u tetikleyeceğini filtrelemek için isteğe bağlı olarak Etki Alanı'nı ayarlayın
6. Alanlar'ı veriye dahil edecek şekilde yapılandırın

Bir Flask hizmetinde webhook etkinliklerini alma:

from flask import Flask, request, jsonify
import hmac, hashlib

app = Flask(__name__)
WEBHOOK_SECRET = "your_webhook_secret"

@app.route("/odoo-webhook", methods=["POST"])
def handle_webhook():
    # Verify signature
    signature = request.headers.get("X-Odoo-Signature")
    body = request.get_data()
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        body,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        return jsonify({"error": "Invalid signature"}), 401

    event = request.json
    model = event.get("model")
    record_id = event.get("id")

    # Process the event
    if model == "sale.order":
        handle_order_event(record_id, event)

    return jsonify({"status": "ok"}), 200

---

Hata İşleme ve Yeniden Deneme Mantığı

Güçlü entegrasyonlar, Odoo API hatalarını düzgün bir şekilde ele almalıdır.

import time
import requests
from requests.exceptions import RequestException

def api_call_with_retry(url, payload, headers, max_retries=3, backoff=2):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, json=payload, headers=headers, timeout=30)
            response.raise_for_status()

            data = response.json()
            if "error" in data:
                error = data["error"]
                code = error.get("code", 0)
                message = error.get("data", {}).get("message", "Unknown error")

                # Don't retry validation errors
                if code in [200, 100]:
                    raise ValueError(f"Odoo validation error: {message}")

                raise RuntimeError(f"Odoo API error {code}: {message}")

            return data.get("result")

        except (RequestException, RuntimeError) as e:
            if attempt == max_retries - 1:
                raise
            wait = backoff ** attempt
            print(f"Attempt {attempt + 1} failed: {e}. Retrying in {wait}s...")
            time.sleep(wait)

Yaygın hata kodları:

---

En İyi Performans Uygulamaları

Toplu işlemler: Bireysel kayıtlar için hiçbir zaman API'yi bir döngüde çağırmayın. Listelerle create_multi ve write kullanın:

# Bad: loop with individual creates
for product in products:
    call_kw("product.template", "create", [product])

# Good: batch create
call_kw("product.template", "create", [products])

Alan seçimi: Tüm alanların getirilmesini önlemek için her zaman fields parametresini belirtin:

# Good: only fetch needed fields
orders = call_kw(
    "sale.order", "search_read",
    [[["state", "=", "sale"]]],
    {"fields": ["name", "amount_total"], "limit": 1000}
)

Sayfalandırma: Büyük veri kümeleri için limit ve offset kullanarak sayfalandırma yapın:

def fetch_all_records(model, domain, fields, batch_size=500):
    records = []
    offset = 0
    while True:
        batch = call_kw(
            model, "search_read", [domain],
            {"fields": fields, "limit": batch_size, "offset": offset}
        )
        records.extend(batch)
        if len(batch) < batch_size:
            break
        offset += batch_size
    return records

---

Sıkça Sorulan Sorular

Odoo 19'daki JSON-RPC ile REST API arasındaki fark nedir?

JSON-RPC, tüm sunucu tarafı yöntemleri de dahil olmak üzere Odoo Python API'sinin tamamına erişim sağlarken REST, OpenAPI 3.0 kurallarına uyar ve daha sınırlı ancak standartlaştırılmış bir arayüz sunar. REST'in kullanım durumunuzu kapsadığı yeni entegrasyonlarda keşfedilebilirliği nedeniyle REST tercih edilir. Karmaşık iş akışı otomasyonu veya özel Python yöntemlerine erişim için JSON-RPC'yi kullanın.

Büyük veri aktarımlarını (100.000'den fazla kayıt) verimli bir şekilde nasıl yönetirim?

search_read ile sayfalandırmayı ve 500-1000 kayıttan oluşan toplu iş boyutunu kullanın. Çok büyük dışa aktarmalar için, tek seferlik çıkarmalar için kullanıcı arayüzü aracılığıyla Odoo'nun dışa aktarma özelliğini kullanmayı düşünün veya gerçek zamanlı API çağrıları yapmak yerine verileri yoğun olmayan saatlerde parçalar halinde işlemek için Odoo'nun ir.cron modelini kullanarak arka plan işlerini planlayın.

XML-RPC için kullanıcı adı/şifre yerine API anahtarlarını kullanabilir miyim?

Evet. Odoo 13+ sürümünde API anahtarları, XML-RPC kimlik doğrulama çağrısında parola olarak kullanılabilir. Kullanıcı profilinizden bir API anahtarı oluşturun ve bunu şifreniz yerine kullanın: common.authenticate(db, username, api_key, {}). Hizmet hesapları için önerilen yaklaşım budur.

API aracılığıyla Many2many ve One2many kayıtlarını nasıl oluştururum?

Odoo'nun komut dizilerini kullanın: (0, 0, vals) yeni bir ilgili kayıt oluşturur, (1, id, vals) mevcut bir ilgili kaydı günceller, (2, id, 0) ilgili bir kaydı siler, (4, id, 0) mevcut bir kaydı bağlar, (5, 0, 0) tüm ilgili kayıtların bağlantısını kaldırır. Bu komutlar JSON-RPC, XML-RPC ve REST'te aynı şekilde çalışır.

API aracılığıyla bir iş akışı eylemini (bir siparişi onaylamak gibi) nasıl tetikleyebilirim?

Modelde karşılık gelen yöntemi çağırın. Bir satış siparişini onaylamak için sale.order numaralı telefondan action_confirm numaralı telefonu arayın. Bir teslimatı doğrulamak için stock.picking numaralı telefondan button_validate numaralı telefonu arayın. Bu yöntemler Odoo'nun kaynak kodunda görünür ve kullanıcı arayüzünün geliştirici modunda düğmenin name özelliği incelenerek keşfedilebilir.

Odoo, API çağrılarına hangi hız sınırlarını uyguluyor?

Odoo, API hızı sınırlarını yerel olarak uygulama düzeyinde zorunlu kılmaz. Hız sınırlamanın ters proxy (Nginx) veya altyapı düzeyinde yapılandırılması gerekir. Harici entegrasyonlar için makul bir varsayılan, IP başına dakikada 60 istektir. Yüksek verimli entegrasyonlar için özel bir hizmet kullanıcısıyla kuyruk tabanlı bir yaklaşım kullanın.

---

Sonraki Adımlar

Güvenilir bir Odoo API entegrasyonu oluşturmak, çalışan kod örneklerinden daha fazlasını gerektirir; doğru hata yönetimi, izleme, kimlik bilgisi yönetimi ve Odoo'nun veri modeliyle uyum sağlamayı gerektirir.

ECOSIRE'ın entegrasyon ekibi, Odoo ile Shopify, Amazon, GoHighLevel, Power BI, özel ERP'ler ve özel sistemler dahil olmak üzere düzinelerce platform arasında üretim düzeyinde bağlantılar kurdu. Kimlik doğrulama mimarisini, web kancası tasarımını, veri dönüşümünü ve sürekli izlemeyi biz yönetiyoruz.

Odoo Entegrasyon Projeniz Hakkında ECOSIRE ile Konuşun →

İster yeni bir entegrasyona başlıyor olun ister bozuk bir entegrasyonu düzeltiyor olun, mühendislerimiz gereksinimlerinizi inceleyecek ve ilk günden itibaren uç durumları ele alan bir çözüm sunacaktır.