数字证书产品对接文档
此文档版本专门为 API Version5 服务编写。API V5 比起API V2、API V3 增加了部分新的接口,所有错误代码和数据结构均兼容之前版本的API服务,因此您可以将您现有的API接口直接迁移到此版本,并将新的功能集成到您的系统中。
主要更新:
- 增加队列机制,优化处理大规模签发和续费情况;
- 更加规范的数据结构;
- 移除了CA处的订单编号字段(保留结构,返回null),便于队列处理;
- 支持调试(完善中);
- 支持记录请求日志,可从控制台查看请求日志。
基础路径
API BASE URL
- https://api.trustocean.com/ssl/v5生产服务器
调用说明
请求
请求方式:POST
所有的API接口仅接受 POST 方式(method)请求
参数传入方式
传参方式:Content-Type: application/x-www-form-urlencoded
即使用表单方式传递每个接口所需的业务参数和认证参数。
HTTP状态码
TRUSTOCEAN API 不采用 HTTP 状态码标识请求状态,因此无论请求处理成功与否,响应的 HTTP 头中状态都应该为 status:200
。
响应
TRUSTOCEAN API 的响应统一为标准json
格式,成功响应中同时包含了请求的处理状态和对应的处理结果,如下为调用getPreDomainValidationInformation
接口返回的响应。
认证
API的每一个方法都需要认证,您需要在每次请求的参数中增加username
和password
参数来完成验证:
username
API用户名password
您的API Token,请登陆TrustOcean控制台并访问API设置页面获取
请求限制
为了防止拒绝服务攻击,API 制定了一定的限流策略,规则如下:
- 认证失败或API账户名/API Token无效的请求,24小时内,连续收到超过3次,自动封禁发出请求的公网IP地址,自动禁止该API账户登陆(需要联系我们技术人员解封)。
- 访问令牌有效的请求,每分钟可请求 300 次
错误
TRUSTOCEAN API 使用响应中的status
字段表示请求的处理状态,当status
值为error
时,将同时返回error_code
和message
字段,error_code
值可标识大致错误类型,错误详情将由message
字段值描述。
业务错误说明
当请求出错时,错误响应也将通过 JSON 形式返回,其中包括业务错误码 error_code
和错误原因 message
,例如:
{
"status":"error",
"error_code": 770039,
"message": "账户余额不足,请您充值后再试"
}
错误码对照说明
错误码 | 描述 |
---|---|
99927 | 认证失败或权限不足: 账号或API Token错误;账户无权访问API服务;账户状态异常;发出请求的公网IP地址不在您API账户的白名单中 |
99926 | 请求的API方法不存在;无权执行请求的API方法 |
99925 | 签发系统维护中,请稍后再试 |
99924 | 请求中缺少认证参数username 和password |
99923 | 签发系统返回的错误信息,参考返回的message 值 |
99922 | 【订单状态不正确,不符合当前操作】请参考订单状态和操作逻辑说明 |
99921 | 缺少必要的业务参数,详情由返回的message 值确定 |
99915 | 网络出现错误,请稍后再试 |
99912 | 请求中提供的domains 值无效 |
99909 | 请求中提供的dcv_method 值无效 |
99906 | 请求中提供的contact_email 值无效 |
99902 | 请求中提供的csr_code 值无效,或CSR中的主域名格式不符合订单要求 |
99901 | 请求中提供的unique_id 值无效 |
99802 | 请求中提供的period 值无效 |
99801 | 请求中提供的pid 值无效 |
770039 | 【账户状态不正确,下单失败】账户余额不足;账户定价存在问题;账单计费故障等,详情由返回的message 值确定 |
版本
即便我们的API版本发生变化,我们依然会尽力维持在新版本中兼容旧的请求的数据结构。
订单状态
此处详细的描述了TrustOcean数字证书产品订单可能获取到的订单状态和其含义。
基本状态
通过API或控制台下单后可能获取到的订单/证书状态如下:
状态 | 含义 | 解释 |
---|---|---|
enroll_caprocessing | 签发中 | 订单已经提交至CA系统,但是还未签发,可能处于: 等待客户完成域名验证; 等待完成企业信息审核; 等待人工审核; 等待CA系统制证。 |
enroll_organization_pre | 企业信息预审中 | 订单已经提交至TrustOcean,正在等待后台人员完成组织信息预审,完成后将更改订单状态为 enroll_caprocessing ,后续API版本中可能将不再需要组织信息预审。 |
issued_active | 已签发 | 证书已经签发,并且已经可用 |
cancelled | 已取消 | 证书订单因客户原因被取消或客户已经申请退款,此状态为终结状态,不可继续操作订单 |
expired | 已过期 | 证书订单已经过期,对应的证书已经时效,需要续费签发新的证书。此状态为终结状态,不可继续操作订单 |
rejected | 已拒绝 | 证书订单因滥用,侵权,提交了包含在Google黑名单 (https://gsb.name 可查) 中域名被风控系统直接拒绝。此状态为终结状态,不可继续操作订单 |
revoked | 已吊销 | 证书订单因滥用、侵权、申请退费、调用revokeSSL 接口、受到举报等原因被CA或TrustOcean人员吊销。此状态为终结状态,不可继续操作订单 |
状态依赖
由于受到证书生命周期和联合控制规则限制,部分API方法只有在特定的订单状态下才可以调用,否则将调用失败。具有状态依赖的API方法如下:
API方法 | 名称 | 依赖状态 |
---|---|---|
reissueSSLOrder | 重新签名/更换CSR&KEY/更换域名 | 当前订单状态必须是issued_active |
revokeSSL | 吊销证书订单 | 当前订单状态必须是issued_active |
removeSanDomain | 移除未通过验证的域名 | 当前订单状态必须是enroll_caprocessing |
changeDCVMethod | 修改域名验证方式 | 当前订单状态必须是enroll_caprocessing |
cancelAndRefund | 提交订单退款请求 | 当前订单状态必须是issued_active 或者enroll_caprocessing 或者enroll_organization_pre |
PUSH / WEB HOOK 通知
TRUSTOCEAN现在支持对多种订单操作和状态更改执行 PUSH 主动通知,以避免您采用轮询方式增加服务器负担。 接入此通知准备工作:
- 需要您前往合作伙伴配置页面(https://console.trustocean.com/partner/api-setting) 填写您的
API PUSH
接口地址。 - 请将我们的IP地址
47.95.117.197
添加至您的服务器防火墙白名单(如果存在), 并且需要确保您的服务器网络可以正常访问此IP地址。 - 请将 PUSH 服务所用的 UserAgent
TrustOceanAPI/1.0 Mozilla/5.0
添加至您的网站WAF防火墙(如果存在)。
确认接收
我们将会为每次推送记录日志,请您正确处理并接收 PUSH 消息后返回 json
格式的消息:
{"status":"success"}
即表示处理成功,否则均表示为接收失败,当TrustOcean获取到处理失败信息时,将会按照下列的推送频率继续此消息的推送。
推送频率
为保障您的系统可以成功接收到我们推送的信息,我们将按照7个阶段进行推送。您的程序可以在任何一个阶段中的任何一次推送中进行确认接收。一旦完成确认接收成功,我们将会停止接下来的推送。
倘若您的程序在第七阶段(最后阶段)任然无法完成确认接收,本次通知将会失效,我们不再保留这条推送任务。您需要通过其他API方式获取证书信息。
- 一阶段: 实时推送一次,若没有完成确认接收;将会立即再推送第二次,若依然没有完成确认接收,则立即继续尝试第三次推送。如果依然没有完成确认接收,则进行下一个阶段。
- 二阶段: 每隔1分钟再次尝试推送,共尝试5次
- 三阶段: 每隔5分钟再次尝试推送,共尝试5次
- 四阶段: 每隔1小时再次尝试推送,共尝试1次
- 五阶段: 每隔2小时再次尝试推送,共尝试1次
- 六阶段: 每隔12小时再次尝试推送,共尝试1次
- 七阶段: 每隔24小时再次尝试推送,共尝试1次
数据结构(PUSH加密)
如果您的主API账户已经配置了用于加密PUSH信息的 RSA-SHA1公钥,那么您接收到的数据结构将会是被加密的,需要使用您的私钥解密后才能得到后续事务分类中阐述的数据类型。
加密后的PUSH消息例子
{"encrypted_data":"-----BEGIN TRUSTOCEAN ENCRYPTED DATA-----\nsome-encrypted-data-string-hereKOAJKSD0-/askljsa0-as89snPOAJIOD09A80SD7FAHJSN-----END TRUSTOCEAN ENCRYPTED DATA-----"}
解密PUSH消息
如果您确实已经在主账户配置了PUSH公钥,那么您可以参考这里的代码进行PUSH消息解密
/**
* @param string $pKey
* @param string $data
* @return array
* @throws TrustoceanException
*/
public function verifyAndGetRsaEncodedContent($pKey, $data){
// 您的本地 PrivateKey
$privateKey = $pKey;
// 加载 privateKey
$privateKey = openssl_get_privatekey($privateKey);
if($privateKey === false){
throw new TrustoceanException("管理员配置的PUSH私钥无效或格式不正确");
}
$header = "-----BEGIN TRUSTOCEAN ENCRYPTED DATA-----";
$footer = "-----END TRUSTOCEAN ENCRYPTED DATA-----";
$data = str_replace($footer, "", str_replace($header, "", $data));
$encodedStringArray = str_split($data, 172);
$decodedString = "";
foreach ($encodedStringArray as $chunk){
$result = openssl_private_decrypt(base64_decode($chunk),$temp,$privateKey);
if(!$result){
throw new TrustoceanException("私钥或传递的PUSH消息无效");
}
$decodedString .= $temp;
}
openssl_free_key($privateKey);
return json_decode($decodedString, 1, 10); // 返回解密后的 array
}
证书签发
证书一旦完成验证并签发,将会触发此事件并向您配置的 PUSH 接收终端地址 通过 POST
方式传送下列信息:
参数名称 | 类型 | 值 | 说明 |
---|---|---|---|
type | string | 固定值: "cert_issued" | 表示通知类型, 固定值"cert_issued"为证书签发通知 |
trustocean_id | string | 举例: 9002901 | 证书订单号码 |
vendor_id | string | 举例: 9028872629 | CA订单号码 |
certificate_id | string | 举例: 282988272651762 | 内部系统证书编号 |
ca_code | string | 举例: 证书链 | PEM格式的证书链代码 |
cert_code | string | 举例: 证书 | PEM格式的证书代码 |
status | string | 固定值: "issued_active" | 证书订单状态 |
issued_at | string | 举例: "2020-01-01 00:00:01" | 证书签发时间 |
paidcertificate_status | string | 举例: 状态描述信息 | 扩展描述证书状态 |
证书吊销
当证书被TRUSTOCEAN执行吊销时,将会触发此事件并向您配置的 PUSH 接收终端地址 通过 POST
方式传送下列信息:
参数名称 | 类型 | 值 | 说明 |
---|---|---|---|
type | string | 固定值: "cert_revoked" | 表示通知类型, 固定值"cert_revoked"为证书吊销通知 |
trustocean_id | string | 举例: 9002901 | 证书订单号码 |
vendor_id | string | 举例: 9028872629 | CA订单号码 |
certificate_id | string | 举例: 282988272651762 | 内部系统证书编号 |
cert_code | string | 举例: 证书 | PEM格式的证书代码 |
status | string | 固定值: "revoked" | 证书订单状态 |
证书取消
当证书订单因退款、或其他原因被TRUSTOCEAN执行取消操作时,将会触发此事件并向您配置的 PUSH 接收终端地址 通过 POST
方式传送下列信息:
参数名称 | 类型 | 值 | 说明 |
---|---|---|---|
type | string | 固定值: "cert_cancelled" | 表示通知类型, 固定值"cert_cancelled"为证书取消通知 |
trustocean_id | string | 举例: 9002901 | 证书订单号码 |
vendor_id | string | 举例: 9028872629 | CA订单号码 |
certificate_id | string | 举例: 282988272651762 | 内部系统证书编号 |
cert_code | string | 举例: 证书 | PEM格式的证书代码 |
status | string | 固定值: "cancelled" | 证书订单状态 |
处理退款
当证书订单的退款请求被TRUSTOCEAN做出处理时,将会触发此事件并向您配置的 PUSH 接收终端地址 通过 POST
方式传送下列信息:
参数名称 | 类型 | 值 | 说明 |
---|---|---|---|
type | string | 固定值: "refund_processed" | 表示通知类型, 固定值"refund_processed"为订单退款处理通知 |
trustocean_id | string | 举例: 9002901 | 证书订单号码 |
refund_at | string | 举例: "2020-01-01 00:00:01" | 退款处理时间 |
refund_status | string | 举例: "reject" | 退款状态: "reject" 表示被拒绝退款失败, "finished" 表示退款成功 |
certificate_status | string | 举例: "cancelled" | 退款后的证书订单状态 |
我们将会在后续增加更多的通知类型。
检查API 服务状态
鉴于CA签发系统会不定时进行维护等情况,我们提供此方法用于查询API服务和CA签发服务的可用性,您可以在提交订单之前先调用此接口检查CA签发服务状态。仅当返回结果中的status值为success时表示CA服务可用。对于已经转移到新版本API的用户,此方法可能不是必要的,我们已经在新版本中使用消息队列来接收所有新订单
HEADER
- Content-Typestring值:application/x-www-form-urlencoded
请求 BODY
- usernamestring
您的 API 账户名
- passwordstring
您的 API 密码
HEADER
- Content-Typestring值:application/json
参数
- statusstring
Example 1
请求
API服务连接成功
1{
2 "status": "<string>"
3}
获取账户基本信息
此接口用于查询API账户的基本信息,目前支持查询如下信息:账户余额
HEADER
- Content-Typestring值:application/x-www-form-urlencoded
请求 BODY
- usernamestring
您的 API 账户名
- passwordstring
您的 API 密码
HEADER
- Content-Typestring值:application/json
参数
- statusstring
- creditstring
Example 1
请求
API服务连接成功
1{
2 "status": "<string>",
3 "credit": "<string>"
4}
获取产品和价格信息
兼容方法,调用此方法可获取到适用您账户的所有产品列表,同时包含了证书产品的配置属性,同时包含价格信息。
HEADER
- Content-Typestring值:application/x-www-form-urlencoded
请求 BODY
- usernamestring
您的 API 账户名
- passwordstring
您的 API 密码
HEADER
- Content-Typestring值:application/json
参数
- statusstring
- productsarray
- 数组成员object
- products.pidstring
- products.namestring
- products.chineseNamestring
- products.classstring
- products.multidomainstring
- products.wildcardstring
- products.ipv4string
- products.brandstring
- products.sealstring
- products.scorestring
- products.periodsarray
- 数组成员string
- products.pricingobject
- 子属性
- pricing.baseobject
- 子属性
- base.Monthlystring
- base.Quarterlystring
- base.Annuallystring
- base.Bienniallystring
- base.Trienniallystring
- base.Quadrennialstring
- base.Quinquennialstring
- pricing.sanobject
- 子属性
- san.Monthlystring
- san.Quarterlystring
- san.Annuallystring
- san.Bienniallystring
- san.Trienniallystring
- san.Quadrennialstring
- san.Quinquennialstring
Example 1
请求
API服务连接成功
1{
2 "status": "<string>",
3 "products": [
4 {
5 "pid": "<integer>",
6 "name": "<string>",
7 "chineseName": "<string>",
8 "class": "<string>",
9 "multidomain": "<string>",
10 "wildcard": "<string>",
11 "ipv4": "<string>",
12 "brand": "<string>",
13 "seal": "<string>",
14 "score": "<string>",
15 "periods": [
16 "<string>",
17 "<string>"
18 ],
19 "pricing": {
20 "base": {
21 "Monthly": "<string>",
22 "Quarterly": "<string>",
23 "Annually": "<string>",
24 "Biennially": "<string>",
25 "Triennially": "<string>",
26 "Quadrennial": "<string>",
27 "Quinquennial": "<string>"
28 },
29 "san": {
30 "Monthly": "<string>",
31 "Quarterly": "<string>",
32 "Annually": "<string>",
33 "Biennially": "<string>",
34 "Triennially": "<string>",
35 "Quadrennial": "<string>",
36 "Quinquennial": "<string>"
37 }
38 }
39 },
40 {
41 "pid": "<integer>",
42 "name": "<string>",
43 "chineseName": "<string>",
44 "class": "<string>",
45 "multidomain": "<string>",
46 "wildcard": "<string>",
47 "ipv4": "<string>",
48 "brand": "<string>",
49 "seal": "<string>",
50 "score": "<string>",
51 "periods": [
52 "<string>",
53 "<string>"
54 ],
55 "pricing": {
56 "base": {
57 "Monthly": "<string>",
58 "Quarterly": "<string>",
59 "Annually": "<string>",
60 "Biennially": "<string>",
61 "Triennially": "<string>",
62 "Quadrennial": "<string>",
63 "Quinquennial": "<string>"
64 },
65 "san": {
66 "Monthly": "<string>",
67 "Quarterly": "<string>",
68 "Annually": "<string>",
69 "Biennially": "<string>",
70 "Triennially": "<string>",
71 "Quadrennial": "<string>",
72 "Quinquennial": "<string>"
73 }
74 }
75 }
76 ]
77}
生成域名验证信息
此接口仅可用于在正式提交证书请求到addSSLOrder或reissueSSLOrder接口之前获取域名验证信息,并做好相关的域名验证操作。在正式提交签发/重签之前做好域名验证,可以加快证书签发速度,最快可以1分钟内下证书。【注意】1.您需要保证此处传入的unique_id是未被使用过的。 2.您需要确保后续调用addSSLOrder或reissueSSLOrder时传入的csr_code、unique_id两个字段的值和此处传入的保持一致,否则将导致域名验证不通过
HEADER
- Content-Typestring值:application/x-www-form-urlencoded
请求 BODY
- usernamestring
您的 API 账户名
- passwordstring
您的 API 密码
- domainsstring
英文逗号隔开的域名列表,传入所有需要验证的域名
- csr_codestring
PEM格式的CSR代码内容
- unique_idstring
未被使用过的订单唯一识别字符串,8-15位字符,英文小写字母和数字组成,用于创建域名验证信息。此处的识别字符串同样要保留至调用addSSLOrder或reissueSSLOrder时进行消费
HEADER
- Content-Typestring值:application/json
参数
- statusstring
- pre_dcv_infoobject
- 子属性
- pre_dcv_info.each_of_your_domain_name_as_keyobject
- 子属性
- each_of_your_domain_name_as_key.isipstring
- each_of_your_domain_name_as_key.subdomainstring
- each_of_your_domain_name_as_key.topdomainstring
- each_of_your_domain_name_as_key.auth_email_addressesarray
- 数组成员string
- each_of_your_domain_name_as_key.dns_cnameobject
- 子属性
- dns_cname.dns_hoststring
- dns_cname.dns_typestring
- dns_cname.dns_valuestring
- each_of_your_domain_name_as_key.httpobject
- 子属性
- http.http_verifylinkstring
- http.http_filenamestring
- http.http_filecontentstring
- each_of_your_domain_name_as_key.httpsobject
- 子属性
- https.https_verifylinkstring
- https.https_filenamestring
- https.https_filecontentstring
Example 1
请求
API服务连接成功
1{
2 "status": "<string>",
3 "pre_dcv_info": {
4 "each_of_your_domain_name_as_key": {
5 "isip": "<boolean>",
6 "subdomain": "<string>",
7 "topdomain": "<string>",
8 "auth_email_addresses": [
9 "<string>",
10 "<string>"
11 ],
12 "dns_cname": {
13 "dns_host": "<string>",
14 "dns_type": "<string>",
15 "dns_value": "<string>"
16 },
17 "http": {
18 "http_verifylink": "<string>",
19 "http_filename": "<string>",
20 "http_filecontent": "<string>"
21 },
22 "https": {
23 "https_verifylink": "<string>",
24 "https_filename": "<string>",
25 "https_filecontent": "<string>"
26 }
27 }
28 }
29}
创建 SSL 证书订单
此方法用于创建DV SSL订单,实时递交至CA签发系统。您需要查看每个传递的字段含义以及规定,以确保您的订单信息正确
HEADER
- Content-Typestring值:application/x-www-form-urlencoded
请求 BODY
- pidstring
需要订购的产品的PID
- csr_codestring
PEM格式的CSR代码,单域名、通配符证书产品将采用CSR中主题名称(CommonName)作为主域名,多域名证书、多域通配符证书、IP地址证书不采用CSR中的主题名称(CommonName)
- periodstring
申请证书的有效期周期
- dcv_methodstring
必须提供,英文逗号隔开的域名验证选项。顺序必须和domains字段中的域名位置匹配。验证方法选项必须是http、https、dns或由getPreDomainValidationInformation返回的auth_email_addresses属性中的有效的邮箱地址。同时,IP地址仅支持http、https两种验证方式
- usernamestring
您的 API 账户名
- passwordstring
您的 API 密码
- unique_idstring
未被消费过的订单唯一识别字符串,8-15位字符,英文小写字母和数字组成,此处传入的值应该同之前调用getPreDomainValidationInformation方法时传入的值保持一致。同时,此处调用成功后将会正式消费掉传入的识别字符串
- contact_emailstring
证书联系人的邮件地址或证书实际申请人的联系邮件地址。此字段将传送至CA系统,作为证书持有人的凭据。
- callbackstring
用于接收此证书订单的 webhook Push 通知的 URL 网址,必须是以
https://
开头 - domainsstring
[多域名证书、IP地址证书、多域通配符证书产品必须提供] 英文逗号隔开的合法的域名列表,总长度不得超过 32767 个字符,IDN域名需要转码为punnyCode格式后提交
- renewstring
是否为续费订单,当且仅当传入值为yes时,系统才会标识为续费订单,额外赠送30~90天证书有效期
- organization_namestring
[OV\EV订单必须提供]组织名称,同企业执照/组织机构代码证上的名称保持一致。若该组织希望展示英文名称、商标名称或其他贸易名称,应自订单提交后联系TRUSTOCEAN在线客服进行验证和修改
- organizationalUnitNamestring
[OV\EV订单必须提供]申请人所在部门名称
- registered_address_line1string
[OV\EV订单必须提供]组织注册地址,同企业执照/组织机构代码证上的注册地址/办公地址保持一致
- registered_nostring
[OV\EV订单必须提供]组织注册编号,同企业执照/组织机构代码证上的编号一致,或企业的统一社会信用编码
- countrystring
[OV\EV订单必须提供]标准的国际化国家名称缩写字母,标识企业所在的注册地国家, 如: CN
- statestring
[OV\EV订单必须提供]组织所在地址的省、自治区、直辖市或洲名称
- citystring
[OV\EV订单必须提供]组织所在地址的城市名称
- postal_codestring
[OV\EV订单必须提供]组织所在地址的邮政编码
- organization_phonestring
[OV\EV订单必须提供]组织的联系电话,组织联系电话需经过TrustOcean认可的第三方数据库登记并公布,才可用于进行电话确认。若此处提供的电话号码未经第三方数据库登记,则实际确认电话将由后续验证验证人员确认
- date_of_incorporationstring
[OV\EV订单必须提供]组织成立日期,格式必须为:YYYY-MM-DD
- contact_namestring
[OV\EV订单必须提供]组织联系人,必须为组织内部员工,用于订单验证事宜沟通
- contact_titlestring
[OV\EV订单必须提供]组织联系人职位
- contact_phonestring
[OV\EV订单必须提供]组织联系人的直拨号码、手机号码
HEADER
- Content-Typestring值:application/json
参数
- statusstring
- vendor_idstring
- partner_order_idstring
- certificate_idstring
- cert_statusstring
- unique_idstring
- created_atstring
- trustocean_idstring
- csr_codestring
- contact_emailstring
- domainsarray
- 数组成员string
- dcv_infoobject
- 子属性
- dcv_info.each_of_your_domain_name_as_keyobject
- 子属性
- each_of_your_domain_name_as_key.domainstring
- each_of_your_domain_name_as_key.emailsarray
- 数组成员string
- each_of_your_domain_name_as_key.methodstring
- each_of_your_domain_name_as_key.statusstring
- each_of_your_domain_name_as_key.domainmd5hashstring
- each_of_your_domain_name_as_key.isipstring
- each_of_your_domain_name_as_key.subdomainstring
- each_of_your_domain_name_as_key.topdomainstring
- each_of_your_domain_name_as_key.dns_hoststring
- each_of_your_domain_name_as_key.dns_typestring
- each_of_your_domain_name_as_key.dns_valuestring
- each_of_your_domain_name_as_key.http_verifylinkstring
- each_of_your_domain_name_as_key.http_filenamestring
- each_of_your_domain_name_as_key.http_filecontentstring
- each_of_your_domain_name_as_key.https_verifylinkstring
- each_of_your_domain_name_as_key.https_filenamestring
- each_of_your_domain_name_as_key.https_filecontentstring
- each_of_your_domain_name_as_key.emailstring
Example 1
请求
API服务连接成功
1{
2 "status": "<string>",
3 "vendor_id": "<string>",
4 "partner_order_id": "<string>",
5 "certificate_id": "<string>",
6 "cert_status": "<string>",
7 "unique_id": "<string>",
8 "created_at": "<string>",
9 "trustocean_id": "<integer>",
10 "csr_code": "<string>",
11 "contact_email": "<string>",
12 "domains": [
13 "<string>",
14 "<string>"
15 ],
16 "dcv_info": {
17 "each_of_your_domain_name_as_key": {
18 "domain": "<string>",
19 "emails": [
20 "<string>",
21 "<string>"
22 ],
23 "method": "<string>",
24 "status": "<string>",
25 "domainmd5hash": "<string>",
26 "isip": "<boolean>",
27 "subdomain": "<string>",
28 "topdomain": "<string>",
29 "dns_host": "<string>",
30 "dns_type": "<string>",
31 "dns_value": "<string>",
32 "http_verifylink": "<string>",
33 "http_filename": "<string>",
34 "http_filecontent": "<string>",
35 "https_verifylink": "<string>",
36 "https_filename": "<string>",
37 "https_filecontent": "<string>",
38 "email": "<string>"
39 }
40 }
41}
获取域名验证状态
调用此方法可以实时获取域名验证状态和相关的验证信息,DV SSL订单在所有域名验证完成之后即可签发(CA延迟签发除外)。OV SSL/EV SSL订单在所有域名验证完成后还需要完成电话验证才可以签发
HEADER
- Content-Typestring值:application/x-www-form-urlencoded
请求 BODY
- usernamestring
您的 API 账户名
- passwordstring
您的 API 密码
- trustocean_idstring
订单号码,必须是由addSSLOrder或reissueSSLOrder返回的订单号码
HEADER
- Content-Typestring值:application/json
参数
- statusstring
- dcv_infoobject
- 子属性
- dcv_info.each_of_your_domain_name_as_keyobject
- 子属性
- each_of_your_domain_name_as_key.domainstring
- each_of_your_domain_name_as_key.emailsarray
- 数组成员string
- each_of_your_domain_name_as_key.methodstring
- each_of_your_domain_name_as_key.statusstring
- each_of_your_domain_name_as_key.domainmd5hashstring
- each_of_your_domain_name_as_key.isipstring
- each_of_your_domain_name_as_key.subdomainstring
- each_of_your_domain_name_as_key.topdomainstring
- each_of_your_domain_name_as_key.dns_hoststring
- each_of_your_domain_name_as_key.dns_typestring
- each_of_your_domain_name_as_key.dns_valuestring
- each_of_your_domain_name_as_key.http_verifylinkstring
- each_of_your_domain_name_as_key.http_filenamestring
- each_of_your_domain_name_as_key.http_filecontentstring
- each_of_your_domain_name_as_key.https_verifylinkstring
- each_of_your_domain_name_as_key.https_filenamestring
- each_of_your_domain_name_as_key.https_filecontentstring
- each_of_your_domain_name_as_key.emailstring
Example 1
请求
API服务连接成功
1{
2 "status": "<string>",
3 "dcv_info": {
4 "each_of_your_domain_name_as_key": {
5 "domain": "<string>",
6 "emails": [
7 "<string>",
8 "<string>"
9 ],
10 "method": "<string>",
11 "status": "<string>",
12 "domainmd5hash": "<string>",
13 "isip": "<boolean>",
14 "subdomain": "<string>",
15 "topdomain": "<string>",
16 "dns_host": "<string>",
17 "dns_type": "<string>",
18 "dns_value": "<string>",
19 "http_verifylink": "<string>",
20 "http_filename": "<string>",
21 "http_filecontent": "<string>",
22 "https_verifylink": "<string>",
23 "https_filename": "<string>",
24 "https_filecontent": "<string>",
25 "email": "<string>"
26 }
27 }
28}
刷新域名验证 / 重发验证邮件
此方法支持您手动催促系统执行新一轮的域名验证,前提是您已经通知用户做好了相关的DNS记录或上传好了HTTP验证文件。对于采用电子邮箱验证方式的域名,调用此方法可以重新发送验证邮件到对应的验证邮箱地址
HEADER
- Content-Typestring值:application/x-www-form-urlencoded
请求 BODY
- usernamestring
您的 API 账户名
- passwordstring
您的 API 密码
- trustocean_idstring
订单号码,必须是由addSSLOrder或reissueSSLOrder返回的订单号码
HEADER
- Content-Typestring值:application/json
参数
- statusstring
Example 1
请求
API服务连接成功
1{
2 "status": "<string>"
3}
修改域名验证方式
此方法支持对订单中还未通过验证的域名进行验证方式更换
HEADER
- Content-Typestring值:application/x-www-form-urlencoded
请求 BODY
- usernamestring
您的 API 账户名
- passwordstring
您的 API 密码
- trustocean_idstring
订单号码,必须是由addSSLOrder或reissueSSLOrder返回的订单号码
- domainstring
需要修改验证方式的域名,域名必须是由addSSLOrder或reissueSSLOrder返回的domains属性中的域名,且必须是未验证通过的域名
- methodstring
新的验证方法,验证方法选项必须是http、https、dns或由getPreDomainValidationInformation返回的auth_email_addresses属性中的有效的邮箱地址。同时,IP地址仅支持http、https两种验证方式
HEADER
- Content-Typestring值:application/json
参数
- statusstring
Example 1
请求
API服务连接成功
1{
2 "status": "<string>"
3}
移除无法验证的域名
仅支持以下订单类型调用: 多域名证书、IP地址证书、多域通配符证书订单 用于移除证书内无法验证的域名,一次仅可以移除一个域名。 同时,每个订单必须保留至少1个域名,无法全部移除
HEADER
- Content-Typestring值:application/x-www-form-urlencoded
请求 BODY
- usernamestring
您的 API 账户名
- passwordstring
您的 API 密码
- trustocean_idstring
订单号码,必须是由addSSLOrder或reissueSSLOrder返回的订单号码
- domainstring
需要移除的域名,域名必须是由addSSLOrder或reissueSSLOrder返回的domains属性中的域名,且必须是未验证通过的域名
HEADER
- Content-Typestring值:application/json
参数
- statusstring
Example 1
请求
API服务连接成功
1{
2 "status": "<string>"
3}
查询订单状态
此方法用于获取订单状态的摘要信息,调用间隔为每三分钟一次。实时查询CA签发系统中的订单状态
HEADER
- Content-Typestring值:application/x-www-form-urlencoded
请求 BODY
- usernamestring
您的 API 账户名
- passwordstring
您的 API 密码
- trustocean_idstring
订单号码,必须是由addSSLOrder或reissueSSLOrder返回的订单号码
HEADER
- Content-Typestring值:application/json
参数
- statusstring
- cert_statusstring
- messagestring
Example 1
请求
API服务连接成功
1{
2 "status": "<string>",
3 "cert_status": "<string>",
4 "message": "<string>"
5}
获取订单详情信息
此方法用于获取详细的订单信息,包含验证状态、产品信息、验证信息等
HEADER
- Content-Typestring值:application/x-www-form-urlencoded
请求 BODY
- usernamestring
您的 API 账户名
- passwordstring
您的 API 密码
- trustocean_idstring
订单号码,必须是由addSSLOrder或reissueSSLOrder返回的订单号码
HEADER
- Content-Typestring值:application/json
参数
- statusstring
- vendor_idstring
- parnter_order_idstring
- cert_statusstring
- unique_idstring
- created_atstring
- trustocean_idstring
- classstring
- product_namestring
- is_multidomainstring
- domain_countstring
- csr_codestring
- cert_codestring
- ca_codestring
- contact_emailstring
- domainsarray
- 数组成员string
- dcv_infoobject
- 子属性
- dcv_info.each_of_your_domain_name_as_keyobject
- 子属性
- each_of_your_domain_name_as_key.domainstring
- each_of_your_domain_name_as_key.emailsarray
- 数组成员string
- each_of_your_domain_name_as_key.methodstring
- each_of_your_domain_name_as_key.statusstring
- each_of_your_domain_name_as_key.domainmd5hashstring
- each_of_your_domain_name_as_key.isipstring
- each_of_your_domain_name_as_key.subdomainstring
- each_of_your_domain_name_as_key.topdomainstring
- each_of_your_domain_name_as_key.dns_hoststring
- each_of_your_domain_name_as_key.dns_typestring
- each_of_your_domain_name_as_key.dns_valuestring
- each_of_your_domain_name_as_key.http_verifylinkstring
- each_of_your_domain_name_as_key.http_filenamestring
- each_of_your_domain_name_as_key.http_filecontentstring
- each_of_your_domain_name_as_key.https_verifylinkstring
- each_of_your_domain_name_as_key.https_filenamestring
- each_of_your_domain_name_as_key.https_filecontentstring
- each_of_your_domain_name_as_key.emailstring
Example 1
请求
API服务连接成功
1{
2 "status": "<string>",
3 "vendor_id": "<string>",
4 "parnter_order_id": "<string>",
5 "cert_status": "<string>",
6 "unique_id": "<string>",
7 "created_at": "<string>",
8 "trustocean_id": "<integer>",
9 "class": "<string>",
10 "product_name": "<string>",
11 "is_multidomain": "<integer>",
12 "domain_count": "<integer>",
13 "csr_code": "<string>",
14 "cert_code": "<string>",
15 "ca_code": "<string>",
16 "contact_email": "<string>",
17 "domains": [
18 "<string>",
19 "<string>"
20 ],
21 "dcv_info": {
22 "each_of_your_domain_name_as_key": {
23 "domain": "<string>",
24 "emails": [
25 "<string>",
26 "<string>"
27 ],
28 "method": "<string>",
29 "status": "<string>",
30 "domainmd5hash": "<string>",
31 "isip": "<boolean>",
32 "subdomain": "<string>",
33 "topdomain": "<string>",
34 "dns_host": "<string>",
35 "dns_type": "<string>",
36 "dns_value": "<string>",
37 "http_verifylink": "<string>",
38 "http_filename": "<string>",
39 "http_filecontent": "<string>",
40 "https_verifylink": "<string>",
41 "https_filename": "<string>",
42 "https_filecontent": "<string>",
43 "email": "<string>"
44 }
45 }
46}
重签 / 更换域名 / 更换CSR / 更换私钥
此方法用于将已经签发的证书进行重签名操作,重签名操作支持:1.更换域名 2.在多域名证书中增加更多的域名 3.移除不需要的域名 4.更换CSR实现更换私钥的目的.适用于私钥丢失的情况对于多域名证书中增加新的域名的情况,仅需要验证新增加的域名,而无需验证同个订单中已经验证过的域名。
HEADER
- Content-Typestring值:application/x-www-form-urlencoded
请求 BODY
- usernamestring
您的 API 账户名
- passwordstring
您的 API 密码
- trustocean_idstring
订单号码,必须是由addSSLOrder或reissueSSLOrder返回的订单号码
- csr_codestring
PEM格式的CSR代码,单域名、通配符证书产品将采用CSR中主题名称(CommonName)作为主域名,多域名证书、多域通配符证书、IP地址证书不采用CSR中的主题名称(CommonName)
- contact_emailstring
证书联系人的邮件地址或证书实际申请人的联系邮件地址。此字段将传送至CA系统,作为证书持有人的凭据。
- dcv_methodstring
必须提供,英文逗号隔开的域名验证选项。顺序必须和domains字段中的域名位置匹配。验证方法选项必须是http、https、dns或由getPreDomainValidationInformation返回的auth_email_addresses属性中的有效的邮箱地址。同时,IP地址仅支持http、https两种验证方式
- unique_idstring
未被消费过的订单唯一识别字符串,8-15位字符,英文小写字母和数字组成,此处传入的值应该同之前调用getPreDomainValidationInformation方法时传入的值保持一致。同时,此处调用成功后将会正式消费掉传入的识别字符串
- domainsstring
[多域名证书、IP地址证书、多域通配符证书产品必须提供] 英文逗号隔开的合法的域名列表,总长度不得超过 32767 个字符,IDN域名需要转码为punnyCode格式后提交
HEADER
- Content-Typestring值:application/json
参数
- statusstring
- vendor_idstring
- certificate_idstring
- cert_statusstring
- unique_idstring
- created_atstring
- trustocean_idstring
- csr_codestring
- contact_emailstring
- domainsarray
- 数组成员string
- dcv_infoobject
- 子属性
- dcv_info.each_of_your_domain_name_as_keyobject
- 子属性
- each_of_your_domain_name_as_key.domainstring
- each_of_your_domain_name_as_key.emailsarray
- 数组成员string
- each_of_your_domain_name_as_key.methodstring
- each_of_your_domain_name_as_key.statusstring
- each_of_your_domain_name_as_key.domainmd5hashstring
- each_of_your_domain_name_as_key.isipstring
- each_of_your_domain_name_as_key.subdomainstring
- each_of_your_domain_name_as_key.topdomainstring
- each_of_your_domain_name_as_key.dns_hoststring
- each_of_your_domain_name_as_key.dns_typestring
- each_of_your_domain_name_as_key.dns_valuestring
- each_of_your_domain_name_as_key.http_verifylinkstring
- each_of_your_domain_name_as_key.http_filenamestring
- each_of_your_domain_name_as_key.http_filecontentstring
- each_of_your_domain_name_as_key.https_verifylinkstring
- each_of_your_domain_name_as_key.https_filenamestring
- each_of_your_domain_name_as_key.https_filecontentstring
- each_of_your_domain_name_as_key.emailstring
Example 1
请求
API服务连接成功
1{
2 "status": "<string>",
3 "vendor_id": "<string>",
4 "certificate_id": "<string>",
5 "cert_status": "<string>",
6 "unique_id": "<string>",
7 "created_at": "<string>",
8 "trustocean_id": "<integer>",
9 "csr_code": "<string>",
10 "contact_email": "<string>",
11 "domains": [
12 "<string>",
13 "<string>"
14 ],
15 "dcv_info": {
16 "each_of_your_domain_name_as_key": {
17 "domain": "<string>",
18 "emails": [
19 "<string>",
20 "<string>"
21 ],
22 "method": "<string>",
23 "status": "<string>",
24 "domainmd5hash": "<string>",
25 "isip": "<boolean>",
26 "subdomain": "<string>",
27 "topdomain": "<string>",
28 "dns_host": "<string>",
29 "dns_type": "<string>",
30 "dns_value": "<string>",
31 "http_verifylink": "<string>",
32 "http_filename": "<string>",
33 "http_filecontent": "<string>",
34 "https_verifylink": "<string>",
35 "https_filename": "<string>",
36 "https_filecontent": "<string>",
37 "email": "<string>"
38 }
39 }
40}
吊销 SSL 证书
此接口用于吊销特定的证书订单,此接口仅取消订单并吊销对应的证书或证书副本,无法进行退款。且一旦调用此接口后即无法再次调用退款接口进行退款申请。只有已经签发(状态为:issued_active)的证书订单才可以调用此接口
HEADER
- Content-Typestring值:application/x-www-form-urlencoded
请求 BODY
- usernamestring
您的 API 账户名
- passwordstring
您的 API 密码
- trustocean_idstring
订单号码,必须是由addSSLOrder或reissueSSLOrder返回的订单号码
- revocationReasonstring
吊销原因,1-20个字符,用于简要描述吊销订单的原因
HEADER
- Content-Typestring值:application/json
参数
- statusstring
Example 1
请求
API服务连接成功
1{
2 "status": "<string>"
3}
提交订单退款申请
此接口用于提交订单退款申请,但需要符合退款政策,申请提交后将由TrustOcean后台人员处理。
HEADER
- Content-Typestring值:application/x-www-form-urlencoded
请求 BODY
- usernamestring
您的 API 账户名
- passwordstring
您的 API 密码
- trustocean_idstring
订单号码,必须是由addSSLOrder或reissueSSLOrder返回的订单号码
HEADER
- Content-Typestring值:application/json
参数
- statusstring
Example 1
请求
API服务连接成功
1{
2 "status": "<string>"
3}
获取退款处理状态
此接口用于查询特定订单的退款请求处理状态,只有当订单提交过退款申请后才可以调用此接口
HEADER
- Content-Typestring值:application/x-www-form-urlencoded
请求 BODY
- usernamestring
您的 API 账户名
- passwordstring
您的 API 密码
- trustocean_idstring
订单号码,必须是由addSSLOrder或reissueSSLOrder返回的订单号码
HEADER
- Content-Typestring值:application/json
参数
- statusstring
- refund_atstring
- refund_statusstring
- refund_requested_atstring
Example 1
请求
API服务连接成功
1{
2 "status": "<string>",
3 "refund_at": "<string>",
4 "refund_status": "<string>",
5 "refund_requested_at": "<string>"
6}
检查 unique_id 是否可用
此方法为辅助方法,当您不确定您生成的unique_id是否可用时,您可以调用此方法进行校验。当返回的status值为success时表示可用。您应该创建可靠的算法来生成您的连续的unique_id,而不是依赖此方法生成不规则的unique_id进行使用
HEADER
- Content-Typestring值:application/x-www-form-urlencoded
请求 BODY
- usernamestring
您的 API 账户名
- passwordstring
您的 API 密码
- unique_idstring
您本地生成的,未被消费过的订单唯一识别字符串,8-15位字符,英文小写字母和数字组成,必须是您账户的
apiSalt
作为字符串开头
HEADER
- Content-Typestring值:application/json
参数
- statusstring
Example 1
请求
API服务连接成功
1{
2 "status": "<string>"
3}
获取产品和价格信息(兼容方法) - 1
兼容方法,调用此方法可获取到适用您账户的所有产品列表,同时包含了证书产品的配置属性,同时包含价格信息。
HEADER
- Content-Typestring值:application/x-www-form-urlencoded
请求 BODY
- usernamestring
您的 API 账户名
- passwordstring
您的 API 密码
HEADER
- Content-Typestring值:application/json
参数
- statusstring
- productsarray
- 数组成员object
- products.pidstring
- products.namestring
- products.chineseNamestring
- products.classstring
- products.multidomainstring
- products.wildcardstring
- products.ipv4string
- products.brandstring
- products.sealstring
- products.scorestring
- products.periodsarray
- 数组成员string
- products.pricingobject
- 子属性
- pricing.baseobject
- 子属性
- base.Monthlystring
- base.Quarterlystring
- base.Annuallystring
- base.Bienniallystring
- base.Trienniallystring
- base.Quadrennialstring
- base.Quinquennialstring
- pricing.sanobject
- 子属性
- san.Monthlystring
- san.Quarterlystring
- san.Annuallystring
- san.Bienniallystring
- san.Trienniallystring
- san.Quadrennialstring
- san.Quinquennialstring
Example 1
请求
API服务连接成功
1{
2 "status": "<string>",
3 "products": [
4 {
5 "pid": "<integer>",
6 "name": "<string>",
7 "chineseName": "<string>",
8 "class": "<string>",
9 "multidomain": "<string>",
10 "wildcard": "<string>",
11 "ipv4": "<string>",
12 "brand": "<string>",
13 "seal": "<string>",
14 "score": "<string>",
15 "periods": [
16 "<string>",
17 "<string>"
18 ],
19 "pricing": {
20 "base": {
21 "Monthly": "<string>",
22 "Quarterly": "<string>",
23 "Annually": "<string>",
24 "Biennially": "<string>",
25 "Triennially": "<string>",
26 "Quadrennial": "<string>",
27 "Quinquennial": "<string>"
28 },
29 "san": {
30 "Monthly": "<string>",
31 "Quarterly": "<string>",
32 "Annually": "<string>",
33 "Biennially": "<string>",
34 "Triennially": "<string>",
35 "Quadrennial": "<string>",
36 "Quinquennial": "<string>"
37 }
38 }
39 },
40 {
41 "pid": "<integer>",
42 "name": "<string>",
43 "chineseName": "<string>",
44 "class": "<string>",
45 "multidomain": "<string>",
46 "wildcard": "<string>",
47 "ipv4": "<string>",
48 "brand": "<string>",
49 "seal": "<string>",
50 "score": "<string>",
51 "periods": [
52 "<string>",
53 "<string>"
54 ],
55 "pricing": {
56 "base": {
57 "Monthly": "<string>",
58 "Quarterly": "<string>",
59 "Annually": "<string>",
60 "Biennially": "<string>",
61 "Triennially": "<string>",
62 "Quadrennial": "<string>",
63 "Quinquennial": "<string>"
64 },
65 "san": {
66 "Monthly": "<string>",
67 "Quarterly": "<string>",
68 "Annually": "<string>",
69 "Biennially": "<string>",
70 "Triennially": "<string>",
71 "Quadrennial": "<string>",
72 "Quinquennial": "<string>"
73 }
74 }
75 }
76 ]
77}
获取产品和价格信息(兼容方法) - 2
兼容方法,调用此方法可获取到适用您账户的所有产品列表,同时包含了证书产品的配置属性,同时包含价格信息。
HEADER
- Content-Typestring值:application/x-www-form-urlencoded
请求 BODY
- usernamestring
您的 API 账户名
- passwordstring
您的 API 密码
HEADER
- Content-Typestring值:application/json
参数
- statusstring
- productsarray
- 数组成员object
- products.pidstring
- products.namestring
- products.chineseNamestring
- products.classstring
- products.multidomainstring
- products.wildcardstring
- products.ipv4string
- products.brandstring
- products.sealstring
- products.scorestring
- products.periodsarray
- 数组成员string
- products.pricingobject
- 子属性
- pricing.baseobject
- 子属性
- base.Monthlystring
- base.Quarterlystring
- base.Annuallystring
- base.Bienniallystring
- base.Trienniallystring
- base.Quadrennialstring
- base.Quinquennialstring
- pricing.sanobject
- 子属性
- san.Monthlystring
- san.Quarterlystring
- san.Annuallystring
- san.Bienniallystring
- san.Trienniallystring
- san.Quadrennialstring
- san.Quinquennialstring
Example 1
请求
API服务连接成功
1{
2 "status": "<string>",
3 "products": [
4 {
5 "pid": "<integer>",
6 "name": "<string>",
7 "chineseName": "<string>",
8 "class": "<string>",
9 "multidomain": "<string>",
10 "wildcard": "<string>",
11 "ipv4": "<string>",
12 "brand": "<string>",
13 "seal": "<string>",
14 "score": "<string>",
15 "periods": [
16 "<string>",
17 "<string>"
18 ],
19 "pricing": {
20 "base": {
21 "Monthly": "<string>",
22 "Quarterly": "<string>",
23 "Annually": "<string>",
24 "Biennially": "<string>",
25 "Triennially": "<string>",
26 "Quadrennial": "<string>",
27 "Quinquennial": "<string>"
28 },
29 "san": {
30 "Monthly": "<string>",
31 "Quarterly": "<string>",
32 "Annually": "<string>",
33 "Biennially": "<string>",
34 "Triennially": "<string>",
35 "Quadrennial": "<string>",
36 "Quinquennial": "<string>"
37 }
38 }
39 },
40 {
41 "pid": "<integer>",
42 "name": "<string>",
43 "chineseName": "<string>",
44 "class": "<string>",
45 "multidomain": "<string>",
46 "wildcard": "<string>",
47 "ipv4": "<string>",
48 "brand": "<string>",
49 "seal": "<string>",
50 "score": "<string>",
51 "periods": [
52 "<string>",
53 "<string>"
54 ],
55 "pricing": {
56 "base": {
57 "Monthly": "<string>",
58 "Quarterly": "<string>",
59 "Annually": "<string>",
60 "Biennially": "<string>",
61 "Triennially": "<string>",
62 "Quadrennial": "<string>",
63 "Quinquennial": "<string>"
64 },
65 "san": {
66 "Monthly": "<string>",
67 "Quarterly": "<string>",
68 "Annually": "<string>",
69 "Biennially": "<string>",
70 "Triennially": "<string>",
71 "Quadrennial": "<string>",
72 "Quinquennial": "<string>"
73 }
74 }
75 }
76 ]
77}