API调用 · ThinkAPI 统一API调用服务

## `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`讨论。