README

This SDK provides a simplified access to the API of Nuvem Shop / Tienda Nube.

Installation

This SDK is mounted on top of Requests for PHP, so we recommend using Composer for installing.

Simply add the tiendanube/php-sdk requirement to composer.json.

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

Then run composer install or composer update to complete the installation.

If you need an autoloader, you can use the one provided by Composer:

require 'vendor/autoload.php';

Authenticating Your App

When a user installs your app, he will be taken to your specified Redirect URI with a parameter called code containing your temporary authorization code.

With this code you can request a permanent access token.

$code = $_GET['code'];

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

The returned value will contain the id of the authenticated store, as well as the access token and the authorized scopes.

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)

Keep in mind that future visits to your app will not go through the Redirect URI, so you should store the store id in a session.

However, if you need to authenticate a user that has already installed your app (or invite them to install it), you can redirect them to login to the Tienda Nube/Nuvem Shop site.

$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

After the user has logged in, he will be taken to your specified Redirect URI with a new authorization code. You can use this code to request a new request token.

Making a Request

The first step is to instantiate the API class with a store id and an access token, as well as a user agent to identify your app. Then you can use the get, post, put and delete methods.

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

You can access the headers of the response via $response->headers as if it were an array:

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

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

For convenience, the X-Main-Language header can be obtained from $response->main_language:

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

Other examples:

//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,
]);

For list results you can use the next, prev, first and last methods to retrieve the corresponding page as a new response object.

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

Exceptions

Calls to Auth may throw a 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)
}

Likewise, calls to API may throw a Tiendanube\API\Exception. You can retrieve the original response from these exceptions:

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)
}

Requests that return 404 will throw a subclass called Tiendanube\API\NotFoundException.