Bitrix Framework

Let's overview one of full-scale standard scenarios available for REST delivery services: handing delivery in sales center. Starting point for a manager can be the feature of receiving payment ("Receive payment in deal") or creating a delivery activity.

  Manager procedure

Delivery cost pre-calculation

Manger can preliminarily calculate delivery cost inside delivery slider by selecting products for shipping and by indicating property values (addresses and a comment in this case) and requirements for additional services:

When calculating a delivery, system sends query for a URL, indicated in the property CALCULATE_URL of delivery service handler. Query passes all the parameters necessary for calculating delivery cost (shipment properties, weight, item price, necessary additional services, delivery service settings and etc.). Response must retrieve a preliminary delivery cost in the request's currency. When delivery cost calculation is impossible, delivery service must display error text to the manager (see. delivery cost pre-calculation webhook).

In case delivery service handler supports an option of creating delivery requests and their subsequent tracking (handler's parameter value HAS_CALLBACK_TRACKING_SUPPORT is set as "Y"), the system creates an activity for delivery of the created shipment.

Creating a delivery request

By using a delivery activity, manager can initiate process of delivery request creation. Clicking on Request delivery ( Request Delivery ) sends a query to URL, indicated in the property CREATE_DELIVERY_REQUEST of delivery service handler. The query, in addition to shipping information, also has information about sender and recipient contacts.

Upon successfully processed query results, delivery service creates a delivery request and passes its external identifier in the response. Subsequently, this identifier will be needed for updating the request's status and binding to sender or recipient of the request. If a delivery request cannot be created for some reason, delivery service must issue an error text to be displayed to the manager (see. delivery request creating webhook).

Delivery activity for successfully created delivery request will look as follows:

Cancelling a delivery request

Manager can attempt to cancel previously created request at any time until it wasn't completed by the delivery service. Clicking on Cancel request sends query to the URL, indicated in the property CANCEL_DELIVERY_REQUEST of delivery service handler. If permitted, delivery service can cancel the request and informs about successful cancellation in the response. Delivery activity in this case is returned to an original status and manager can re-issue delivery request. When request cannot be cancelled, delivery service must inform about the reason why the cancellation isn't possible. Reason will be printed to the manager on attempt to cancel the request (see. delivery request cancellation webhook).

  Delivery service procedure

Updating a delivery request

Next, it's expected that delivery service information will be updated while executing a delivery request.

Immediately after creating a delivery request, it's minimum required to update its status - for the manager to be aware what is happening with the request at this moment. For example, if searching for a request performer takes some time, manager can be informed by updating request status by the method sale.delivery.request.update:

{
  "DELIVERY_ID":723,
  "REQUEST_ID":"4757aca4931a4f029f49c0db4374d13d",
  "STATUS":{
    "TEXT":"Searching performer",
    "SEMANTIC":"process"
  }
}

Let's assume that request performer was found and now you need to register new status and performer information in the request. You can select properties for delivery request (method sale.delivery.request.update):

{
  "DELIVERY_ID":723,
  "REQUEST_ID":"4757aca4931a4f029f49c0db4374d13d",
  "STATUS":{
    "TEXT":"Performer found",
    "SEMANTIC":"process"
  },
  "PROPERTIES":[
    {
      "NAME":"Car",
      "VALUE":"Gray Skoda Octavia, a777zn"
    },
    {
      "NAME":"Driver",
      "VALUE":"John Smith"
    },
    {
      "NAME":"Phone Number",
      "VALUE":"+79097996161",
      "TAGS":[
        "phone"
      ]
    }
  ]
}

Set of properties can be arbitrary. If a property value is to be processed by a special method, you can mark it by tag. The example above demonstrates performer phone number marked by tag "phone". This allows displaying it as a link and open it via IP telephony (if it was configured at the customer's side), or standard browser features.

Suppose, the delivery service has forwarded a delivery request to the performer/executor (i. e. shipped an order) and now its status must be updated by the method sale.delivery.request.update:

{
  "DELIVERY_ID":723,
  "REQUEST_ID":"4757aca4931a4f029f49c0db4374d13d",
  "STATUS":{
    "TEXT":"Parcel on its way",
    "SEMANTIC":"process"
  }
}

In this case, property values are not passed, because they didn't require an update. Even if you still need to update delivery request properties, you can use two available modes:

• adding new properties and values (OVERWRITE_PROPERTIES = N, default mode)
• rewriting the complete set of properties (OVERWRITE_PROPERTIES = Y)

When a delivery order/request has been completed, you need to finalize it via the method sale.delivery.request.update:

{
  "DELIVERY_ID":723,
  "REQUEST_ID":"4757aca4931a4f029f49c0db4374d13d",
  "FINALIZE":"Y"
}

Activity for delivery in this case moves to a completed status , and its cancellation from the manager's side mow is not possible.

Sending delivery request messages

Let's assume that during delivery order/request in progress, you need to notify the manager responsible for delivery or an order recipient about a specific event. For example, you need to inform the customer that the parcel was handed over to delivery service and about the delivery time (method sale.delivery.request.sendmessage):

{
  "DELIVERY_ID":723,
  "REQUEST_ID":"4757aca4931a4f029f49c0db4374d13d",
  "ADDRESSEE":"RECIPIENT",
  "MESSAGE":{
    "SUBJECT":"We will soon deliver your parcel to you!",
    "BODY":"Your order has been dispatched and will be delivered to you in 23 minutes. Thank you!",
    "STATUS":{
      "MESSAGE":"Dispatched",
      "SEMANTIC":"success"
    }
  }
}

Notification will be sent to the customer using one of available communication channels, configured in CRM. This can be a SMS or a message sent from one of available messengers (for example, WhatsApp). To send a notification to a manager must assign a message recipient (ADDRESSEE) into the value "MANAGER".

Sending delivery request messages

Delivery service can also cancel an order on its own volition, by sending a corresponding request and ensuring that receiving party has received it. Such action may be required, for example, when initially it's not known, if a performer would be found for this request, or not. If the performer wasn't found, delivery service must initiate a request cancellation. In this case, a delivery activity is returned to its original form, so that manager can re-issue the delivery again.