API调用
最后更新于：2022-04-02 08:16:10
## `API`调用
市场的每个`API`接口都会有一个接口调用地址（包括请求参数），因此你可以通过传统`curl`的方式来调用接口，如果需要调试接口推荐使用`postman`。不过更推荐使用我们封装的SDK接口进行调用（目前仅提供了`SDK for PHP` 更多语言的SDK陆续开放），无需再进行繁琐的封装。
>[info] `ThinkAPI`提供了一套通用的SDK接口规范，让你用更为简洁和现代化的方式调用接口服务。
首先需要在你的项目里面安装`think-api`库（适用于任何PHP`5.6+`项目，**对框架没有任何要求**）。
```
composer require topthink/think-api
```
> 一些用户可能由于网络问题无法安装，可以使用[阿里云 Composer 全量镜像](https://developer.aliyun.com/composer)。
>[danger] 如果因为PHP版本过低或者需要用到非PHP语言项目，则建议直接调用原生接口地址（每个具体接口的文档页面都有接口的请求调用地址），PHP语言之外的SDK会陆续支持。
然后就可以调用你需要的接口进行查询和返回数据，以查询身份证所属地区接口为例
~~~
use think\api\Client;
$client = new Client("YourAppCode");
$result = $client->idcardIndex()
->withCardno('身份证号码')
->request();
~~~
>[danger] 官方的SDK一直在保持更新，如果在调用接口方法的时候提示某个接口不存在，可以尝试更新SDK后再测试。
```
composer update topthink/think-api
```
如需多次调用的话，建议自己在项目里面封装一个助手函数，例如：
```
use think\api\Client;
/**
* API接口调用助手函数
* @return Client
*/
function api(): Client
{
return new Client('yourAppCode');
}
// 调用示例
$result = api()->idcardIndex()
->withCardno('身份证号码')
->request();
```
所有的接口服务和方法都支持IDE自动提示和完成（请务必注意方法大小写必须保持一致），基本上不需要文档即可完成接口开发工作，`ThinkAPI`所有的API调用服务必须设置`appCode`值，用于接口调用的身份认证。
>[info] `AppCode`的值可以在官方服务市场“我的服务-->[安全信息](https://market.topthink.com/my/security)”的上方查询到，每个用户账号拥有一个唯一的`AppCode`值（请不要随意泄露）。如果你的`AppCode`由于某种原因已经泄露给第三方，建议**设置IP白名单**。
>[danger] 注意，该SDK服务仅支持官方已经接入的API接口，目前接口数量正在扩充中，你可以联系我们反馈你需要的API接口，我们来统一进行接入。
## 接口参数
`ThinkAPI`接口的参数包括系统级参数和应用级参数，所有的应用参数都统一使用**驼峰命名**（首字母小写）规范。无论是付费接口还是免费接口，都必须传入身份认证的系统传参（参考下面）。
如果是通过SDK方式调用接口的话，参数都是通过方法的方式调用，无需额外传参。如果不是特殊说明，`ThinkAPI`的接口默认都支持`GET`/`POST`请求。
## 身份认证（AppCode）
如果你不是基于SDK进行调用而是自己调用接口地址的话，需要进行身份认证，目前支持使用两种方式进行身份认证：
### 第一种：通过`Header`信息认证
在请求`Header`中添加的`Authorization`字段，配置值为“AppCode ＋ 半角空格 ＋AppCode值”。
格式如下：
~~~plaintext
Authorization:AppCode AppCode值
~~~
### 第二种：通过请求参数认证
`ThinkAPI`的接口均支持`GET`和`POST`请求调用，你需要在请求Query中添加`appCode`参数，参数的值为用户`AppCode`的值。
~~~plaintext
https://API接口地址?appCode=AppCode值
~~~
>[danger] 不一定是GET方式，POST参数一样可以支持
## 返回数据
`ThinkAPI`所有的接口返回数据为`JSON`格式，通用规范如下：
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| code | int | 返回码,0 表示成功 其它表示失败 |
| message| string | 返回提示信息 |
| data| object | 返回数据 |
> 如果为付费接口，则当`code`为0的时候计费，其中`data`包含的数据请参考具体的接口说明。
## 接口预警
如果是付费接口，支持设置剩余调用次数预警。当到达设置的预警阈值的时候，会发送短信和邮件预警通知。注意及时续费，避免影响业务正常运行。
## 技术支持
如果在使用`ThinkAPI`的过程中有任何问题，可以加官方QQ交流群`375558052`讨论。
';