Preparing request

Before performing any request, integration performs the contents of the preprocessing code. You can use it for fine configuration of the request: convert to JSON, add headers, carry out authorization, adjust some fields, make a digital signature to request.

Available variables

When working with the request, you can affect three variables:

  • $url - request destination URL.
  • $post - the body of the request in the form of a PHP array. If empty, the query is sent to GET. If it is filled - POST.
  • $cc - CURL configuration. Allows you to add the request headers, change the type, put the timeout.

Under the hood, the system calls the curl function with these parameters:

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

You can use it in your code to execute subrequests. For example, it is useful for obtaining and maintaining the authorization token. Parameters $post and $cc are optional.

Request adjustment

Data for the request body is located in the variable $post as an array. If necessary, you can directly change its contents.

For example, you need to give the currency code always in capital letters:

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

Another common case - generation of digital signature for the request:

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

You can add variables to the request on the fly:

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

You can even create the body of a complex request on the fly, without using the fields:

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

But it is optimal to generate the main part of the request using fields and then fit it into a complex request:

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

Sometimes it is convenient to generate parameters for the request through the fields, but send them in the link using the GET method. To do this, set the request URL in the following form:

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

With a question mark at the end! And in the preprocessing code, add the lines:

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

CURL configuration

When changing the CURL configuration, do not set the entire contents of the $cc array, always edit its specific field.

Wrong:

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

Right:

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

Headers

The header parameter is responsible for the contents of the headers. It should contain a PHP array with header lines.

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

Connection timeout

Using the timeout parameter, you can set the maximum connection time. The default is 15 seconds. Specified as an integer.

$cc['timeout'] = 30;

Connection protocol used

Some networks do not support the young IPv6 protocol, which is only a quarter of a century old. To send a request over IPv4 or IPv6 without switching, use the following options:

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

Request method

In rare cases, we may need to send a request other than the traditional GET without a body and POST with a body. The request variable is responsible for the request type.

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

Other useful little things

  • ua - User-Agent string
  • referer - request referer string
  • login and pass - data for basic authentication
  • onlycode - return only server reply code
  • proxy - proxy url like proto://address:port
  • pauth - proxy authentication data like login:pass
  • json - if set to true, the request will be sent in JSON format

Different request formats

By default, the platform sends a request in the multipart/form-data format, because this is how the request looks when passing an array in POST. You can change the behavior of the request to suit the needs of the recipient.

application/x-www-form-urlencoded

Add the following line to the end of the preprocessing code:

$post = http_build_query( $post );

application/json

Add the following line to the end of the preprocessing code:

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

If you are already using a header for authorization, simply add the content type to the list of header fields.

Authorization

Classically, the API key will be specified in the query string or one of the data fields. Sometimes you may need to authorize with a header. Use $cc['header'] to specify it:

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

Some networks require the header to be retrieved on every session. We recommend using this hack to store the token in the $core->flag[] array after getting it. Instead of the mynetwork key, use the address of the target network.

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'] ];

The curl function is used to send the request and is described above. The function xxdec is a shorthand alias for json_decode with output as an associative array.