>[danger]### 在官方不久前宣布提供统一API接口服务之后，`SDK`接口现在也已经正式发布了`1.0`版本。 ## `ThinkAPI`服务介绍 开发者经常为了各种功能而四处寻找是否有相应的API接口，即便找到了可能还要忍受第三方各种奇葩的SDK调用，或者不支持`composer`安装。 >[danger]### `ThinkAPI`统一`API`接口服务是由官方联合合作伙伴封装的一套接口调用服务及`SDK`，旨在帮助`ThinkPHP`开发者更方便的调用官方及第三方的提供的各类`API`接口及服务，从而更好的构建开发者生态。 ### 一站式接口服务 `ThinkAPI`提供了一站式的接口服务，从接口购买、调用到SDK封装都只需要一个官方账号即可完成，无需注册各种接口服务账号，除了涵盖常用`API`服务之外，还设计了可转换接口服务更好的保障接口的稳定性，让你省心省力。 ### 提供统一的`SDK` 官方提供了一套统一的`SDK for PHP`调用服务，通过`composer`安装一个轻量级的依赖包即可调用，采用简洁和现代化的调用方式，并且对IDE友好，可以简化你的`API`调用开发工作。 ### 官方服务市场保障 `ThinkAPI`所有支持的接口都纳入[官方服务市场](https://www.thinkphp.cn/partner/78)，包括免费接口和付费接口，市场服务有保障，并且有购买记录以及统计数据。 对于一些付费的接口，官方的[服务市场](https://www.thinkphp.cn/partner/78)提供了更优惠的价格。 ## `ThinkAPI`调用流程 请务必按照如下流程进行`ThinkAPI`接口服务调用： * 第一步：注册[服务市场账号](https://market.topthink.com/auth/login)获取个人`AppCode`； * 第二步：购买[接口服务（次数）](https://market.topthink.com/partner/78)，免费接口则跳过； * 第三步：通过接口地址（及参数）或者`SDK`调用接口服务返回数据； ## 身份认证（AppCode） 无论是免费还是付费接口，都需要通过`AppCode`授权后才能进行接口请求。`AppCode`的值可以在官方服务市场`->`个人中心`->`[API管理](https://market.topthink.com/setting/api)的上方查询到，每个用户账号拥有一个唯一的`AppCode`值（请不要随意泄露）。  可以使用两种方法进行身份认证： ### 第一种：`Header`信息认证（推荐） 在请求`Header`中添加的`Authorization`字段，配置值为“AppCode ＋ 半角空格 ＋AppCode值”。 格式如下： ~~~ Authorization:AppCode AppCode值 ~~~ ### 第二种：请求参数认证 请求Query中添加的`appCode`参数，参数的值为用户`AppCode`的值。 ~~~ https://API接口地址?appCode=AppCode值 ~~~ ## 原生`API`调用 `ThinkAPI`所有支持的接口服务都有一个唯一的接口调用地址，这个接口地址统一使用`https://api.topthink.com` 作为接口网址，例如身份证查询接口的请求地址是： ``` https://api.topthink.com/idcard/index ``` 你可以通过下面的请求来调用接口 ``` https://api.topthink.com/idcard/index?appCode=AppCode值&cardno=要查询的身份证号码 ``` 你可以在注册市场账号后测试下这个免费接口，查看具体的返回数据。 >[danger]注意：部分接口可能采用不同的请求类型，不一定是`GET`请求，具体的接口参数请参考具体的API文档，会有详细的说明。 ### 返回数据格式 所有的`api`接口返回数据规范如下： | 名称 | 类型 | 说明 | | --- | --- | --- | | code | int | 返回码,0 表示成功 其它表示失败 | | message | string | 返回提示信息 | | data | object | 返回数据 | >[danger] 当`code`为0的时候计费，其中`data`包含的数据和具体的接口有关。 ## 使用`SDK`调用 除了使用原生的方式调用接口外，`ThinkAPI`还提供了一套通用的`SDK`接口规范，让你用更简洁和现代化的方式调用接口服务。使用方法如下： 首先需要在你的项目里面安装`think-api`库 ~~~ composer require topthink/think-api ~~~ > 建议设置使用[阿里云 Composer 全量镜像](https://developer.aliyun.com/composer) 然后就可以调用你需要的接口进行查询和返回数据，还是以上面的查询身份证所属地区接口为例说明： ~~~ use think\api\Client; // API调用之前必须设置`AppCode`值，用于接口调用的身份认证 $client = new Client("YourAppCode"); // 调用某个接口方法和传入参数 $result = $client->idcardIndex() ->withCardno('身份证号码') ->request(); var_dump($result); ~~~ 所有的接口服务和方法都支持IDE自动提示和完成（请务必注意方法大小写必须保持一致 确保参数名的正确性），基本上不需要文档即可完成接口开发工作。 上面是免费接口的SDK调用示例，付费接口的调用方式是完全一样的，区别在于付费接口你必须要先在市场购买接口次数才能正常调用（`ThinkAPI`服务的接口必须在[官方市场](https://market.topthink.com/partner/78)购买才有效，第三方购买的接口是不支持调用的），而免费接口则有每天不超过100次请求的限制。 下面是身份证实名认证的付费接口调用示例： ``` $client = new Client("YourAppCode"); $result = $client->idcardQuery() ->withIdcard('身份证号码') ->withRealname('姓名') ->request(); var_dump($result); ``` > 注意，该SDK服务仅支持官方已经接入的API接口，目前接口数量正在扩充中，你可以联系我们反馈你需要的API接口，我们来统一进行接入。 ## 成为`API`供应商 面向服务开发将是将来的一大开发趋势，如果你计划在100万+的ThinkPHP开发者中推广你们的服务，欢迎联系！诚邀合作伙伴（包括但不限于API服务商或对外提供开放API的产品服务商）加入官方统一API接口服务计划。 ## 联系我们 成为API供应商或者反馈你需要的API接口请联系微信`topthink`（注明来意）。