README

此 SDK 为 Nuvem Shop / Tienda Nube 的 API 提供简化访问。

安装

此 SDK 基于 Requests for PHP 构建，因此我们建议使用 Composer 进行安装。

只需将 ceresaconsultoria/sdk-php-nuvemshop 依赖项添加到 composer.json 中。

{
    "require": {
        "ceresaconsultoria/sdk-php-nuvemshop": ">=1.0"
    }
}

然后运行 composer install 或 composer update 以完成安装。

如果您需要自动加载器，可以使用 Composer 提供的自动加载器。

require 'vendor/autoload.php';

认证您的应用

当用户安装您的应用时，他们将被带到指定的重定向 URI，并带有名为 code 的参数，其中包含您的临时授权码。

使用此代码，您可以请求永久访问令牌。

$code = $_GET['code'];

$auth = new TiendaNube\Auth(CLIENT_ID, CLIENT_SECRET);
$store_info = $auth->request_access_token($code);

返回值将包含认证商店的 id、访问令牌和授权作用域。

var_dump($store_info);
//array (size=3)
//  'store_id' => string '1234' (length=4)
//  'access_token' => string 'a2b544066ee78926bd0dfc8d7bd784e2e016b422' (length=40)
//  'scope' => string 'read_products,read_orders,read_customers' (length=40)

请注意，将来访问您的应用将不会通过重定向 URI 进行，因此您应在会话中存储商店 id。

但是，如果您需要认证已安装您的应用的用户（或邀请他们安装），您可以让他们重定向到 Tienda Nube/Nuvem Shop 网站进行登录。

$auth = new TiendaNube\Auth(CLIENT_ID, CLIENT_SECRET);

//You can use one of these to obtain a url to login to your app
$url = $auth->login_url_brazil();
$url = $auth->login_url_spanish();

//Redirect to $url

用户登录后，他们将被带到指定的重定向 URI，并带有新的授权码。您可以使用此代码请求新的请求令牌。

发送请求

第一步是使用商店 id、访问令牌以及用于识别应用的 用户代理 实例化 API 类。然后您可以使用 get、post、put 和 delete 方法。

$api = new TiendaNube\API(STORE_ID, ACCESS_TOKEN, 'Awesome App (contact@awesome.com)');
$response = $api->get("products");
var_dump($response->body);

您可以通过 $response->headers 作为数组访问响应头

var_dump(isset($response->headers['X-Total-Count']));
//boolean true

var_dump($response->headers['X-Total-Count']);
//string '48' (length=2)

方便起见，可以从 $response->main_language 获取 X-Main-Language 头

$response = $api->get("products/123456");
$language = $response->main_language;
var_dump($response->body->name->$language);

其他示例

//Create a product
$response = $api->post("products", [
    'name' => 'Tienda Nube',
]);
$product_id = $response->body->id;

//Change its name
$response = $api->put("products/$product_id", [
    'name' => 'Nuvem Shop',
]);

//And delete it
$response = $api->delete("products/$product_id");

//You can also send arguments to GET requests
$response = $api->get("orders", [
    'since_id' => 10000,
]);

对于列表结果，您可以使用 next、prev、first 和 last 方法检索相应的页面作为新的响应对象。

$response = $api->get('products');
while($response != null){
    foreach($response->body as $product){
        var_dump($product->id);
    }
    $response = $response->next();
}

异常

对 Auth 的调用可能抛出 Tiendanube\Auth\Exception

try{
    $auth->request_access_token($code);
} catch(Tiendanube\Auth\Exception $e){
    var_dump($e->getMessage());
    //string '[invalid_grant] The authorization code has expired' (length=50)
}

同样，对 API 的调用可能抛出 Tiendanube\API\Exception。您可以从这些异常中检索原始响应

try{
    $api->get('products');
} catch(Tiendanube\API\Exception $e){
    var_dump($e->getMessage());
    //string 'Returned with status code 401: Invalid access token' (length=43)
    
    var_dump($e->response->body);
    //object(stdClass)[165]
    //  public 'code' => int 401
    //  public 'message' => string 'Unauthorized' (length=12)
    //  public 'description' => string 'Invalid access token' (length=20)
}

返回 404 的请求将抛出名为 Tiendanube\API\NotFoundException 的子类。