Подготовка запроса

Перед выполнением любого запроса, интеграция выполняет содержимое кода предобработки. Вы можете использовать его для тонкой настройки запроса: преобразовать в JSON, добавить заголовки, провести авторизацию, скорректировать некоторые поля, сделать цифровую подпись к запросу.

Доступные переменные

При работе с запросом, вы можете влиять на три переменных:

  • $url - адрес отправки запроса.
  • $post - тело запроса в виде PHP-массива. Если пустое, запрос отправляется в GET, если заполнено - POST.
  • $cc - конфигурация CURL. Позволяет добавлять заголовки запроса, менять тип, ставить таймаут.

Под капотом система осуществляет вызов функции curl с этими параметрами:

curl( $url, $post, $cc );

Вы можете использовать её в своём коде для выполнения подзапросов. Например, пригодится для получения и сохранения токена авторизации. Параметры $post и $cc - необязательные.

Корректировка запроса

Данные для тела запроса находятся в переменной $post в виде массива. При необходимости, вы можете напрямую менять его содержимое.

Например, вам необходимо отдавать код валюты всегда заглавными буквами:

$post['currency'] = strtoupper( $post['currency'] );

Другой распространённый кейс - генерация цифровой подписи запроса.

$sign = hash_hmac( implode( ':', $post ), 'mysecretkey' );
$url .= '&signature=' . $sign;

Вы можете добавлять переменные в запрос на лету:

$post['rand_param'] = rand( 1000000, 99999999 );
$post['key'] = md5( 'whatthefuckamidoing' . $post['rand_param'] );

Вы можете даже создать само тело сложного запроса на лету, не используя указание полей:

$post = [ 'params' => [ 'filterByDate' => [
  'from' => '2022-01-01',
  'to' => '2022-12-31'
]]];

Но оптимально сгенерировать основную часть запроса с помощью полей и после вписать её в сложный запрос:

$post = [
  'user' => 123456,
  'key' => 'apikeywithoutajoke',
  'data' => $post,
];

Иногда удобно сгенерировать параметры для запроса через поля, но отправить их в ссылке методом GET. Для этого указываем URL запроса в следующем виде:

https://my.network.domain/api/getLeadStatus?

Со знаком вопроса на конце! А в коде предобработки добавляем строки:

$url .= http_build_query( $post );
$post = false;

Конфигурация CURL

При изменении конфигурации CURL, не задавайте содержимое массива $cc целиком, всегда редактируйте конкретное его поле.

Неправильно:

$cc = [ 'ipv4' => true, 'timeout' => 60 ];

Правильно:

$cc['ipv4'] = true;
$cc['timeout'] = 60;

Заголовки

За содержимое заголовков отвечает параметр header. Он должен содержать PHP-массив со строками заголовка.

$cc['header'] = [ 
  'Content-type: application/json',
  'Authorization: Bearer yay36u6a6u3gu'
];

Таймаут соединения

С помощью параметра timeout можно задать максимальное время соединения. По умолчанию это 15 секунд. Указывается в виде целого числа.

$cc['timeout'] = 30;

Используемый протокол подключения

Некоторые сети не поддерживают работу с молодым протоколом IPv6, которому всего четверть века. Для отправки запроса по протоколам IPv4 или IPv6 без переключения, используйте следующие варианты:

$cc['ipv4'] = true; // IPv4 only
$cc['ipv6'] = true; // IPv6 only

Метод отправки запроса

В редких случаях нам может потребоваться отправка запроса, отличного от традиционных GET без тела и POST с телом. За тип запроса отвечает переменная request.

$cc['request'] = 'PATCH';

Другие полезные мелочи

  • ua - строка User-Agent
  • referer - строка реферера запроса
  • login и pass - данные для стандартной аутентификации
  • onlycode - вернуть только код ответа сервера
  • proxy - строка с адресом прокси в виде proto://address:port
  • pauth - строка с данными авторизации прокси в виде login:pass
  • json - если указать true, запрос отправится в JSON-формате

Разные форматы запроса

По умолчанию платформа отправляет запрос в формате multipart/form-data, потому что именно в таком виде выглядит запрос при передаче массива в POST. Вы можете изменить поведение запроса под требования получателя.

application/x-www-form-urlencoded

Добавьте в конец кода предобработки строку:

$post = http_build_query( $post );

application/json

Добавьте в конец кода предобработки строку:

$cc['header'] = [ 'Content-type: application/json' ];
$post = json_encode( $post );

Если вы уже используете заголовок для авторизации, просто добавьте в список полей тип контента.

Авторизация

По классике, ключ API будет указываться в строке запроса или одном из полей данных. Иногда вам может потребоваться авторизация с помощью заголовка. Используйте $cc['header'] для его указания:

$cc['header'] = [ 'Authorization: Bearer ihateheaderauthentication' ];

Некоторые сети требуют получения заголовка при каждом сеансе работы. Мы рекомендуем использовать вот такой лайфхак с сохранением заголовка в массиве $core->flag[] после получения. Вместо ключа mynetwork используйте адрес целевой сети.

if ( ! $core->flag['mynetwork'] ) {
  $atk = xxdec(curl( 
    'https://my.network.url/api/affiliate/generateauthtoken', 
    [ 'userName' => 'MyLogin', 'password' => 'MyPassWord' ],
    [ 'json' => true ]
  ));
  if ( $atk['token'] ) $core->flag['mynetwork'] = $atk['token'];
}
$cc['header'] = [ 'AuthToken: ' . $core->flag['mynetwork'] ];

Функция curl используется для отправки запроса и описана выше. Функция xxdec - краткий псевдоним json_decode с выводом в виде ассоциативного массива.