Odoo 外部接口开发与调用

本教学文档适用于希望通过 JSON-RPC 或自定义接口从外部系统访问 Odoo 数据和模型的开发者，尤其适用于接口联调和系统集成场景。

---

1. Odoo 接口访问方式总览

Odoo 支持两大类外部接口调用方式：

✅ 原生 JSON-RPC 接口（官方标准）

• 登录验证接口：/web/session/authenticate
• 数据模型操作：/web/dataset/call_kw
• 通用 JSON-RPC 网关：/jsonrpc

✅ 自定义 HTTP 接口（灵活扩展）

• 使用 @http.route 装饰器创建自定义接口
• 示例路径如：/api/modules

---

2. @http.route 装饰器参数详解

以下是定义自定义接口的标准形式：

@http.route("/api/models", type="json", auth="user", methods=["GET"], csrf=False)

参数	含义
"/api/models"	URL 路径，定义接口访问地址
type="json"	该接口只接受 JSON 请求体，通常使用 POST 请求
auth="user"	限定访问权限为已登录用户；其他选项有 public（匿名）、none（完全开放）
methods=["GET"]	尽管写的是 GET，但实际上请求仍需使用 POST（Odoo 的 JSON 接口限制）
csrf=False	禁用 CSRF 检查，推荐对外提供接口时使用

---

3. 自定义接口开发示例

@http.route("/api/modules", type="json", auth="user", methods=["GET"], csrf=False)
def get_modules(self):
    modules = request.env["ir.module.module"].sudo().search_read([], ["name", "shortdesc"])
    return {"code": 200, "message": "模块获取成功", "data": modules}

上述接口将返回当前系统已安装模块的名称与简要描述。

---

4. 接口调用方式详解

✅ 方法一：基于 Session 的 Cookie 登录（推荐）

1. 调用登录接口获取 Session：

POST /web/session/authenticate
{
  "jsonrpc": "2.0",
  "params": {
    "db": "odoo18",
    "login": "admin",
    "password": "admin"
  }
}

2. 拿到 session_id 后，在请求头中添加：

Cookie: session_id=YOUR_SESSION_ID

3. 使用该 Cookie 调用自定义接口或 Odoo 原生接口：

POST /web/dataset/call_kw
{
  "jsonrpc": "2.0",
  "params": {
    "model": "bug.report",
    "method": "search_read",
    "args": [],
    "kwargs": {
      "fields": ["id", "name", "item_number", "description"],
      "limit": 10
    }
  }
}
POST /api/modules
{}

---

✅ 方法二：使用用户名密码调用（纯 JSON-RPC 流程）

1. 登录获取 UID：

POST /jsonrpc
{
  "jsonrpc": "2.0",
  "method": "call",
  "params": {
    "service": "common",
    "method": "login",
    "args": ["odoo18", "admin", "admin"]
  },
  "id": 1
}

2. 用 UID、密码继续访问模型接口：

POST /jsonrpc
{
  "jsonrpc": "2.0",
  "method": "call",
  "params": {
    "service": "object",
    "method": "execute",
    "args": [
      "odoo18",      // 数据库名
      2,                 // UID
      "admin",           // 密码
      "bug.report",      // 模型名
      "search_read",     // 方法
      [],                // 搜索条件
      ["id", "item_number", "name", "description"]
    ]
  },
  "id": 1
}

---

• 💡 常见 JSON-RPC 服务类型

服务名 (service)	功能	常用方法
common	登录、获取版本号	login, version, authenticate
object	模型操作（增删改查）	execute, execute_kw
db	数据库管理	list, create, drop, dump
report	报表导出（如 PDF）	render_report, get_pdf
wizard	向导操作（临时模型）	较少使用

---

✅ 方法三：使用 API Key（推荐）

从 Odoo 15 起，每个用户可以生成 API Key 用于接口调用。

• 生成步骤：

  1. 登录 Odoo 后台
  2. 进入“我的账户”（My Profile）
  3. 创建新的 API 密钥并复制

• 使用方式：

与 JSON-RPC 调用方式一致，只需将登录密码替换为 API Key。

{
  "jsonrpc": "2.0",
  "method": "call",
  "params": {
    "service": "object",
    "method": "execute",
    "args": [
      "odoo18", 
      2, 
      "API_KEY_XXX", 
      "res.partner", 
      "search_read", 
      [],
      ["id", "name", "email"]
    ]
  },
  "id": 1
}

5. 使用 Apifox 调试 Odoo 接口

调试自定义接口（如 /api/modules）

1. 请求方式：POST
2. 请求地址：http://127.0.0.1:8069/api/modules
3. 请求头（Header）添加：

Content-Type: application/json
Cookie: session_id=YOUR_SESSION_ID

4. 请求体（Body）：JSON 格式，最简单可写 {}

---

6. 常见错误与排查建议

错误信息	可能原因
400 Bad Request	请求非 JSON 格式，但接口定义为 type="json"
tuple index out of range	JSON-RPC 参数结构错误，通常是 args 结构错误
403 Forbidden	未登录或权限不足
csrf token missing	未设置 csrf=False，接口默认启用 CSRF 防护

---

7. 开发建议与小贴士

• 自定义接口推荐使用 type="json"，避免数据解析错误
• 如果接口对外暴露，请禁用 CSRF 防护并控制访问权限
• 推荐使用 session + Cookie 的方式调用接口，更安全且便于管理
• 建议在 Apifox 中先调试登录获取 session，再调用其他接口