tiendanube / php-sdk
A PHP SDK for the Tienda Nube/Nuvem Shop API.
Installs: 49 803
Dependents: 1
Suggesters: 0
Security: 0
Stars: 8
Watchers: 170
Forks: 14
Open Issues: 6
Requires
- rmccue/requests: >=1.0
This package is not auto-updated.
Last update: 2024-10-26 15:34:16 UTC
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
.