2017 © Pedro Peláez
 

library api-client-php

PHP client for retailCRM API

image

retailcrm/api-client-php

PHP client for retailCRM API

  • Tuesday, March 20, 2018
  • by muxx
  • Repository
  • 16 Watchers
  • 24 Stars
  • 27,683 Installations
  • PHP
  • 2 Dependents
  • 0 Suggesters
  • 21 Forks
  • 0 Open issues
  • 37 Versions
  • 10 % Grown

The README.md

Build Status Coverage Latest stable PHP from Packagist, (*1)

RetailCRM API PHP client

This is the PHP RetailCRM API client. This library allows using of the actual API version.
You can find more info in the documentation., (*2)

Table of contents

Requirements

  • PHP 7.3 and above
  • PHP's cURL support
  • PHP's JSON support
  • Any HTTP client compatible with PSR-18 (covered by the installation instructions).
  • Any HTTP factories implementation compatible with PSR-17 (covered by the installation instructions).
  • Any HTTP messages implementation compatible with PSR-7 (covered by the installation instructions).
  • Other dependencies listed in the composer.json (covered by the installation instructions)

Installation

Follow those steps to install the library:, (*3)

  1. Download and install Composer package manager.
  2. Install the library from the Packagist by executing this command:
composer require retailcrm/api-client-php:"~6.0"

During the installation, you'll see a message which will look like this:, (*4)

The following packages have new compilation tasks:
 - retailcrm/api-client-php has 1 task

Allow these packages to compile? ([y]es, [a]lways, [n]o, [l]ist, [h]elp)

That's because the Client uses code generation to speed up serialization and deserialization of models in production. This code should be generated during installation or update. Without that code, the library itself will not work at all., (*5)

Just type y here and press Enter. The DTO cache will be generated after that., (*6)

If you skipped the compilation task - don't worry, it can be executed manually at any time with this command:, (*7)

composer compile --all
  1. Optional. Disable compilation prompt that you have seen in the previous step. Run this command to do that:
./vendor/bin/retailcrm-client compiler:prompt

Replace vendor/bin with your bin directory path if it's different from the default. You can find more information about this step in the documentation., (*8)

Note: You should not skip this step if your application is using CI/CD pipeline because the interactive terminal is not available in that environment which will result in failure during the dependencies installation., (*9)

  1. Include the autoloader if it's not included, or you didn't use Composer before.
require 'path/to/vendor/autoload.php';

Replace path/to/vendor/autoload.php with the correct path to Composer's autoload.php., (*10)

Note: API client uses php-http/curl-client and nyholm/psr7 as a PSR-18, PSR-17 and PSR-7 implementation. You can replace those implementations during installation by installing this library with the implementation of your choice, like this:, (*11)

composer require symfony/http-client guzzlehttp/psr7 retailcrm/api-client-php:"~6.0"

More information about that can be found in the documentation., (*12)

Usage

Firstly, you should initialize the Client. The easiest way to do this is to use the SimpleClientFactory:, (*13)

$client = \RetailCrm\Api\Factory\SimpleClientFactory::createClient('https://test.retailcrm.pro', 'apiKey');

The client is separated into several resource groups, all of which are accessible through the Client's public properties. You can call API methods from those groups like this:, (*14)

$client->api->credentials();

For example, you can retrieve the customers list:, (*15)

$client = \RetailCrm\Api\Factory\SimpleClientFactory::createClient('https://test.retailcrm.pro', 'apiKey');
$response = $client->customers->list();

Or the orders list:, (*16)

$client = \RetailCrm\Api\Factory\SimpleClientFactory::createClient('https://test.retailcrm.pro', 'apiKey');
$response = $client->orders->list();

To handle errors you must use two types of exceptions: * RetailCrm\Api\Interfaces\ClientExceptionInterface for the network or other runtime errors. * RetailCrm\Api\Interfaces\ApiExceptionInterface for the errors from the API., (*17)

An example of error handling can be found in the next section of this document., (*18)

Each resource group is responsible for the corresponding API section. For example, costs resource group provide methods for costs manipulation and loyalty resource group allows interacting with loyalty programs, accounts, bonuses, etc., (*19)

Use annotations to determine which DTOs you need for sending the requests. If annotations are not provided by your IDE - you probably should configure them. It'll ease your work with this (and any other) library a lot., (*20)

More information about the usage including examples can be found in the documentation., (*21)

Examples

Listing orders:, (*22)

<?php

use RetailCrm\Api\Interfaces\ClientExceptionInterface;
use RetailCrm\Api\Factory\SimpleClientFactory;
use RetailCrm\Api\Interfaces\ApiExceptionInterface;
use RetailCrm\Api\Model\Entity\CustomersCorporate\CustomerCorporate;

$client = SimpleClientFactory::createClient('https://test.retailcrm.pro', 'apiKey');

try {
    $response = $client->orders->list();
} catch (ApiExceptionInterface | ClientExceptionInterface $exception) {
    echo $exception; // Every ApiExceptionInterface and ClientExceptionInterface instance implements __toString() method.
    exit(-1);
}

foreach ($response->orders as $order) {
    printf("Order ID: %d\n", $order->id);
    printf("First name: %s\n", $order->firstName);
    printf("Last name: %s\n", $order->lastName);
    printf("Patronymic: %s\n", $order->patronymic);
    printf("Phone #1: %s\n", $order->phone);
    printf("Phone #2: %s\n", $order->additionalPhone);
    printf("E-Mail: %s\n", $order->email);

    if ($order->customer instanceof CustomerCorporate) {
        echo "Customer type: corporate\n";
    } else {
        echo "Customer type: individual\n";
    }

    foreach ($order->items as $item) {
        echo PHP_EOL;

        printf("Product name: %s\n", $item->productName);
        printf("Quantity: %d\n", $item->quantity);
        printf("Initial price: %f\n", $item->initialPrice);
    }

    echo PHP_EOL;

    printf("Discount: %f\n", $order->discountManualAmount);
    printf("Total: %f\n", $order->totalSumm);

    echo PHP_EOL;
}

Fetching a specific order by it's ID:, (*23)

<?php

use RetailCrm\Api\Interfaces\ClientExceptionInterface;
use RetailCrm\Api\Interfaces\ApiExceptionInterface;
use RetailCrm\Api\Enum\ByIdentifier;
use RetailCrm\Api\Factory\SimpleClientFactory;
use RetailCrm\Api\Model\Request\BySiteRequest;

$client = SimpleClientFactory::createClient('https://test.retailcrm.pro', 'apiKey');

try {
    $response = $client->orders->get(1234, new BySiteRequest(ByIdentifier::ID, 'site'));
} catch (ApiExceptionInterface | ClientExceptionInterface $exception) {
    echo $exception; // Every ApiExceptionInterface instance should implement __toString() method.
    exit(-1);
}

echo 'Order: ' . print_r($response->order, true);

Creating a new customer:, (*24)

<?php

use RetailCrm\Api\Interfaces\ClientExceptionInterface;
use RetailCrm\Api\Interfaces\ApiExceptionInterface;
use RetailCrm\Api\Factory\SimpleClientFactory;
use RetailCrm\Api\Model\Entity\Customers\Customer;
use RetailCrm\Api\Model\Request\Customers\CustomersCreateRequest;

$client = SimpleClientFactory::createClient('https://test.retailcrm.pro', 'apiKey');

$request = new CustomersCreateRequest();
$request->customer = new Customer();

$request->site = 'aliexpress';
$request->customer->email = 'john.doe@example.com';
$request->customer->firstName = 'John';
$request->customer->lastName = 'Doe';

try {
    $response = $client->customers->create($request);
} catch (ApiExceptionInterface | ClientExceptionInterface $exception) {
    echo $exception; // Every ApiExceptionInterface instance should implement __toString() method.
    exit(-1);
}

echo 'Customer ID: ' . $response->id;

Creating a task for the user with a specific email:, (*25)

<?php

use RetailCrm\Api\Interfaces\ClientExceptionInterface;
use RetailCrm\Api\Interfaces\ApiExceptionInterface;
use RetailCrm\Api\Factory\SimpleClientFactory;
use RetailCrm\Api\Model\Entity\Tasks\Task;use RetailCrm\Api\Model\Filter\Users\ApiUserFilter;
use RetailCrm\Api\Model\Request\Tasks\TasksCreateRequest;
use RetailCrm\Api\Model\Request\Users\UsersRequest;

$client = SimpleClientFactory::createClient('https://test.retailcrm.pro', 'apiKey');

$usersRequest = new UsersRequest();
$usersRequest->filter = new ApiUserFilter();
$usersRequest->filter->email = 'john.doe@example.com';

try {
    $usersResponse = $client->users->list($usersRequest);
} catch (ApiExceptionInterface | ClientExceptionInterface $exception) {
    echo $exception; // Every ApiExceptionInterface instance should implement __toString() method.
    exit(-1);
}

if (0 === count($usersResponse->users)) {
    echo 'User is not found.';
    exit(-1);
}

$tasksRequest = new TasksCreateRequest();
$tasksRequest->task = new Task();
$tasksRequest->task->performerId = $usersResponse->users[0]->id;
$tasksRequest->task->text = 'Do something!';
$tasksRequest->site = 'site';

try {
    $tasksResponse = $client->tasks->create($tasksRequest);
} catch (ApiExceptionInterface | ClientExceptionInterface $exception) {
    echo $exception; // Every ApiExceptionInterface instance should implement __toString() method.
    exit(-1);
}

echo 'Created task with ID: ' . $tasksResponse->id;

The error handling in the examples above is good enough for real production usage. You can safely assume that ApiExceptionInterface is an error from the API, and ClientExceptionInterface is a client error (e.g. network error or any runtime error, use HttpClientException to catch only PSR-18 client errors). However, you can implement more complex error handling if you want., (*26)

Also, both ApiExceptionInterface and ClientExceptionInterface implements __toString(). This means that you can just convert those exceptions to string and put the results into logs without any special treatment for the exception data., (*27)

More examples can be found in the documentation., (*28)

You can use a PSR-14 compatible event dispatcher to receive events from the client. See documentation for details., (*29)

Notes

This library uses HTTPlug abstractions. Visit official documentation to learn more about it., (*30)

The Versions

20/03 2018

dev-master

9999999-dev http://www.retailcrm.ru/

PHP client for retailCRM API

  Sources   Download

MIT

The Requires

  • ext-curl *
  • php >=5.4.0

 

The Development Requires

by retailCRM

api rest retailcrm

06/03 2018

v5.1.4

5.1.4.0 http://www.retailcrm.ru/

PHP client for retailCRM API

  Sources   Download

MIT

The Requires

  • php >=5.4.0
  • ext-curl *

 

The Development Requires

by retailCRM

api rest retailcrm

27/02 2018

v5.1.3

5.1.3.0 http://www.retailcrm.ru/

PHP client for retailCRM API

  Sources   Download

MIT

The Requires

  • php >=5.4.0
  • ext-curl *

 

The Development Requires

by retailCRM

api rest retailcrm

21/02 2018

v5.1.2

5.1.2.0 http://www.retailcrm.ru/

PHP client for retailCRM API

  Sources   Download

MIT

The Requires

  • php >=5.4.0
  • ext-curl *

 

The Development Requires

by retailCRM

api rest retailcrm

20/02 2018

v5.1.1

5.1.1.0 http://www.retailcrm.ru/

PHP client for retailCRM API

  Sources   Download

MIT

The Requires

  • php >=5.4.0
  • ext-curl *

 

The Development Requires

by retailCRM

api rest retailcrm

20/12 2017

v5.1.0

5.1.0.0 http://www.retailcrm.ru/

PHP client for retailCRM API

  Sources   Download

MIT

The Requires

  • php >=5.4.0
  • ext-curl *

 

The Development Requires

by retailCRM

api rest retailcrm

17/11 2017

v5.0.2

5.0.2.0 http://www.retailcrm.ru/

PHP client for retailCRM API

  Sources   Download

MIT

The Requires

  • php >=5.4.0
  • ext-curl *

 

The Development Requires

by retailCRM

api rest retailcrm

22/06 2017

v5.0.1

5.0.1.0 http://www.retailcrm.ru/

PHP client for retailCRM API

  Sources   Download

MIT

The Requires

  • php >=5.4.0
  • ext-curl *

 

The Development Requires

by retailCRM

api rest retailcrm

21/06 2017

v5.x-dev

5.9999999.9999999.9999999-dev http://www.retailcrm.ru/

PHP client for retailCRM API

  Sources   Download

MIT

The Requires

  • ext-curl *
  • php >=5.4.0

 

The Development Requires

by retailCRM

api rest retailcrm

21/06 2017

v5.0.0

5.0.0.0 http://www.retailcrm.ru/

PHP client for retailCRM API

  Sources   Download

MIT

The Requires

  • php >=5.4.0
  • ext-curl *

 

The Development Requires

by retailCRM

api rest retailcrm

12/06 2017

v4.x-dev

4.9999999.9999999.9999999-dev http://www.retailcrm.pro/

PHP client for retailCRM API

  Sources   Download

MIT

The Requires

  • php >=5.3.0
  • ext-curl *

 

The Development Requires

by retailCRM

api rest retailcrm

07/03 2017

v4.1.5

4.1.5.0 http://www.retailcrm.pro/

PHP client for retailCRM API

  Sources   Download

MIT

The Requires

  • php >=5.3.0
  • ext-curl *

 

The Development Requires

by retailCRM

api rest retailcrm

07/03 2017

v3.x-dev

3.9999999.9999999.9999999-dev http://www.retailcrm.pro/

PHP client for retailCRM API

  Sources   Download

MIT

The Requires

  • php >=5.3.0
  • ext-curl *

 

by retailCRM

api rest retailcrm

07/03 2017

3.0.6

3.0.6.0 http://www.retailcrm.pro/

PHP client for retailCRM API

  Sources   Download

MIT

The Requires

  • php >=5.3.0
  • ext-curl *

 

by retailCRM

api rest retailcrm

06/03 2017

dev-response-isset-v3

dev-response-isset-v3 http://www.retailcrm.pro/

PHP client for retailCRM API

  Sources   Download

MIT

The Requires

  • php >=5.3.0
  • ext-curl *

 

by retailCRM

api rest retailcrm

06/03 2017

dev-response-isset-v4

dev-response-isset-v4 http://www.retailcrm.pro/

PHP client for retailCRM API

  Sources   Download

MIT

The Requires

 

by retailCRM

api rest retailcrm

28/11 2016

v4.1.4

4.1.4.0 http://www.retailcrm.pro/

PHP client for retailCRM API

  Sources   Download

MIT

The Requires

 

by retailCRM

api rest retailcrm

30/10 2016

v4.1.3

4.1.3.0 http://www.retailcrm.pro/

PHP client for retailCRM API

  Sources   Download

MIT

The Requires

  • php >=5.3.0
  • ext-curl *

 

by retailCRM

api rest retailcrm

29/09 2016

v4.1.2

4.1.2.0 http://www.retailcrm.pro/

PHP client for retailCRM API

  Sources   Download

MIT

The Requires

  • php >=5.3.0
  • ext-curl *

 

by retailCRM

api rest retailcrm

21/09 2016

v4.1.1

4.1.1.0 http://www.retailcrm.pro/

PHP client for retailCRM API

  Sources   Download

MIT

The Requires

  • php >=5.3.0
  • ext-curl *

 

by retailCRM

api rest retailcrm

20/09 2016

v4.1.0

4.1.0.0 http://www.retailcrm.pro/

PHP client for retailCRM API

  Sources   Download

MIT

The Requires

  • php >=5.3.0
  • ext-curl *

 

by retailCRM

api rest retailcrm

22/07 2016

4.0.0

4.0.0.0 http://www.retailcrm.pro/

PHP client for retailCRM API

  Sources   Download

MIT

The Requires

  • php >=5.3.0
  • ext-curl *

 

by retailCRM

api rest retailcrm

02/03 2016

dev-delivery

dev-delivery http://www.retailcrm.ru/

PHP client for retailCRM API

  Sources   Download

The Requires

  • php >=5.3.0
  • ext-curl *

 

The Development Requires

by retailCRM

api rest retailcrm

20/05 2015

v3.0.4

3.0.4.0 http://www.retailcrm.ru/

PHP client for retailCRM API

  Sources   Download

The Requires

  • php >=5.3.0
  • ext-curl *

 

The Development Requires

by retailCRM

api rest retailcrm

27/11 2014

v3.0.3

3.0.3.0 http://www.retailcrm.ru/

PHP client for retailCRM API

  Sources   Download

The Requires

  • php >=5.3.0
  • ext-curl *

 

The Development Requires

by retailCRM

api rest retailcrm

13/11 2014

v3.0.2

3.0.2.0 http://www.retailcrm.ru/

PHP client for retailCRM API

  Sources   Download

The Requires

  • php >=5.3.0
  • ext-curl *

 

The Development Requires

by retailCRM

api rest retailcrm

06/11 2014

v3.0.1

3.0.1.0 http://www.retailcrm.ru/

PHP client for retailCRM API

  Sources   Download

The Requires

  • php >=5.3.0
  • ext-curl *

 

by retailCRM

api rest retailcrm

20/06 2014

1.3.0

1.3.0.0 http://www.intarocrm.ru/

PHP Client for IntaroCRM REST API

  Sources   Download

The Requires

  • php >=5.2.0
  • ext-curl *

 

by Kruglov Kirill

api rest intaro crm

13/04 2014

v1.2.5

1.2.5.0 http://www.intarocrm.ru/

PHP Client for IntaroCRM REST API

  Sources   Download

The Requires

  • php >=5.2.0
  • ext-curl *

 

by Kruglov Kirill

api rest intaro crm

03/04 2014

v1.2.4

1.2.4.0 http://www.intarocrm.ru/

PHP Client for IntaroCRM REST API

  Sources   Download

The Requires

  • php >=5.2.0
  • ext-curl *

 

by Kruglov Kirill

api rest intaro crm

22/03 2014

v1.2.3

1.2.3.0 http://www.intarocrm.ru/

PHP Client for IntaroCRM REST API

  Sources   Download

The Requires

  • php >=5.2.0
  • ext-curl *

 

by Kruglov Kirill

api rest intaro crm

04/03 2014

v1.2.2

1.2.2.0 http://www.intarocrm.ru/

PHP Client for IntaroCRM REST API

  Sources   Download

The Requires

  • php >=5.2.0
  • ext-curl *

 

by Kruglov Kirill

api rest intaro crm

15/10 2013

v1.0.0

1.0.0.0 http://www.intarocrm.ru/

PHP Client for IntaroCRM REST API

  Sources   Download

The Requires

  • php >=5.2.0
  • ext-curl *

 

by Kruglov Kirill

api rest intaro crm

15/10 2013

v1.1.0

1.1.0.0 http://www.intarocrm.ru/

PHP Client for IntaroCRM REST API

  Sources   Download

The Requires

  • php >=5.2.0
  • ext-curl *

 

by Kruglov Kirill

api rest intaro crm

15/10 2013

v1.2.0

1.2.0.0 http://www.intarocrm.ru/

PHP Client for IntaroCRM REST API

  Sources   Download

The Requires

  • php >=5.2.0
  • ext-curl *

 

by Kruglov Kirill

api rest intaro crm

15/10 2013

v1.2.1

1.2.1.0 http://www.intarocrm.ru/

PHP Client for IntaroCRM REST API

  Sources   Download

The Requires

  • php >=5.2.0
  • ext-curl *

 

by Kruglov Kirill

api rest intaro crm