Checking statuses via API

Statuses check can work in three variations:

  • Checking status for processing leads. Orders in the statuses "Processing", "Callback" and "Hold" are checked. The check is performed every 10 minutes. Leads are checked against a list of identifiers. As a result of the check, the lead changes the status of the call, moves to the terminal status "Approval" or "Cancel".
  • Checking status for approved leads. Orders in the statuses "Packaging", "Sending", "Delivery" and "Delivered" are checked. The check is performed every few hours. Leads are checked against a list of identifiers. As a result of the check, the lead changes the delivery status, goes to "Completed" or "Returned".
  • Checking status by date range. Orders are verified in all non-terminal statuses. The check is performed every hour. Checking is carried out by date ranges in which there are orders. Lead can be transferred to any status.

All integrations have a similar approach to links, fields, and processing code. The request is made separately for each offer. The query includes a selected number of leads or a range of days. The response is decoded automatically depending on the selected format. The processing code must change the status of the lead within itself.

Check URL

This is the address to which the request will be made. The macros for checking against dates and checking against a list of identifiers are different.

Checking processing and approved leads:

  • {idsl} - list of internal lead IDs separated by commas.
  • {idel} - list of external lead IDs separated by commas.

Checking leads by date range:

  • {from} and {to} - start and end date of the period in YYYY-MM-DD format.
  • {ffrom} and {fto} - start and end date of the period in YYYY-DD-MM HH:MM:SS format.
  • {ufrom} and {uto} - start and end date of the period in UNIX timestamp format.

Data fields

The data fields support the same list of macros as the validation URL. Two additional macros are available to check leads in processing and accepted leads:

  • {ids} - array of internal order IDs
  • {ide} - array of external order IDs

When sending arrays, it is recommended to convert the request to form-urlencoded or JSON format using preprocessing code.

Preprocessing code

The basic principles of using the preprocessing code are described in the relevant section of the documentation. The main variables in the preprocessing code are the same as the corresponding data field macros.

Checking processing and approved leads:

  • $idl - array of internal order IDs.
  • $ide - an associative array of external order identifiers whose key is internal order identifiers.
  • $idsl - list of internal lead IDs separated by commas.
  • $idel - list of external lead IDs separated by commas.

Checking leads by date range:

  • $from and $to - start and end date of the period in YYYY-MM-DD format.
  • $ffrom and $fto - start and end date of the period in YYYY-DD-MM HH:MM:SS format.
  • $ufrom and $uto - start and end date of the period in UNIX timestamp format.

Processing code

The input of the processing code is the $data variable containing the decoded response from the server. Most often, this is an associative array obtained by decoding JSON.

Additional variables that can be used in the processing code:

  • $e2i - array of matching external IDs with internal IDs. For security reasons, it is recommended to use external IDs through this array like this: $e2i[$d['id']].
  • $ids - array of order statuses by internal order ID.
  • $i2t - array of order creation time by internal ID.

The task of the processing code is to go through the response array and distribute statuses to leads in accordance with the statuses in the target CRM. The general view of the processing code can be represented as follows:

foreach ( $data as $d ) {
  $oid = $e2i[$d['id']]; // Get our ID by their ID
  switch ( $st ) {
    case 'accept': $core->lead->edit( $oid, [ 'accept' => 1 ] ); break;
    case 'cancel': $core->lead->edit( $oid, [ 'status' => 5 ] ); break;
    case 'trash':  $core->lead->edit( $oid, [ 'status' => 5, 'reason' => 6 ] ); break;
  }
}

For many integrations, a shorthand processing option that recognizes the text value of the status may be suitable:

foreach ( $data as $d ) $core->lead->setstc( $e2i[$d['id']], $d['status'] );

Financial integrations can use a variant of the processing code that takes into account the presence of the first deposit with the client:

foreach ( $data as $d ) {
  $oid = $e2i[$d['id']];
  if ( ! $oid ) continue;
  if ( $d['ftd'] ) {
    $core->lead->approve( $oid, $d['status'] );
  } else $core->lead->setstc( $oid, $d['status']  );
}

Order editing functions

An order is edited using the $core->lead->edit function. It has several add-ons to shorten and simplify the code.

$core->lead->approve( $id, $comment )

The function approves the lead with the number $id. If the optional parameter $comment is set, the lead receives corresponding comment.

$core->lead->setstatus( $id, $status )

The function tries to automatically recognize the status in the $status parameter and set it for the lead with the number $id.

$core->lead->setstc( $id, $status )

The function tries to automatically recognize the status in the $status parameter and set it for the lead with the number $id. It also writes the initial $status value to the lead comment for easy analysis.

$core->lead->edit( $id, $data )

The function changes the lead with the number $id according to the specified data in the $data array. The $data array can contain the following fields:

  • accept = 1 - approve lead. Use this particular confirmation option, and not setting the status of the lead to "Packaging" or "Completed" for the correct operation of all mechanisms.
  • status - numeric status identifier from 1 to 12, the list is given below.
  • reason - numeric identifier of the cancellation reason, may vary depending on your network settings.
  • hold - if true is passed, the lead is sent to hold for the number of days specified in the offer setting. If an integer is passed, the lead is put on hold for that number of days.
  • comment - text comment to the order. Don't forget addslashes!
  • base - unit price.
  • count - quantity of goods in the order.
  • curr - internal identifier of the order currency, determined by the function $core->currency->id( $iso ) by the currency ISO code.
  • goal - internal identifier of the offer goal, determined by the function $core->goal->bycode( $off, $code ) by the symbolic goal code in $code.
  • track - track code for tracking order delivery progress.

Order confirmation example:

$core->lead->edit( $oid, [ 'accept' => 1 ] );

An example of changing the status of an order and a comment:

$core->lead->edit( $oid, [ 'status' => 3, 'comment' => addslashes(stripslashes( $d['comment'] )) ] );

Example of order rejection with reason:

$core->lead->edit( $oid, [ 'status' => 5, 'reason' => 6 ] );

When editing a lead, the cash parameter can also be used - an array of manually set commissions. It allows you to redefine commissions based on those received from the affiliate network. May contain the following fields:

  • wm - affiliate commission.
  • pay - advertizer commission.
  • ref - refferal commission.
  • cc - commission currency.

The optimal use case is to set the amount of commission for the advertiser, leaving the choice of commission for the affiliate on the conscience of the system:

'cash' => [ 'pay' => $d['payout'], 'cc' => $d['currency'] ]

An example of a lead confirmation with advertiser commission:

$core->lead->edit( $oid, [ 'accept' => 1, 'cash' => [ 'pay' => $d['payout'], 'cc' => $d['currency'] ] ] );

Lead statuses and cancellation reasons

The lead can be in one of these statuses:

  1. New - the lead is waiting to be processed or sent to CRM
  2. Processing - the lead has been sent to CRM and is being processed
  3. Call back - the lead is being processed by the call center
  4. Hold - the lead is waiting for automatic approval
  5. Cancel - lead cancelled, reason for cancellation required
  6. Packing - the lead has been approved and is waiting to be packaged
  7. Sending - order is packed and awaiting shipment
  8. Delivery - order shipped and is in delivery progress
  9. Delivered - the order has been delivered to the point of issue
  10. Complete - order is bought out and completed
  11. Return - order returned to sender
  12. Delete - the lead has been deleted and is not included in the statistics

Default cancellation reasons:

  1. Incorrect phone (trash)
  2. Changed his mind
  3. Did not order (trash)
  4. Requires certificate
  5. Wrong GEO (trash)
  6. Errors or fakes (trash)
  7. Duplicate order (trash)
  8. Ordered elsewhere (trash)
  9. Expensive
  10. Not satisfied with delivery (trash)
  11. Could not get through (trash)
  12. Possibly fraud (trash)
  13. Speaks different language
  14. Product did not fit
  15. Offer disabled