SuiteCRM 开发者文档 API V8 设置指南

一、简介

SuiteCRM API版本8公开了一组资源,供希望利用SuiteCRM提供的强大CRM功能的客户端使用。

API框架采用了Restful设计来简化 JSON API 1.0 HTTPS上的标准消息。它包括元对象,以提供JSON API 1.0标准中尚未定义的功能。SuiteCRM API由SuiteCRM中提供的OAuth 2服务器保护。

二、要求

为了防止中间人攻击,授权服务器务必要求将TLS与服务器身份验证结合使用,如 RFC2818 发送给授权和令牌端点的任何请求。

客户端必须按照以下定义验证授权服务器的TLS证书: RFC6125 并根据其对服务器身份验证的要求。

SuiteCRM使用密钥加密来进行加密和解密,以及验证签名的完整性。

请确保您具有以下条件:

  • 已安装和配置OpenSSL PHP扩展
  • 必须将SuiteCRM实例配置为使用HTTPS / SSL
  • 您需要拥有PHP 5.5.9或7.0及更高版本

为了能够成功连接到端点,您需要完成本节下的步骤。 开始呼叫端点之前 除了这里提到的。

三、授权配置 

身份验证:获取会话:SuiteCRM API要求客户端具有活动会话才能使用该API。通过与 OAuth 2服务器,使用一种可用的授权类型。

配置授权类型:在使用API​​之前,必须先配置SuiteCRM授予对客户端的访问权限。SuiteCRM 7.10提供了一个管理面板,您可以通过该面板添加客户端和撤销令牌。要配置授予类型,请选择管理面板,然后选择OAuth2客户端和令牌:

SuiteCRM API
SuiteCRM API

可用的 授权 类型 

SuiteCRM版本可用的授权类型
7.10.0密码授予
7.10.2
密码授予,客户凭证授予

3.1 客户证书授予 

客户端凭据授予是所有授予类型中最简单的,此授予用于验证计算机或服务。选择新的客户端凭据客户端:

客户证书授予
客户证书授予

开始配置授权:

开始配置授权
开始配置授权
项目描述
名称这使得识别客户变得容易。
更改秘密定义在身份验证期间发布到服务器的client_secret
是机密的机密客户端是一种能够使客户端密码对世界保密的应用程序。
关联的用户通过将客户端与用户的安全特权相关联来限制客户端对CRM的访问。

保存后,“秘密”将被散列,以后将无法访问。“ id”是由SuiteCRM创建的,保存客户端后将可见。

SuiteCRM客户端管理
SuiteCRM客户端管理

使用客户端凭据进行身份验证

POST /Api/access_token

必要参数 

参数
grant_typeclient_credentials
client_idExampleClientName
client_secretExampleSecretPassword

示例请求(PHP):

$ch = curl_init();
$header = array(
    'Content-type: application/vnd.api+json',
    'Accept: application/vnd.api+json',
 );
$postStr = json_encode(array(
    'grant_type' => 'client_credentials',
    'client_id' => '3D7f3fda97-d8e2-b9ad-eb89-5a2fe9b07650',
    'client_secret' => 'client_secret',
));
$url = 'https://path-to-instance/Api/access_token';
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $postStr);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
$output = curl_exec($ch);

示例响应:

{
   "token_type":"Bearer",
   "expires_in":3600,
   "access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjdkOTEyODNhMjc1NDdkNDRlMzNmOTc5ZjVmMGRkYzQwNzg1ZGY5NGFhMWI5MDVlZGNmMzg3NWIxYjJkZDMzNDljZWEyNjZhMTQ2OTE5OWIzIn0.eyJhdWQiOiJzdWl0ZWNybV9jbGllbnQiLCJqdGkiOiI3ZDkxMjgzYTI3NTQ3ZDQ0ZTMzZjk3OWY1ZjBkZGM0MDc4NWRmOTRhYTFiOTA1ZWRjZjM4NzViMWIyZGQzMzQ5Y2VhMjY2YTE0NjkxOTliMyIsImlhdCI6MTUxODE5NTEwMiwibmJmIjoxNTE4MTk1MTAyLCJleHAiOjE1MTgxOTg3MDIsInN1YiI6IjEiLCJzY29wZXMiOltdfQ.EVGuRisoMxSIZut3IWtgOYISw8lEFSZgCWYCwseLEfOuPJ8lRMYL4OZxhu9gxJoGF0nj3yc6SYDPxovrsoj8bMoX38h4krMMOHFQLoizU0k2wAceOjZG1tWKPhID7KPT4TwoCXbb7MqAsYtVPExH4li7gSphJ8wvcWbFdS5em89Ndtwqq3faFtIq6bv1R4t0x98HHuT7sweHUJU40K9WQjbAfIOk8f5Y6T2wassN2wMCBB8CC6eUxLi14n2D6khHvkYvtPbXLHpXSHZWvEhqhvjAeSR5MmMrAth9WDSWUx7alO-ppsZpi8U7-g9Be5p6MRatc25voyTI2iTYbx02FQ",
}
token_type the Bearer token value
expires_in 代表访问令牌的TTL的整数
access_token一个 JWT使用授权服务器的私钥签名。每次您向API请求时,都需要在HTTP标头中添加此标头

您可以将承载令牌存储在数据库中,并在请求中使用,例如:

$header = array(
   'Content-type: application/vnd.api+json',
   'Accept: application/vnd.api+json',
   'Authorization: Bearer ' . $your_saved_access_token
);

3.2 密码授予

密码授予用于允许用户使用用户名和密码登录SuiteCRM。选择新的密码客户端, 开始配置授权:

SuiteCRM密码授权
SuiteCRM密码授权
名称这使得识别客户变得容易。
更改机密定义在身份验证期间发布到服务器的client_secret
是机密的机密客户端是一种能够使客户端密码对世界保密的应用程序。

保存后,“更改机密”将被散列,以后将无法访问。“ id”是由SuiteCRM创建的,保存客户端后将可见。

密码授予认证 

POST /Api/access_token

必要参数 

参数
grant_type password
client_idExampleClientName
client_secretExampleSecretPassword
username admin
password secret

请更改粗体值以匹配您选择的身份验证详细信息。

示例请求(PHP):

$ch = curl_init();
$header = array(
    'Content-type: application/vnd.api+json',
    'Accept: application/vnd.api+json',
 );
$postStr = json_encode(array(
    'grant_type' => 'password',
    'client_id' => '3D7f3fda97-d8e2-b9ad-eb89-5a2fe9b07650',
    'client_secret' => 'client_secret',
    'username' => 'admin',
    'password' => 'admin',
));
$url = 'https://path-to-instance/Api/access_token';
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $postStr);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
$output = curl_exec($ch);

示例响应:

{
   "token_type":"Bearer",
   "expires_in":3600,
   "access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjdkOTEyODNhMjc1NDdkNDRlMzNmOTc5ZjVmMGRkYzQwNzg1ZGY5NGFhMWI5MDVlZGNmMzg3NWIxYjJkZDMzNDljZWEyNjZhMTQ2OTE5OWIzIn0.eyJhdWQiOiJzdWl0ZWNybV9jbGllbnQiLCJqdGkiOiI3ZDkxMjgzYTI3NTQ3ZDQ0ZTMzZjk3OWY1ZjBkZGM0MDc4NWRmOTRhYTFiOTA1ZWRjZjM4NzViMWIyZGQzMzQ5Y2VhMjY2YTE0NjkxOTliMyIsImlhdCI6MTUxODE5NTEwMiwibmJmIjoxNTE4MTk1MTAyLCJleHAiOjE1MTgxOTg3MDIsInN1YiI6IjEiLCJzY29wZXMiOltdfQ.EVGuRisoMxSIZut3IWtgOYISw8lEFSZgCWYCwseLEfOuPJ8lRMYL4OZxhu9gxJoGF0nj3yc6SYDPxovrsoj8bMoX38h4krMMOHFQLoizU0k2wAceOjZG1tWKPhID7KPT4TwoCXbb7MqAsYtVPExH4li7gSphJ8wvcWbFdS5em89Ndtwqq3faFtIq6bv1R4t0x98HHuT7sweHUJU40K9WQjbAfIOk8f5Y6T2wassN2wMCBB8CC6eUxLi14n2D6khHvkYvtPbXLHpXSHZWvEhqhvjAeSR5MmMrAth9WDSWUx7alO-ppsZpi8U7-g9Be5p6MRatc25voyTI2iTYbx02FQ",
   "refresh_token":"def50200d2fb757e4c01c333e96c827712dfd8f3e2c797db3e4e42734c8b4e7cba88a2dd8a9ce607358d634a51cadd7fa980d5acd692ab2c7a7da1d7a7f8246b22faf151dc11a758f9d8ea0b9aa3553f3cfd3751a927399ab964f219d086d36151d0f39c93aef4a846287e8467acea3dfde0bd2ac055ea7825dfb75aa5b8a084752de6d3976438631c3e539156a26bc10d0b7f057c092fce354bb10ff7ac2ab5fe6fd7af3ec7fa2599ec0f1e581837a6ca2441a80c01d997dac298e1f74573ac900dd4547d7a2a2807e9fb25438486c38f25be55d19cb8d72634d77c0a8dfaec80901c01745579d0f3822c717df21403440473c86277dc5590ce18acdb1222c1b95b516f3554c8b59255446bc15b457fdc17d5dcc0f06f7b2252581c810ca72b51618f820dbb2f414ea147add2658f8fbd5df20820843f98c22252dcffe127e6adb4a4cbe89ab0340f7ebe8d8177ef382569e2aa4a54d434adb797c5337bfdfffe27bd8d5cf4714054d4aef2372472ebb4"
}
token_type不记名令牌值
expires_in 代表访问令牌的TTL的整数
access_token一个 JWT使用授权服务器的私钥签名。每次您向API请求时,都需要在HTTP标头中添加此标头
refresh_token加密的有效负载,可用来在访问令牌过期时刷新访问令牌。

您可以将承载令牌存储在数据库中,并在请求中使用,例如:

$header = array(
   'Content-type: application/vnd.api+json',
   'Accept: application/vnd.api+json',
   'Authorization: Bearer ' . $your_saved_access_token
);
滚动至顶部