Improved logistics for AlterCPA and CPAmoe
Improved logistics for AlterCPA and CPAmoe

Xoxo, Reznik here! Today we gonna implement powerful logistics for AlterCPA or CPAmoe. Or you will, and it’s power will also depend on you. I’ll only give you a few advices.

The AlterCPA platform allows you to track the delivery of parcels of your product traffic and control the buyout in automatic mode. The built-in types of delivery at the time of this writing do not provide extensive freedom of action in the field of logistics. And for organizing various delivery schemes designed to deceive courier and postal services, it will never support it. Therefore, our way out is to expand the possibilities of logistics with our own efforts or to implement “schematosis”.

Schematosis (“scheme” + “diagnosis”) – this is an irresistible desire of the boss to save at the expense of cunning schemes for bypassing normal work and various methods of deceiving courier services. It is usually degraded from “schematics” or “schemes” – complicated, but legal, taking most of the advantages of various competitive solutions in one area.

For this we need a quality programmer in the amount of at least one piece. Further guidance is intended to study exclusively complete with a competent specialist in the development of web services. Without a good programmer, nothing described below can be implemented. None.

The guide is suitable for organizing your logistic service in conjunction with a full-featured AlterCPA, as well as for connecting to the logistics of free CRM for commodity CPA business CPAmoe. Differences in work are minimal, they will be indicated separately.

Solution architecture

Our minimum plan is to create some kind of web service that must fulfill the following tasks:

  1. Load orders ready to be sent from your AlterCPA network or your CPAmoe account.
  2. Transfer orders to delivery service based on the data received and add the appropriate marks to the order on the AlterCPA / CPAmoe side.
  3. Load data on the current status of the shipment from the delivery service and collect from them a consistent history of changes in the delivery status of the package.
  4. Upon request from AlterCPA / CPAmoe, show the delivery status history of the package in a strictly defined format used within the standard delivery type.

We call our creation “logistics service”. Below we will look at some more useful features of this service that can be implemented, but first we will focus on these four mandatory points.

Loading orders for delivery

The AlterCPA Merchant API makes it quite convenient to load orders that require delivery. Suppose we will load all orders in the status “Sending” from the delivery type “Standard”, which is exactly intended for such integration. In general, you can unload orders from the “Packing”, if fulfilment runs on the basis of the logistic service.

We need to use “Order list” API from Merchant section of your network documantation, for example: ui.cpa.moe/help/api.en.php#orderlist. At first glance, it represents a terribly inconvenient interface, because it does not allow us to unload only those packages that need to be delivered now. And that would be so if AlterCPA did not have its undocumented function in this case.

We send the request with following GET-parameters:

  • trackon with value 0, will give us orders without track-code.
  • delivery with value 1, will filter orders by “Standard” delivery type.
  • status with value 7, will filter orders by “Sending” status, for “Packing” use 6.
  • You also can add stage with the extended status ID or stagename with it’s code to filter orders by specific stage.

For example, the URL for CPAmoe will look like this:

https://api.cpa.moe/comp/list.json?id=x-x&trackon=0&delivery=1&status=6

As the result, we get a list of orders that are ready to be shipped. The composition of the fields is best studied in the API documentation. It contains all the recipient data and the list of the goods in the order.

Transfer orders to delivery

The loaded orders we actually need to send. To do this, we immediately, or after some processing, transfer orders to the delivery service interface.

We will not consider the process of transferring orders to your delivery services, the solution to this problem lies entirely on the powerful brain of your programmer. We are only interested in one thing: after adding the order to the delivery service, we will get a certain track code.

We need to add this track code to the order in AlterCPA and enable automated tracking. It can be done via “Edit order” API, for example: ui.cpa.moe/help/api.en.php#orderedit

We need to send the following GET or POST fields:

  • oid with the order ID on AlterCPA side
  • trackon with value 1 to enable automated tracking
  • track with our track code value

For example, the URL for CPAmoe will look like this:

https://api.cpa.moe/comp/edit.json?id=x-x&oid=123&trackon=1&track=AB123456

It is recommended to do this request immediately after the order is loaded from AlterCPA and sent to the delivery service. Otherwise, the order will be shown again at the next request for loading orders.

If you do not send orders immediately, use any of your own intermediate track code that will be uniquely compared with the order in the database of your logistic service. You will use it to check the status of the package further.

Loading delivery progress

The process of loading progress statuses, as well as adding orders to the delivery service, is still referred to your programmer. As usual, this task is not difficult. But sometimes the desire to find a developer of parcel tracking API and firmly shake his neck goes over all bounds.

There are some advices for loading statuses that will greatly simplify your integration:

  • It is mandatory to save not one last status, but the entire history of the delivery statuses, so that it can be easily uploaded to AlterCPA.
  • Record the time of occurrence of each of the statuses. If the status on the delivery service side does not contain a timestamp, enter there the time of the first appearance of the status when checking.
  • If possible, get the ZIP code and the city in which the status appeared in the parcel delivery history. This may be useful later for manual analysis of delivery.
  • If necessary, save text comments to statuses in the delivery history, they can also be useful. In such comments, delivery services often point to the postponement of delivery, problems in communicating with the customer, and other important information for your call center.

You can both load these data automatically and store it in your logistic service database, or process it upon request from AlterCPA, which is described below.

Showing AlterCPA the parcel delivery history

Twice a day, AlterCPA may request a delivery history of the parcel. To set up the tracking, you need to go to the “Delivery services” section of the selected company, activate the “Standard” delivery and enter the URL of the API function on the side of your logistic service in the URL field, which will display the delivery history in the format described below.

When specifying the tracking URL, add the {code} macro and it will be replaced with the parcel track code that you added in the second paragraph of the algorithm. If the {code} macro in the address is not specified, the track code will be added to the end of the URL.

At the specified URL, your logistic service should display the status history in JSON format as a simple array of objects, each of object corresponds to one status. All statuses should be sorted by time of occurrence, from old to new. Compliance with the structure below is strictly required.

Status object may contain the following fields:

  • status – required field with symbolic delivery status, listed below
  • time – required field with the time of occurrence of the status in the UNIX timestamp format
  • country – country ISO-code
  • zip – ZIP-code
  • city – city or place
  • comment – arbitrary status comment

The field status should contain one of the following values:

  1. wait – parcel is waiting to be sent.
  2. transfer – the parcel is on the way, is transferred to the “Delivery” status.
  3. problem – there were problems with the delivery of the parcel, the reaction of the merchant is required.
  4. delivered – the parcel arrived at the destination, transferred to the “Delivered” status.
  5. paid – the parcel was successfully paid, transferred to the “Completed” status.
  6. return – parcel returned or disposed of, transferred to the “Return” status.
  7. comment – arbitrary comment without changing the state of the parcel.

An example of a function response might look like this:

[ 
   { 
      "status":"delivered",
      "time":1234567890,
      "zip":"AB1234",
      "city":"Neverland"
   },
   { 
      "status":"paid",
      "time":1234567891,
      "comment":"Awesome!"
   }
]

Printing docs and labels

In the AlterCPA interface, the operator can request a package of documents for sending. To activate this function, for delivery “Standard” you need to specify in the URL field the address of the API function on the side of your logistics service, which will give a link to the document package file in the format described below.

When specifying the print URL, add the {code} macro and it will be replaced with the parcel track code that you added in the second paragraph of the algorithm. If the {code} macro in the address is not specified, the track code will be added to the end of the URL.

At the specified URL, your logistics service should give a response in JSON format with two fields: status and url. The status field should contain ok in case of successful formation of a package of documents and error in case of an error. The url field should contain a link to the package of documents that will be provided to the user.

An example of successful function response might look like this:

{
    "status": "ok",
    "url": "https://altercpa.one/docs/abcdef123456.zip"
}

The easiest way to implement

Your logistic service may consist of two logical functions, or even just two files that will perform the following:

  1. Load parcels from the system in accordance with paragraph 1 and immediately send them, making notes in accordance with paragraph 2.
  2. Receive requests from the system, as described in paragraph 4, under the background making a request under paragraph 3 and producing a result formatted as described in paragraph 4.

This simple mechanism is enough for you to organize the work of your delivery service, which is not yet available in AlterCPA or CPAmoe. And at the time you read this article, there surely is not the service you need, no wonder you are reading this at all!

Several delivery services

You probably have a reasonable question: if we use only the “Standard” type of delivery, then how do we work with several delivery services? The question is quite logical, and there is an answer to it, not without a light smell of the dendro-faecal paradigm of software development.

This life hacking I spied on several CRM. We need to create special delivery goods. In the settings of AlterCPA and CPAmoe products we even have the corresponding product group for this purpose.

An example of the goods field of an order containing both the main and delivery goods:

[ 
   { 
      "id":11,
      "name":"Dick Extender",
      "short":"dexter",
      "count":2,
      "price":990,
      "param":{ 
         "abc":"123",
         "def":"456"
      }
   },
   { 
      "id":22,
      "name":"Delivery via courier",
      "short":"courier",
      "count":1,
      "price":350,
      "param": []
   }
]

In order not to identify the delivery types by their full name, in CPAmoe it is recommended to use the “Short Name” field to set the code of delivery type, for example: courier. When loading order data, this parameter will appear in the short field of goods list. The owners of the full AlterCPA version can also use the additional parameters of the goods that will be in the params field.

Schematosis as diagnosis

In the field of CPA merchants always want to arrange some tricky scheme of work to reduce costs. And the delivery here is one of the largest items of expenses, the reduction of which can bring fabulous profits.

The most classic optimization scheme for a delivery service is the use of several (tens, hundreds, thousands) accounts to send packages. Sometimes they are even issued to individuals to simplify the procedure for returns or other purposes.

For such a case, the simple method of sending packages will not be enough, and it is recommended to make your logistics service as a separate powerful solution that will store the necessary data on parcels and give you some web-interface.

Store the following types of data:

  • Delivery services accounts. From this table you will choose the appropriate account on whose behalf the delivery of the selected parcel will be delivered according to your cunning algorithm, which certainly differs from ORDER BY RAND (). In addition to the access key to the delivery service itself, it will be useful to save the sender’s name, return address and various additional delivery settings, such as the types of packages used and stuff like that. Organize a convenient interface for managing these accounts, in particular for checking their activity, for example to exclude those that have reached their limits in time.
  • Parcel data. It is recommended to keep the recipient’s data (full name, telephone number, shipping address) and order contents in this table. Each package must be linked to the account from the list above. You don’t need to add some additional table for the order goods, the serialized text field in JSON format will be enough. There is no need to build statistics and keep records of goods, the warehouse accounting interface in both paid AlterCPA and free CPAmoe will do it for you.
  • Parcel status history. It is highly recommended to use a separate table for this purpose. Depending on the delivery services used, you can upload order data much more often than twice a day. On request with AlterCPA, you can show the status list from this table as quickly as possible. If necessary, you can directly ask AlterCPA / CPAmoe to update the tracking information of the parcel using the method described below.

Such a logistics service will allow you to implement any scheme of work you even wish. It is also suitable for further expansion of the functionality, which can be useful in the delivery.

Ask AlterCPA / CPAmoe to update tracking info

Sometimes the delivery of the parcel can be carried out much faster than it does even the updated Russian Post from the picture above. Or problems may arise during the delivery process and require an urgent call center response. In such a situation, checking the status twice a day will not be enough.

We can ask for a forced status update with such a simple request:

https://api.cpa.moe/comp/retrack.json?id=x-x&oid=123

The oid parameter must contain the order ID on the AlterCPA / CPAmoe side. It is assumed that when working with powerful logistics service, you store this ID in your parcel data table.

What else you should and shouldn’t implement?

Since a whole logistics service has been created for our work schemes, it is recommended to think about expanding its functionality with such features:

  • Preparation and printing of documents on a batch of parcels for convenient transfer to the courier
  • Preparation and printing of parcel labels
  • Calculation of the cost of delivery of parcels

You have no need to think about the following:

  • Packing: implemented in AlterCPA and CPAmoe, “Extended order statuses” will come in handy
  • Delivery call: implemented in AlterCPA and CPAmoe, the delivery operator teams and the ability to easily change the call time of orders in any statuses will be useful. In the full version, you can send delivery orders for processing to third-party call-center.
  • Warehouse accounting: available in AlterCPA and CPAmoe, in the full version it also supports synchronization of balances with third-party services.
  • Buyout analysis: available in AlterCPA and CPAmoe, implemented for orders in the “Delivery analytics” section, available for goods in the “Statistics” section of the warehouse.

According to this manual, it will be much easier for you to implement your delivery work model in full AlterCPA or free CRM for CPA networks CPAmoe.

Reznik here. Out!