README

1. Introduction

This SDK offers user many instruments needed to interact with our API in safe and convenient manner. Below is some basic explanation what this SDK is capable of:

validation of input parameters individually for each API method.
throwing of Exceptions with detailed information during all stages of processing
convenient pagination instruments, utilizing Iterator Interface and its methods.
documented functions, and links to API documentation for all methods.
integrated capability to work with API`s limits. User has possibility to set rules for waiting and repeating API calls.
integrated validation of API response, ability to get the response in the form of array or JSON string,
ability to get response`s detailed service information
PSR4-compatible realization
ability to include library using Composer, or php`s include command (proprietary autoloader is provided)

2. Getting Started

Requirements

PHP >= 7.2

cURL library - https://www.php.net/manual/en/curl.requirements.php

JSON library () - if you are using PHP version 8 or higher you don't need to install JSON module, as it is included in PHP by default. https://www.php.net/manual/en/json.installation.php check below for example of basic composer.json file configuration.

You have to be registered Priceva user with valid API key in order to use this SDK.

3. Installing

Using Composer

in the CLI, from your project root directory run the following command:

php composer require priceva/priceva-api-sdk-php

Alternatively, you can add this string in require section of your composer.json:

"priceva/priceva-api-sdk-php": "dev-master"

so that your composer.json will look like this:

{
  "require": {
    "ext-json": "*",
    "ext-curl": "*",
    "php": ">=7.2",
    "priceva/priceva-api-sdk-php": "dev-main"
  },
  "require-dev": {
    "phpunit/php-code-coverage": "9.2.29",
    "phpunit/phpunit": "9.5"
  }
}

and run composer install.

Without the Composer

Download our library at https://github.com/priceva/priceva-api-sdk-php
Include files in your php root file, and then call a register() function:

include_once __DIR__ .'/path/to/file/priceva-api-sdk-php/PricevaAutoload.php';
PricevaAutoload::register();

4. Examples of usage:

Basic usage example #1 (ping Priceva API):

use Priceva\APISDK\PricevaApiConnector;
use Priceva\APISDK\CommonRequestProvider;
use Priceva\APISDK\Exception\PricevaException;

//get your API key from app.priceva.com
$apikey  = 'xxxxxxxxx';
$apiconn = new PricevaApiConnector($apikey);

try {
    // use RequestProvider to get the needed API object and method
    $ping_request = CommonRequestProvider::main()::ping();
    // call() method performs all checks and executes an API call
    $response = $apiconn->call($ping_request);
    if ( $response->is_success() ) {
        echo "Success";
    }
} catch ( PricevaException $e ) {
    // error handler here
}

Basic usage example #2 (requesting list of products with specific filters)

use Priceva\APISDK\PricevaApiConnector;
use Priceva\APISDK\PriceMonitoringRequestProvider;
use Priceva\APISDK\Exception\PricevaException;

$apikey = 'xxxxxxxxx'; 
$apiconn = new PricevaApiConnector($apikey);

try {
    $request = PriceMonitoringRequestProvider::product()::list();
    // add your request parameters as an array
    // see a list of VALID_PARAMS in corresponding Request object.
    $request->set_params_array([
                               'filters' => [
                                   'limit' => 10,
                                   'page'  => 3,
                                   'name'  => 'Yamaha',
                               ],
                               'sources' => [
                                   'add' => true,
                               ],
                           ]);
    
    // or you can add each parameter individually, using each object`s specific methods. 
    $request->filters_category_id_set([ '2', '1', '0', 'u' ]);
    $request->filters_brand_id_set([ 'b', 'c' ]);

    $result = $apiconn->call($request);
    
} catch ( PricevaException $e ) {
    // error handler
}

Basic pagination usage example #3 (requesting list of products page by page):

for additional info see https://priceva.docs.apiary.io/#introduction/pagination

use Priceva\APISDK\PricevaApiConnector;
use Priceva\APISDK\PriceMonitoringRequestProvider;
use Priceva\APISDK\Exception\PricevaException;
use Priceva\APISDK\Lib\RequestIteratorAggregate; 

$apikey = 'xxxxxxxxx'; 
$apiconn = new PricevaApiConnector($apikey);

try {
    $request = PriceMonitoringRequestProvider::product()::list();
    // add your request parameters as an array
    $request->set_params_array([
                                   'filters' => [
                                       'limit' => 50,
                                       'name'  => 'Fender',
                                   ],
                               ]);
    
    $iterated_request = new RequestIteratorAggregate($request, $apiconn);
    foreach ( $iterated_request as $page ) {
        ...
    };
} catch ( PricevaException $e ) {
    // error handler
}

basic working with limits example #4:

for additional info see https://priceva.docs.apiary.io/#introduction/limits

use Priceva\APISDK\PricevaApiConnector;
use Priceva\APISDK\PriceMonitoringRequestProvider;
use Priceva\APISDK\Exception\PricevaException;
use Priceva\APISDK\Lib\ApiCallRepeatsSettings;

$apikey = 'xxxxxxxxx'; 
/**
 * with ApiCallRepeatsSettings it is possible to set maximum amount of time for which a call can be delayed,
 * total time that can be spent waiting for API calls to be repeated,
 * and maximum number of repeated API calls that can be made.
 * Also, there are individual methods for each parameter, 
 * set_max_call_delay_time(), set_max_repeats() and set_max_total_wait_time()
 */
 
$repeat_settings = new ApiCallRepeatsSettings(20, 10, 2);
$apiconn = new PricevaApiConnector($apikey, $repeat_settings); 

try {
    $request = PriceMonitoringRequestProvider::product()::list();
    $list    = $apiconn->call($request);
} catch ( PricevaException $e ) {
    // error handler
}

5. File structure and classes

RequestProviders

Priceva SDK consists of three RequestProvider objects:

PriceMonitoringRequestProvider, contains objects for campaign types: "Competitor price monitoring for online stores" and "Price level monitoring (MAP) for brands and manufacturers"
AssortmentRequestProvider, contains objects for Digital Shelf Analytics campaigns.
CommonRequestProvider, contains objects for API general availability checks and testing.

Each request provider has methods that return corresponding object, which in turn contains specific objects`s methods. For example, PriceMonitoringRequestProvider contains tag() method, which in turn returns Tag object, which in turn contains list(), create(), update(), delete() methods, which return specific Request object. See part 4 (Examples of usage) for detailed syntax.

Request class

Each Request contains API_OBJECT field (e.g.tag) and 'API_METHOD' field (e.g. update), so basically a call will be made to https://api.priceva.com/api/v1/tag/update. All Request objects contain 'VALID_PARAMS' field, a tree of parameters that can be set for this specific API object and method. Before making an actual API call, these parameters are checked for any potential errors (self_check() method), these errors (if any occur) are collected to a list of errors, and an Exception with detailed errors information is thrown. If no error occurs, API proceeds with normal API call procedure.

PricevaApiConnector

PricevaApiConnector is a class that executes a call to Priceva API. PricevaApiConnector takes API key (string) as required parameter, and ApiCallRepeatsSettings(explained below) object as optional parameter. A Request object must be provided as an argument for PricevaApiConnector`s call() method. After a call is executed, if call is successful, the Response object (explained below) is returned.

Response

Response is an object that is produced by PricevaApiConnector after an API call is executed. Beside the 'result' field, which self-explanatory, contains the results of API call, response also contains detailed info on executed call, such as:

time of execution,
timestamp on API machine, 'api_timestamp' field,
date on API machine,
timestamp on local machine,
warnings array and number of warnings,
errors array and number of errors,
current page and total number of pages,
'has_errors' flag, if any errors occurred,
'raw_json_output', that contains original JSON string received from Priceva API.

For all these fields there are getter methods in Response object, so all these fields can be accessed if needed.

ApiCallRepeatsSettings

In order to restrain the frequency and overuse of Priceva API, the API has some limits. Basically this is amount of calls that can be made in the set time period. See https://priceva.docs.apiary.io/#introduction/limits for more detailed info on Priceva API limits.

When API limits are reached, next API call time is returned is Response`s errors field. This is where ApiCallRepeatsSettings come to action. This SDK allows to delay a call until a next_call_time is reached, and then execute a call.

ApiCallRepeatsSettings allows to set maximum amount of time for which a call can be delayed, total time that can be spent waiting for API calls to be repeated, and maximum number of repeated API calls that can be made. These settings can be given as arguments upon class creation, and also there are individual methods for setting each parameter: set_max_call_delay_time(), set_max_repeats() and set_max_total_wait_time().

In order to make use of ApiCallRepeatsSettings, PricevaApiConnector takes this object as a second (optional) parameter upon its initialization (first being api_key string). See an example of usage in section #4.

RequestIterator.

In order to get multiple pages of objects from Priceva API in one operation, this SDK provides pagination tools. RequestIteratorAggregate is an external iterator for RequestIterator, used to iterate over Request and Response objects. It takes Request object, PricevaApiConnector object as required arguments, and as an optional parameter number of page to start iterations from ($iterator_start_page). Iteration is best used in conjunction with ApiCallRepeatsSettings, as it makes possible to execute more API requests in a single operation than otherwise could be possible.

See example in section #4 to see how to make use of RequestIterator.

priceva / priceva-api-sdk-php

Maintainers

Details