# Odoo Rpc API

> 当需要让外部应用通过 Odoo 的 JSON-RPC / XML-RPC 外部 API 读写记录、做集成或中间件、排查鉴权与权限报错时使用；做认证(authenticate 取 uid)、调用模型方法(execute_kw / call_kw)、记录增删改查并产出 Python/JavaScript/curl 可复制调用代码；不适用于 OAuth2 或会话 cookie 鉴权、二进制文件上传、Odoo 模块二次开发或本地化税务合规；触发词：odoo、JSON-RPC、XML-RPC、execute_kw、search_read、call_kw、API key、odoo 集成

- Skill: `findscripter/odoo-rpc-api` (Agent Skill)
- Install (CLI): `npx skillmds@latest add findscripter/odoo-rpc-api`
- Raw SKILL.md: https://api.skillmd.com/api/skills/findscripter/odoo-rpc-api/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- License: MIT
- Author: findscripter (https://skillmd.com/u/findscripter)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/findscripter/odoo-rpc-api

---

## 何时使用

适用于把外部系统接到 Odoo、用其外部 API 增删改查记录的场景：

- 把外部应用（Django、Node.js、移动端等）连到 Odoo 读写数据。
- 跑自动化脚本批量导入/导出 Odoo 数据。
- 在 Odoo 与第三方平台之间搭中间件。
- 排查 API 鉴权或权限报错，给出诊断与修正后的调用。

**不该用边界**：

- 不覆盖 **OAuth2 / 会话 cookie 鉴权**——本技能只用 API key（token）方式。
- 不做**二进制/文件上传**：`/xmlrpc/2/` 端点不支持；二进制走 JSON-RPC 操作 `ir.attachment` 模型。
- 不涉及 Odoo 模块二次开发与数据建模；本地化税务/电子发票合规请走 `odoo-localization-compliance`。
- 缺 URL、数据库名、凭据或 Odoo 版本等关键输入时，先停下来追问，别瞎猜。

## 步骤

1. **备齐前置信息**：`url`、`db`（数据库名）、`username`、`API key`（生产环境用 key，勿用密码）。
2. **认证取 uid**：调 `/xmlrpc/2/common` 的 `authenticate(db, user, password, {})` 拿到 `uid`，失败说明 db/凭据有误。
3. **调用模型**：经 `/xmlrpc/2/object` 的 `execute_kw(db, uid, password, model, method, args, kwargs)` 执行模型方法。
4. **选对方法**：查询优先用 `search_read`（一次往返）而非 `search`+`read`；写入用 `create`/`write`/`unlink`。
5. **传 domain 与 kwargs**：`args` 里放 domain 过滤（如 `[[['state','=','sale']]]`），`kwargs` 放 `fields`/`limit`/`offset`。
6. **生产加固**：凭据进环境变量/密钥管理；加连接重试与指数退避；批量操作而非紧凈循环。

## 指令

端点与签名速查：

| 用途 | 端点 / 调用 |
|---|---|
| 认证 | `common.authenticate(db, user, pwd, {})` → `uid`（`/xmlrpc/2/common`） |
| 模型调用 | `models.execute_kw(db, uid, pwd, model, method, args, kwargs)`（`/xmlrpc/2/object`） |
| JSON-RPC | `POST /web/dataset/call_kw`，body 走 JSON-RPC 2.0（`id` 必填） |
| 常用 method | `search_read` / `create` / `write` / `unlink` / `fields_get` |

## 示例

**示例 1：认证 + 读取记录（Python / XML-RPC）**

```python
import xmlrpc.client

url = 'https://myodoo.example.com'
db = 'my_database'
username = 'admin'
password = 'my_api_key'  # 生产用 API key，勿用密码

# 1) 认证
common = xmlrpc.client.ServerProxy(f'{url}/xmlrpc/2/common')
uid = common.authenticate(db, username, password, {})
print(f"Authenticated as UID: {uid}")

# 2) 调用模型：查已确认销售单
models = xmlrpc.client.ServerProxy(f'{url}/xmlrpc/2/object')
orders = models.execute_kw(db, uid, password,
    'sale.order', 'search_read',
    [[['state', '=', 'sale']]],
    {'fields': ['name', 'partner_id', 'amount_total'], 'limit': 10}
)
for order in orders:
    print(order)
```

**示例 2：创建记录（Python）**

```python
new_partner_id = models.execute_kw(db, uid, password,
    'res.partner', 'create',
    [{'name': 'Acme Corp', 'email': 'info@acme.com', 'is_company': True}]
)
print(f"Created partner ID: {new_partner_id}")
```

**示例 3：JSON-RPC via curl**

```bash
curl -X POST https://myodoo.example.com/web/dataset/call_kw \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "call",
    "id": 1,
    "params": {
      "model": "res.partner",
      "method": "search_read",
      "args": [[["is_company", "=", true]]],
      "kwargs": {"fields": ["name", "email"], "limit": 5}
    }
  }'
# 注：JSON-RPC 2.0 规范要求 "id" 用于关联请求与响应。
# 模型方法调用走 /web/dataset/call_kw 端点。
```

## 注意事项

- ✅ 用 **API Key**（Settings → Technical → API Keys，Odoo 14+）而非密码。
- ✅ 用 `search_read` 替代 `search`+`read`，减少网络往返。
- ✅ 生产环境务必处理连接异常并实现带指数退避的重试。
- ✅ 凭据存环境变量或密钥管理器（如 AWS Secrets Manager、`.env`），并定期轮换。
- ❌ 别把密码/API key 硬编码进脚本。
- ❌ 别在紧凈循环里逐条调用——用批量操作显著降低服务端压力。
- ❌ 别用主管理员密码做集成——建专用集成用户，授予最小必要权限。
- ⚠️ 限制：XML-RPC 层无内置限流，需客户端自行节流；`/xmlrpc/2/` 不支持文件上传（二进制走 JSON-RPC + `ir.attachment`）；Odoo.sh（SaaS）部分套餐可能限制外部 API，先确认订阅是否开放。

## 互见

- related：`odoo-localization-compliance` —— 同属 Odoo，覆盖本地化与税务合规配置
- combines_with：`odoo-localization-compliance` —— RPC 接口对接 + 合规建模常组合落地国家级 ERP 集成

---
本条采编自 sickn33/antigravity-awesome-skills（MIT）。