OmniCRM API

OmniCRM 中的所有功能都可以通过 API 访问 - 没有仅在 UI 中可用的功能。

这使您能够将 OmniCRM 与其他系统集成或自动化任务。

API 是一个 RESTful API，并使用多种身份验证方法进行安全保护，包括 JWT 令牌、API 密钥和 IP 白名单。

API 使用 Swagger 进行文档编制，这是一个允许轻松阅读、理解和测试 API 功能的工具。

API 文档可以在以下 URL 获取：

<https://yourcrm/crm/docs/>

OmniCRM Swagger Page

身份验证方法

OmniCRM 支持三种身份验证方法，每种方法旨在满足不同的用例：

JWT Bearer Tokens - 用于交互式用户会话（Web UI、移动应用）
API Keys - 用于服务器到服务器的集成和自动化脚本
IP Whitelisting - 用于受信任的内部系统（配置服务器、监控工具）

JWT Bearer Token 身份验证

这是用户会话的主要身份验证方法。用户使用电子邮件和密码登录，接收 JWT 令牌，并在后续请求中使用它。

用例：

Web UI 身份验证
移动应用身份验证
短期程序访问

如何进行身份验证：

要登录，请将以下结构的 JSON 主体作为 POST 请求发送到 /crm/auth/login：

{
    "email": "youruser@yourdomain.com",
    "password": "yourpassword"
}

API 将返回一个包含 token 字段的 JSON 对象，该字段用于验证所有未来的请求。此外，响应还包括一个 refresh_token，可以在令牌过期时用于刷新令牌，以及用户的权限和角色。

您可以通过 Swagger 页面测试此功能，选择 /auth/login 端点，填写您的用户名和密码，然后单击 Try it out 按钮。

OmniCRM Swagger Page

要授权会话，请复制令牌值并单击 Swagger 页面右上角的 "Authorize" 按钮。在 "Value" 字段中粘贴令牌，前面加上 Bearer，然后单击 "Authorize"。

OmniCRM Swagger Bearer Auth

现在，所有后续请求将使用此令牌进行身份验证。

API Key 身份验证

API 密钥为服务器到服务器的集成和自动化脚本提供安全、长期的身份验证，而无需用户密码。

用例：

自动化配置系统
监控和警报工具
与外部系统的集成
定时任务和 cron 作业

API 密钥的工作原理：

API 密钥在 crm_config.yaml 文件中配置，并与特定角色和权限相关联。每个 API 密钥都是一个安全的随机字符串（最少 32 个字符），在通过 X-API-KEY 头传递时用于验证请求。

配置 API 密钥：

API 密钥必须由具有服务器访问权限的管理员添加到 crm_config.yaml 中：

api_keys:
  your-secure-api-key-here-minimum-32-chars:
    roles:
      - admin
    description: "Provisioning automation system"
  another-api-key-for-monitoring-system:
    roles:
      - view_customer
      - view_service
    description: "Monitoring and alerting"

使用 API 密钥：

在请求的 X-API-KEY 头中包含 API 密钥：

curl -X GET "https://yourcrm.com/crm/customers" \
  -H "X-API-KEY: your-secure-api-key-here-minimum-32-chars"

Python 示例：

import requests

crm_url = 'https://yourcrm.com'
api_key = 'your-secure-api-key-here-minimum-32-chars'

headers = {
    "Content-Type": "application/json",
    "X-API-KEY": api_key
}

# 获取客户
response = requests.get(crm_url + '/crm/customers', headers=headers)
for customer in response.json()['data']:
    print(customer)

最佳实��：

使用加密安全的随机生成器生成 API 密钥（openssl rand -base64 48）
为不同的系统使用不同的 API 密钥
在 description 字段中记录每个 API 密钥的目的
定期轮换 API 密钥
永远不要将 API 密钥提交到版本控制
为每个 API 密钥分配最小必要权限

IP 白名单身份验证

IP 白名单允许特定 IP 地址在无需身份验证的情况下访问 API。这对于在私有网络上受信任的内部系统非常有用。

用例：

内部配置服务器
管理 VLAN 上的网络监控系统
在受控基础设施上运行的 Ansible 剧本

配置 IP 白名单：

将受信任的 IP 地址添加到 crm_config.yaml：

ip_whitelist:
  - 192.168.1.100
  - 10.0.0.0/24
  - 172.16.50.10

安全考虑：

仅在私有、安全的网络上使用 IP 白名单
永远不要将公共 IP 地址列入白名单
使用尽可能具体的 IP 范围
记录每个 IP 被列入白名单的原因
定期审核白名单中的 IP

使用 Python 的示例 API 调用

以下是如何使用 JWT 令牌身份验证登录并检索客户列表的示例：

import requests

crm_url = 'https://yourcrm.com'
session = requests.Session()

print("将数据配置到服��器: " + str(crm_url))

headers = {
    "Content-Type": "application/json"
}

# 获取身份验证令牌
response = session.post(crm_url + '/crm/auth/login', json={
    "email": "youruser@yourdomain.com",
    "password": "yourpassword"
}, headers=headers)

print(response.status_code)
print(response.json())
assert response.status_code == 200

headers['Authorization'] = 'Bearer ' + response.json()['token']
print("成功认证到 CRM")

# 获取客户
response = session.get(crm_url + '/crm/customers', headers=headers)
for customer in response.json()['data']:
    print(customer)

身份验证方法​

JWT Bearer Token 身份验证​

API Key 身份验证​

IP 白名单身份验证​

使用 Python 的示例 API 调用​

身份验证方法

JWT Bearer Token 身份验证

API Key 身份验证

IP 白名单身份验证

使用 Python 的示例 API 调用