intarocrm / rest-api-client
PHP client for RetailCRM API
Requires
- php: >=7.3
- ext-json: *
- civicrm/composer-compile-plugin: ^0.20
- doctrine/annotations: ^1.13|^2.0
- liip/serializer: 2.2.* || 2.6.*
- neur0toxine/psr.http-client-implementation.php-http-curl: *
- neur0toxine/psr.http-factory-implementation.nyholm: *
- neur0toxine/psr.http-message-implementation.nyholm: *
- php-http/client-implementation: ^1.0
- php-http/discovery: ^1.13
- php-http/httplug: ^2.2
- psr/cache: ^1.0 || ^2.0 || ^3.0
- psr/event-dispatcher: ^1.0
- psr/http-client: ^1.0
- psr/http-factory: ^1.1
- psr/http-message: ^1.0 || ^2.0
- psr/http-message-implementation: ^1.0
- psr/log: ^1|^2|^3
- symfony/cache: >=v3.1.0
- symfony/console: ^4.0|^5.0|^6.0|^7.0
Requires (Dev)
- dealerdirect/phpcodesniffer-composer-installer: ^0.7.1
- league/container: ^3.3
- league/event: ^3.0
- neur0toxine/pock: ^0.11
- nyholm/psr7: ^1.3
- php-http/curl-client: ^2.2
- phpcompatibility/php-compatibility: ^9.3
- phpmd/phpmd: ^2.10
- phpstan/phpstan: 1.9.14
- phpunit/phpunit: ^9.5
- squizlabs/php_codesniffer: ^3.5
- vlucas/phpdotenv: ^5.3
Suggests
- ext-curl: Most HTTP clients need ext-curl to work properly.
- league/event: PSR-14 compatible event dispatcher.
- nyholm/psr7: This is recommended PSR-7 and PSR-17 implementation.
- php-http/client-implementation: PSR-18 compatible client should be available to use this library.
- php-http/curl-client: Simplest PSR-18 client implementation.
- psr/http-factory-implementation: PSR-17 compatible factories should be available to use this library.
- psr/http-message-implementation: PSR-7 compatible HTTP message implementation should be available to use to use this library.
- psr/log-implementation: You can use log implementation for debug purposes.
- symfony/event-dispatcher: PSR-14 compatible event dispatcher.
- symfony/http-client: One of the most popular HTTP clients. Has PSR-18 compatible adapter.
- dev-master / 6.x-dev
- v6.15.9
- v6.15.8
- v6.15.7
- v6.15.6
- v6.15.5
- v6.15.4
- v6.15.3
- v6.15.2
- v6.15.1
- v6.15.0
- v6.14.4
- v6.14.3
- v6.14.2
- v6.14.1
- v6.14.0
- v6.13.8
- v6.13.7
- v6.13.6
- v6.13.5
- v6.13.4
- v6.13.3
- v6.13.2
- v6.13.1
- v6.13.0
- 6.12.5
- v6.12.4
- v6.12.3
- 6.12.2
- v6.12.1
- v6.12.0
- v6.11.0
- v6.9.2
- v6.9.1
- v6.9.0
- v6.8.4
- v6.8.3
- v6.8.2
- v6.8.1
- v6.8.0
- v6.7.3
- v6.7.2
- v6.7.1
- v6.7.0
- v6.6.0
- v6.5.0
- v6.4.6
- v6.4.5
- v6.4.4
- v6.4.3
- v6.4.2
- v6.4.1
- v6.4.0
- v6.3.0
- v6.2.2
- v6.2.1
- v6.2.0
- v6.1.6
- v6.1.5
- v6.1.4
- v6.1.3
- v6.1.2
- v6.1.1
- v6.1.0
- v6.0.4
- v6.0.3
- v6.0.2
- v6.0.1
- v6.0.0
- v5.x-dev
- v5.11.5
- v5.11.4
- v5.11.3
- v5.11.2
- v5.11.1
- v5.10.1
- v5.10.0
- v5.9.0
- v5.8.0
- v5.7.5
- v5.7.4
- v5.7.3
- v5.7.2
- v5.7.1
- v5.7.0
- v5.6.0
- v5.5.4
- v5.5.3
- v5.5.2
- v5.5.1
- v5.5.0
- v5.4.0
- v5.3.0
- v5.2.0
- v5.1.4
- v5.1.3
- v5.1.2
- v5.1.1
- v5.1.0
- v5.0.2
- v5.0.1
- v5.0.0
- v4.x-dev
- v4.1.5
- v4.1.4
- v4.1.3
- v4.1.2
- v4.1.1
- v4.1.0
- v4.0.0
- v3.x-dev
- 3.0.6
- v3.0.5
- v3.0.4
- v3.0.3
- v3.0.2
- v3.0.1
- 1.3.0
- v1.2.5
- v1.2.4
- v1.2.3
- v1.2.2
- v1.2.1
- v1.2.0
- v1.1.0
- v1.0.0
- dev-fixCreateLink
- dev-createLinksOrder
This package is not auto-updated.
Last update: 2024-10-26 15:36:29 UTC
README
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.
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:
- Download and install Composer package manager.
- Install the library from the Packagist by executing this command:
composer require retailcrm/api-client-php:"~6.0"
During the installation you will see this message. Press 'y'
when you do:
civicrm/composer-compile-plugin contains a Composer plugin which is currently not in your allow-plugins config. See https://getcomposer.org/allow-plugins Do you trust "civicrm/composer-compile-plugin" to execute code and wish to enable it now? (writes "allow-plugins" to composer.json) [y,n,d,?]
After that, you may see a message which will look like this:
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)
Choose [a]lways
by typing a
and pressing Enter.
Note: You should choose 'y'
and [a]lways
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.
If you chose something else during the installation and API client doesn't work properly - please follow these instructions to fix the problem.
- 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
.
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:
composer require symfony/http-client guzzlehttp/psr7 retailcrm/api-client-php:"~6.0"
More information about that can be found in the documentation.
Usage
Firstly, you should initialize the Client. The easiest way to do this is to use the SimpleClientFactory
:
$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:
$client->api->credentials();
For example, you can retrieve the customers list:
$client = \RetailCrm\Api\Factory\SimpleClientFactory::createClient('https://test.retailcrm.pro', 'apiKey'); $response = $client->customers->list();
Or the orders list:
$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.
An example of error handling can be found in the next section of this document.
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.
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.
More information about the usage including examples can be found in the documentation.
Examples
Listing orders:
<?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:
<?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:
<?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:
<?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.
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.
More examples can be found in the documentation.
You can use a PSR-14 compatible event dispatcher to receive events from the client. See documentation for details.
Notes
This library uses HTTPlug abstractions. Visit official documentation to learn more about it.