api-client-php/doc/usage/sending_a_request.md

Sending a request

You need three things to send a request:

1. Resource group, DTOs, and method
2. Send a request
3. Deal with exceptions

Choosing correct resource group, DTOs, and method

First, take a look at the API itself:

• English
• Русский

Choose a method you want to use. Which one is yours depend on the task you want to perform.

Then take look at the API again. It consists of several blocks, each block is responsible for a specific set of features. The Client itself is also separated to those blocks or resource groups (full list of them can be found here).

Each resource group corresponds to an equal block in the documentation. For example. customersCorporate resource group implements methods in the Corporate customers API block (рус. Корпоративные клиенты).

Just look at the method you want to use and pick a proper resource group. That's it. Let's move on to the DTOs.

Choosing proper DTOs is also easy. Each client method defines expected parameter types. If the method doesn't have any parameters, then the API method is also doesn't require any parameters and can be just called. The most noteworthy would be /api/api-versions and /api/credentials methods. They can be called from the Client instance like that:

use RetailCrm\Api\Factory\SimpleClientFactory;

$client = SimpleClientFactory::createClient('https://test.retailcrm.pro', 'key');
$client->api->apiVersions();
$client->api->credentials();

The majority of the methods will require some parameters. Usually it's a request DTO, some path parameters (like customer id) or both. For example, /api/v5/customers/create method requires request DTO, /api/v5/customers/{externalId} requires customer ID and /api/v5/customers/{externalId}/edit requires both.

The corresponding methods on the client instance are:

API method	Client instance method
/api/v5/customers/create	$client->customers->create
/api/v5/customers/{externalId}	$client->customers->get
/api/v5/customers/{externalId}/edit	$client->customers->edit

Look at the method definitions (they have also shown by the IDE):

public function create(CustomersCreateRequest $request): IdResponse;
public function get($identifier, ?BySiteRequest $request = null): CustomersGetResponse;
public function edit($identifier, CustomersEditRequest $request): CustomersEditResponse;

Just use types from the type hints and everything will work. The DTO's fields also have type declarations but in the form of the @var annotation tags. That's how you can choose the correct type for the DTO fields.

Sending a request

Using information from the previous article you can easily construct a request.

This request will create a new customer.

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', 'key');
$request = new CustomersCreateRequest();

$request->customer = new Customer();
$request->customer->email = 'test@example.com';
$request->site = 'site';

$response = $client->customers->create($request);

This one will fetch specific customer from the API by the ID and site.

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

$client = SimpleClientFactory::createClient('https://test.retailcrm.pro', 'key');
$response = $client->customers->get(1, new BySiteRequest(ByIdentifier::ID, 'site'));

echo $response->customer->email;

And this one will edit specific customer:

use RetailCrm\Api\Enum\ByIdentifier;
use RetailCrm\Api\Factory\SimpleClientFactory;
use RetailCrm\Api\Model\Entity\Customers\Customer;
use RetailCrm\Api\Model\Request\Customers\CustomersEditRequest;

$client = SimpleClientFactory::createClient('https://test.retailcrm.pro', 'key');
$request = new CustomersEditRequest();

$request->customer = new Customer();
$request->customer->email = 'test@example.com';
$request->site = 'site';
$request->by = ByIdentifier::ID;

$response = $client->customers->edit(1, $request);

echo "Edited customer ID: " . $response->id;

Dealing with exceptions

What will happen if an API error is returned for the one of requests above? Or the network is not working at all? An exception will happen.

There are two main exception types:

• RetailCrm\Api\Interfaces\ApiExceptionInterface is thrown if API returned an error.
• RetailCrm\Api\Interfaces\ClientExceptionInterface is thrown if the request cannot be sent due to an internal error.

You can use those like this:

use RetailCrm\Api\Factory\SimpleClientFactory;
use RetailCrm\Api\Interfaces\ApiExceptionInterface;
use RetailCrm\Api\Interfaces\ClientExceptionInterface;

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

try {
    $response = $client->customers->list();
} catch (ApiExceptionInterface $exception) {
    echo $exception;
} catch (ClientExceptionInterface $exception) {
    echo 'Client error: ' . $exception->getMessage();
}

if (isset($response)) {
    echo "Customers: " . print_r($response->customers, true);
}

More information about exceptions can be found on the error handling page.