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