Odoo REST API: Pratik Örnekler ve Entegrasyon Eğitimi

Postman'ın 2025 API'lerin Durumu raporuna göre işletmelerin %73'ü artık ERP'lerini en az üç harici sistemle entegre ediyor. Dünya çapında 12 milyondan fazla kullanıcıya güç veren Odoo, tüm veri modelini zengin bir API katmanı aracılığıyla ortaya koyuyor. Ancak belgeler, birçok geliştiricinin kimlik doğrulama akışları, toplu işlemler ve üretim düzeyinde hata işlemeyle mücadele etmesine neden oluyor.

Bu eğitimde, her yaygın entegrasyon modeli için hem Python hem de Node.js'de kopyala-yapıştır'a hazır örnekler sunulmaktadır. İster Shopify siparişlerini senkronize ediyor olun, ister bir mobil uygulamadan veri aktarıyor olun, ister özel bir kontrol paneli oluşturuyor olun, bu kılavuz ihtiyacınızı karşılayacaktır.

Temel Çıkarımlar

• Odoo üç API erişim yöntemi sunar: XML-RPC (eski, tüm sürümler), JSON-RPC (web istemci protokolü) ve REST API (API anahtarlarıyla Odoo 17+) — her biri farklı kimlik doğrulama ve kullanım örneklerine sahiptir.
• API anahtarı kimlik doğrulaması (Odoo 17+), sunucular arası entegrasyonlar için önerilen yaklaşımdır; oturum yönetimi yok, CSRF belirteçleri yok, basit HTTP başlıkları yok.
• Alan arama, filtreleme için Odoo'nun güçlü Lehçe gösterimini kullanır; operatörlerde ustalaşarak herhangi bir veri kombinasyonunu sorgulayabilirsiniz.
• Toplu işlemler performans açısından kritik öneme sahiptir; tek bir API çağrısıyla 1.000 kayıt oluşturmak, 1.000 bireysel çağrıdan 50 kat daha hızlıdır.
• Hata işleme ve hız sınırlama, üretim entegrasyonları için gereklidir — Odoo, kodunuzun incelikle ayrıştırıp işlemesi gereken yapılandırılmış hata yanıtlarını döndürür.

1. Kimlik Doğrulama Yöntemleri

Yöntem 1: API Anahtarları (Odoo 17+ için önerilir)

API anahtarları, sunucular arası iletişim için en basit ve en güvenli yöntemdir:

# Generate an API key in Odoo:
# Settings → Users → Select user → Account Security → New API Key

# Test authentication
curl -X GET "https://your-odoo.com/api/res.partner" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

API Anahtarlı Python:

import requests

class OdooAPI:
    def __init__(self, url, api_key):
        self.url = url.rstrip('/')
        self.session = requests.Session()
        self.session.headers.update({
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json',
        })

    def get(self, model, params=None):
        response = self.session.get(
            f'{self.url}/api/{model}',
            params=params or {}
        )
        response.raise_for_status()
        return response.json()

    def post(self, model, data):
        response = self.session.post(
            f'{self.url}/api/{model}',
            json=data
        )
        response.raise_for_status()
        return response.json()

# Usage
odoo = OdooAPI('https://your-odoo.com', 'your-api-key-here')
partners = odoo.get('res.partner', {'limit': 10})

API Anahtarına sahip Node.js:

const axios = require('axios');

class OdooAPI {
  constructor(url, apiKey) {
    this.client = axios.create({
      baseURL: `${url}/api`,
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
      },
      timeout: 30000,
    });
  }

  async get(model, params = {}) {
    const { data } = await this.client.get(`/${model}`, { params });
    return data;
  }

  async post(model, body) {
    const { data } = await this.client.post(`/${model}`, body);
    return data;
  }

  async put(model, id, body) {
    const { data } = await this.client.put(`/${model}/${id}`, body);
    return data;
  }

  async delete(model, id) {
    const { data } = await this.client.delete(`/${model}/${id}`);
    return data;
  }
}

// Usage
const odoo = new OdooAPI('https://your-odoo.com', 'your-api-key');
const partners = await odoo.get('res.partner', { limit: 10 });

Yöntem 2: JSON-RPC (Tüm Sürümler)

JSON-RPC, Odoo'nun web istemcisi tarafından dahili olarak kullanılan protokoldür. Tüm Odoo sürümleriyle çalışır:

import requests
import json

class OdooJsonRpc:
    def __init__(self, url, db, username, password):
        self.url = url.rstrip('/')
        self.db = db
        self.session = requests.Session()
        self.uid = self._authenticate(username, password)

    def _authenticate(self, username, password):
        response = self._call('/web/session/authenticate', {
            'db': self.db,
            'login': username,
            'password': password,
        })
        if not response.get('uid'):
            raise Exception(f"Authentication failed: {response}")
        return response['uid']

    def _call(self, endpoint, params):
        payload = {
            'jsonrpc': '2.0',
            'method': 'call',
            'params': params,
            'id': None,
        }
        response = self.session.post(
            f'{self.url}{endpoint}',
            json=payload,
            headers={'Content-Type': 'application/json'}
        )
        result = response.json()
        if result.get('error'):
            raise Exception(result['error']['data']['message'])
        return result.get('result')

    def search_read(self, model, domain=None, fields=None, limit=80, offset=0, order=None):
        return self._call('/web/dataset/call_kw', {
            'model': model,
            'method': 'search_read',
            'args': [domain or []],
            'kwargs': {
                'fields': fields or [],
                'limit': limit,
                'offset': offset,
                'order': order or '',
            },
        })

    def create(self, model, values):
        return self._call('/web/dataset/call_kw', {
            'model': model,
            'method': 'create',
            'args': [values],
            'kwargs': {},
        })

    def write(self, model, ids, values):
        return self._call('/web/dataset/call_kw', {
            'model': model,
            'method': 'write',
            'args': [ids, values],
            'kwargs': {},
        })

# Usage
odoo = OdooJsonRpc('https://your-odoo.com', 'mydb', 'admin', 'password')
orders = odoo.search_read('sale.order', [('state', '=', 'sale')],
                          fields=['name', 'amount_total', 'partner_id'],
                          limit=20)

Yöntem 3: XML-RPC (Eski, Evrensel)

import xmlrpc.client

url = 'https://your-odoo.com'
db = 'mydb'
username = 'admin'
password = 'password'

# Authenticate
common = xmlrpc.client.ServerProxy(f'{url}/xmlrpc/2/common')
uid = common.authenticate(db, username, password, {})

# Create models proxy
models = xmlrpc.client.ServerProxy(f'{url}/xmlrpc/2/object')

# Search and read
partners = models.execute_kw(db, uid, password,
    'res.partner', 'search_read',
    [[('is_company', '=', True), ('country_id.code', '=', 'US')]],
    {'fields': ['name', 'email', 'phone'], 'limit': 10}
)

2. CRUD İşlemleri

Kayıt Oluştur

# Create a single contact
partner_id = odoo.create('res.partner', {
    'name': 'Acme Corporation',
    'is_company': True,
    'email': '[email protected]',
    'phone': '+1-555-0123',
    'street': '123 Main Street',
    'city': 'San Francisco',
    'state_id': 5,  # California
    'country_id': 233,  # United States
    'category_id': [(6, 0, [1, 3])],  # Tags: replace all with IDs 1 and 3
})

# Create a sale order with lines
order_id = odoo.create('sale.order', {
    'partner_id': partner_id,
    'date_order': '2026-03-23',
    'order_line': [
        (0, 0, {
            'product_id': 42,
            'product_uom_qty': 5,
            'price_unit': 99.99,
        }),
        (0, 0, {
            'product_id': 43,
            'product_uom_qty': 2,
            'price_unit': 149.99,
        }),
    ],
})

Node.js eşdeğeri:

// Create a contact
const partnerId = await odoo.post('res.partner', {
  name: 'Acme Corporation',
  is_company: true,
  email: '[email protected]',
  phone: '+1-555-0123',
  street: '123 Main Street',
  city: 'San Francisco',
  country_id: 233,
});

// Create sale order with lines
const orderId = await odoo.post('sale.order', {
  partner_id: partnerId,
  date_order: '2026-03-23',
  order_line: [
    [0, 0, { product_id: 42, product_uom_qty: 5, price_unit: 99.99 }],
    [0, 0, { product_id: 43, product_uom_qty: 2, price_unit: 149.99 }],
  ],
});

Kayıtları Oku

# Read specific fields from specific records
data = odoo.search_read('sale.order',
    domain=[('state', '=', 'sale'), ('amount_total', '>', 500)],
    fields=['name', 'partner_id', 'amount_total', 'date_order', 'state'],
    limit=50,
    offset=0,
    order='date_order desc'
)

# Read a single record by ID (REST API)
# GET /api/sale.order/42?fields=name,amount_total

// Node.js — read with pagination
async function fetchAllOrders(odoo) {
  const pageSize = 100;
  let offset = 0;
  let allOrders = [];

  while (true) {
    const orders = await odoo.get('sale.order', {
      domain: JSON.stringify([['state', '=', 'sale']]),
      fields: 'name,partner_id,amount_total',
      limit: pageSize,
      offset,
      order: 'date_order desc',
    });

    allOrders = allOrders.concat(orders);
    if (orders.length < pageSize) break;
    offset += pageSize;
  }

  return allOrders;
}

Kayıtları Güncelle

# Update a single record
odoo.write('res.partner', [partner_id], {
    'phone': '+1-555-9999',
    'website': 'https://acme.com',
})

# Update multiple records at once
draft_orders = odoo.search_read('sale.order',
    [('state', '=', 'draft'), ('date_order', '<', '2026-01-01')],
    fields=['id']
)
ids = [o['id'] for o in draft_orders]
odoo.write('sale.order', ids, {'note': 'Reviewed Q1 2026'})

Kayıtları Sil

# Delete records (use with caution)
odoo.write('res.partner', [obsolete_id], {'active': False})  # Prefer archiving

# Actually delete (rarely needed)
# models.execute_kw(db, uid, password, 'res.partner', 'unlink', [[obsolete_id]])

3. Gelişmiş Arama Alanları

Odoo'nun arama alanları, koşulları birleştirmek için Lehçe gösterimi (önek gösterimi) kullanır. Koşullar arasındaki varsayılan operatör VE'dir. '|' dikey çizgisini kullan VEYA için ve açık VE için '&' işareti. Her yaprak, alan adı, operatör ve değerden oluşan bir demettir. Odoo, siparişleri müşterinin ülkesine göre filtrelemek amacıyla 'partner_id.country_id.code' gibi ilgili model alanlarını filtrelemek için nokta gösterimini destekler.

# Complex domain examples

# Orders from US customers with amount > $1000, created this year
domain = [
    ('partner_id.country_id.code', '=', 'US'),
    ('amount_total', '>', 1000),
    ('date_order', '>=', '2026-01-01'),
    ('state', 'in', ['sale', 'done']),
]

# OR condition: email contains 'gmail' OR 'yahoo'
domain = [
    '|',
    ('email', 'ilike', 'gmail.com'),
    ('email', 'ilike', 'yahoo.com'),
]

# Complex: (state=sale AND amount>1000) OR (state=done AND amount>5000)
domain = [
    '|',
    '&', ('state', '=', 'sale'), ('amount_total', '>', 1000),
    '&', ('state', '=', 'done'), ('amount_total', '>', 5000),
]

# Negation: NOT archived
domain = [('active', '!=', False)]

# NULL check: has no email
domain = [('email', '=', False)]

# Hierarchical: all child categories of 'Electronics'
domain = [('categ_id', 'child_of', electronics_id)]

# Date ranges
from datetime import datetime, timedelta
domain = [
    ('create_date', '>=', (datetime.now() - timedelta(days=30)).strftime('%Y-%m-%d')),
    ('create_date', '<', datetime.now().strftime('%Y-%m-%d')),
]

Operatör Referansı

4. Toplu İşlemler

Toplu işlemler performans için gereklidir. Hiçbir zaman döngü içinde tek tek kayıt oluşturmayın:

# BAD: 1000 API calls (slow, ~300 seconds)
for customer in customers:
    odoo.create('res.partner', customer)

# GOOD: 1 API call with batch (fast, ~3 seconds)
# Using JSON-RPC batch create
partner_ids = odoo._call('/web/dataset/call_kw', {
    'model': 'res.partner',
    'method': 'create',
    'args': [customers],  # Pass list of dicts
    'kwargs': {},
})

// Node.js batch pattern with chunking
async function batchCreate(odoo, model, records, chunkSize = 200) {
  const results = [];

  for (let i = 0; i < records.length; i += chunkSize) {
    const chunk = records.slice(i, i + chunkSize);
    console.log(`Creating ${model} batch ${i / chunkSize + 1}/${Math.ceil(records.length / chunkSize)}`);

    const ids = await odoo.post(model, chunk);
    results.push(...(Array.isArray(ids) ? ids : [ids]));

    // Respect rate limits
    if (i + chunkSize < records.length) {
      await new Promise(resolve => setTimeout(resolve, 500));
    }
  }

  return results;
}

// Usage
const customers = generateCustomerData(); // Array of 5000 objects
const ids = await batchCreate(odoo, 'res.partner', customers);
console.log(`Created ${ids.length} partners`);

5. Hata İşleme

Üretim entegrasyonları hataları incelikle ele almalıdır:

import requests
import logging
import time

logger = logging.getLogger(__name__)

class OdooAPIClient:
    MAX_RETRIES = 3
    RETRY_DELAY = 2  # seconds

    def __init__(self, url, api_key):
        self.url = url.rstrip('/')
        self.session = requests.Session()
        self.session.headers.update({
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json',
        })

    def _request(self, method, endpoint, **kwargs):
        last_error = None

        for attempt in range(self.MAX_RETRIES):
            try:
                response = self.session.request(
                    method,
                    f'{self.url}{endpoint}',
                    timeout=30,
                    **kwargs
                )

                if response.status_code == 429:
                    retry_after = int(response.headers.get('Retry-After', 60))
                    logger.warning(f"Rate limited. Retrying after {retry_after}s")
                    time.sleep(retry_after)
                    continue

                if response.status_code == 401:
                    raise AuthenticationError("Invalid API key or session expired")

                if response.status_code == 403:
                    raise PermissionError(f"Access denied: {response.text}")

                if response.status_code == 404:
                    raise RecordNotFoundError(f"Record not found: {endpoint}")

                if response.status_code >= 500:
                    logger.error(f"Server error {response.status_code}: {response.text}")
                    if attempt < self.MAX_RETRIES - 1:
                        time.sleep(self.RETRY_DELAY * (attempt + 1))
                        continue
                    raise ServerError(f"Server error after {self.MAX_RETRIES} retries")

                response.raise_for_status()
                return response.json()

            except requests.exceptions.ConnectionError as e:
                last_error = e
                logger.warning(f"Connection error (attempt {attempt + 1}): {e}")
                if attempt < self.MAX_RETRIES - 1:
                    time.sleep(self.RETRY_DELAY * (attempt + 1))

            except requests.exceptions.Timeout as e:
                last_error = e
                logger.warning(f"Request timeout (attempt {attempt + 1}): {e}")
                if attempt < self.MAX_RETRIES - 1:
                    time.sleep(self.RETRY_DELAY * (attempt + 1))

        raise ConnectionError(f"Failed after {self.MAX_RETRIES} attempts: {last_error}")

class AuthenticationError(Exception): pass
class PermissionError(Exception): pass
class RecordNotFoundError(Exception): pass
class ServerError(Exception): pass

// Node.js error handling with axios interceptors
const axios = require('axios');

function createOdooClient(url, apiKey) {
  const client = axios.create({
    baseURL: `${url}/api`,
    headers: { Authorization: `Bearer ${apiKey}` },
    timeout: 30000,
  });

  // Response interceptor for error handling
  client.interceptors.response.use(
    (response) => response,
    async (error) => {
      const { config, response } = error;
      config.__retryCount = config.__retryCount || 0;

      // Rate limiting
      if (response?.status === 429) {
        const retryAfter = parseInt(response.headers['retry-after'] || '60', 10);
        console.warn(`Rate limited. Waiting ${retryAfter}s...`);
        await new Promise((r) => setTimeout(r, retryAfter * 1000));
        return client(config);
      }

      // Retry on server errors (max 3)
      if (response?.status >= 500 && config.__retryCount < 3) {
        config.__retryCount += 1;
        const delay = config.__retryCount * 2000;
        console.warn(`Server error ${response.status}. Retry ${config.__retryCount}/3 in ${delay}ms`);
        await new Promise((r) => setTimeout(r, delay));
        return client(config);
      }

      // Structured error response
      const errorMessage = response?.data?.error?.message
        || response?.data?.message
        || error.message;

      throw new Error(`Odoo API Error [${response?.status}]: ${errorMessage}`);
    }
  );

  return client;
}

6. Gerçek Dünya Entegrasyon Örnekleri

Shopify'dan Odoo'ya Sipariş Senkronizasyonu

class ShopifyOdooSync:
    def __init__(self, odoo_client, shopify_client):
        self.odoo = odoo_client
        self.shopify = shopify_client

    def sync_order(self, shopify_order):
        # 1. Find or create customer
        partner = self._get_or_create_partner(shopify_order['customer'])

        # 2. Map products
        order_lines = []
        for item in shopify_order['line_items']:
            product_id = self._find_product_by_sku(item['sku'])
            if not product_id:
                logger.warning(f"Product not found for SKU: {item['sku']}")
                continue
            order_lines.append((0, 0, {
                'product_id': product_id,
                'product_uom_qty': item['quantity'],
                'price_unit': float(item['price']),
                'discount': self._calc_discount(item),
            }))

        # 3. Create sale order
        order_id = self.odoo.create('sale.order', {
            'partner_id': partner['id'],
            'client_order_ref': shopify_order['name'],  # Shopify order #
            'order_line': order_lines,
            'note': f"Shopify Order: {shopify_order['id']}",
        })

        # 4. Auto-confirm if paid
        if shopify_order['financial_status'] == 'paid':
            self.odoo._call('/web/dataset/call_kw', {
                'model': 'sale.order',
                'method': 'action_confirm',
                'args': [[order_id]],
                'kwargs': {},
            })

        return order_id

    def _get_or_create_partner(self, customer):
        # Search by email first
        existing = self.odoo.search_read('res.partner',
            [('email', '=', customer['email'])],
            fields=['id', 'name'], limit=1)

        if existing:
            return existing[0]

        return {'id': self.odoo.create('res.partner', {
            'name': f"{customer['first_name']} {customer['last_name']}",
            'email': customer['email'],
            'phone': customer.get('phone'),
        })}

    def _find_product_by_sku(self, sku):
        products = self.odoo.search_read('product.product',
            [('default_code', '=', sku)],
            fields=['id'], limit=1)
        return products[0]['id'] if products else None

Web Kancası Alıcısı (Şişe Örneği)

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

app = Flask(__name__)

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

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

    payload = request.json
    event_type = payload.get('event')

    if event_type == 'sale.order.confirmed':
        handle_order_confirmed(payload['data'])
    elif event_type == 'stock.picking.done':
        handle_shipment_complete(payload['data'])

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

7. Performans İpuçları

Sıkça Sorulan Sorular

Odoo'da XML-RPC, JSON-RPC ve REST API arasındaki fark nedir?

XML-RPC, tüm Odoo sürümlerinde mevcut olan eski protokoldür; ayrıntılıdır ancak evrensel olarak desteklenir. JSON-RPC, Odoo'nun web istemcisi tarafından kullanılan protokoldür ve JSON yükleriyle aynı işlevselliği sağlar. REST API, Odoo 17'de tanıtıldı ve API anahtarı kimlik doğrulamasıyla standart HTTP uç noktaları sağlayarak onu modern entegrasyonlar için en kolay seçenek haline getiriyor. Yeni projeler için Odoo 17 veya üzerini kullanıyorsanız REST API'yi kullanın.

Odoo API hız sınırlarını nasıl yönetirim?

Odoo.sh, plan seviyenize göre ücret sınırları uygular. 429 yanıtı aldığınızda Retry-After başlığını okuyun ve yeniden denemeden önce bekleyin. Yüksek hacimli entegrasyonlar için üstel geri çekilme uygulayın, API çağrılarının sayısını azaltmak için işlemlerinizi gruplandırın ve toplu işleme için kritik olmayan senkronizasyonlar için gerçek zamanlı API çağrıları yerine Odoo'nun planlanmış eylemlerini kullanmayı düşünün.

API aracılığıyla özel Python yöntemlerini çağırabilir miyim?

Evet. Odoo modelindeki herhangi bir genel yöntem, XML-RPC veya JSON-RPC aracılığıyla, executive_kw kullanılarak çağrılabilir. REST API için @http.route ile özel bir denetleyici uç noktası oluşturmanız gerekir. Alt çizgi ile başlayan yöntemler özeldir ve XML-RPC aracılığıyla dışarıdan çağrılamaz. Enjeksiyon saldırılarını önlemek için özel yöntemlerinizdeki girişleri her zaman doğrulayın.

Büyük veri kümelerini verimli bir şekilde nasıl senkronize edebilirim?

Bir strateji kombinasyonu kullanın: toplu işlemler ve sayfalandırmayla ilk tam senkronizasyon (istek başına 200 kayıtla sınırlayın), ardından yalnızca son senkronizasyondan bu yana değiştirilen kayıtları getirmek için write_date filtresini kullanan artımlı senkronizasyonlar. Son senkronizasyon zaman damgasını saklayın ve bunu alan adı filtresi olarak kullanın. 100.000 kaydı aşan çok büyük veri kümeleri için API senkronizasyonu yerine doğrudan veritabanı çoğaltmayı düşünün.

Odoo REST API, Odoo Community Edition'da mevcut mu?

API anahtarı kimlik doğrulamasına sahip yerel REST API, Odoo 17 Enterprise'da tanıtıldı. Odoo Topluluğu için, tüm sürümlerde bulunan XML-RPC veya JSON-RPC'yi kullanabilir veya OCA'nın RESTful uç noktaları ekleyen dinlenme çerçevesi gibi topluluk modüllerini yükleyebilirsiniz. ECOSIRE'ın entegrasyon hizmetleri tüm Odoo sürümlerini ve API protokollerini destekler.

API çağrılarında Many2many ve One2many alanlarını nasıl yönetirim?

İlişkisel alanlar özel komut tuple'larını kullanır: (0, 0, değerler) yeni bir kayıt oluşturmak ve bağlamak için, (1, id, değerler) bağlantılı bir kaydı güncellemek için, (2, id, 0) bağlantılı bir kaydı silmek için, (3, id, 0) silmeden bağlantıyı kaldırmak için, (4, id, 0) mevcut bir kaydı bağlamak için, (5, 0, 0) tümünün bağlantısını kaldırmak için ve (6, 0, [ids]) tüm bağlantıları değiştirmek için. Okumak için bu alanlar varsayılan olarak kimlik listelerini döndürür; tüm verileri almak için alan adıyla birlikte search_read kullanın.

Sonraki Adımlar

API entegrasyonu modern iş sistemlerinin omurgasıdır. İster basit bir veri senkronizasyonu ister karmaşık, çok platformlu bir düzenleme oluşturuyor olun, bu kılavuzdaki modeller size çok iyi hizmet edecektir.

İlgili kaynaklar:

• Odoo Python Geliştirme Kılavuzu — Odoo'nun Python arka ucuna derinlemesine bakış
• Web Kancası Hata Ayıklama Kılavuzu — Web kancası entegrasyonlarında sorun giderme
• ECOSIRE Marketplace Bağlayıcıları — Büyük platformlar için önceden oluşturulmuş entegrasyonlar

Odoo API entegrasyonu konusunda yardıma mı ihtiyacınız var? ECOSIRE'ın entegrasyon ekibi Odoo'yu Shopify, Amazon, Salesforce ve özel ERP'ler dahil 50'den fazla harici platforma bağladı. Basit veri senkronizasyonlarından gerçek zamanlı çift yönlü orkestrasyona kadar ölçeklenebilir entegrasyonlar oluşturuyoruz. Ücretsiz teknik danışmanlık planlayın.