## `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`討論。