>[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`（注明來意）。