retailCRM Documentation

The procedure of delivery service integration through API

Changelog

14.11.2017

    - POST {integrationModule["baseUrl"]}/{configuration["actions"]["shipmentSave"]} creation/editing of pick-up request
    - POST {integrationModule["baseUrl"]}/{configuration["actions"]["shipmentDelete"]} removing of pick-up request

To be available to use this methods specify paths to methods shipmentSave and shipmentDelete in parameter integrationModule[integrations][delivery][actions][] in method POST /api/v5/integration-modules/{code}/edit.

27.09.2017

22.03.2017

01.03.2017

Capabilities of integration

The system API allows to:

  1. Perform delivery cost calculation by order data by request of system user
  2. Transmit to system user the actual set of terminals for current order
  3. Form different packs within one order on delivery
  4. Form the order on delivery, transmitting the necessary information on order to the delivery service
  5. Edit and remove the order on delivery in definite statuses by request of system user
  6. Update massively the statuses for uncompleted orders
  7. Transmit for printing the documents on orders from delivery service by request of system user
  8. Create, edit and delete requests for the shipment of the goods by the delivery service

Working with the API is carried out in accordance to API rules. Api-methods from Delivery section are used for integration.

For integration it is necessary to:

  1. USER Request the API-key of user for access to the system
  2. API Register new delivery integration module
  3. USER Make the necessary settings on the integration settings page in the system
  4. USER Create delivery type related with new integrated delivery service
  5. SYSTEM Requests on creation and editing of orders on delivery will be initiated by system in working process of user
  6. API Send actual data on delivery statuses

Steps with mark USER are the steps, where the data are provided or filled in by the user. Steps with mark API are executed by API-requests from delivery service through the system API. Step with mark SYSTEM means that requests are carried out by the system to delivery service based on the settings specified when registration.

When occurring an error in API query to delivery service, needed to return response in the format:

{
    "success": false,
    "errorMsg": "Error text" // Error message. Will be displayed to user on order page
}

For identification of regions, cities and streets, in addition to the text names, identifiers are transmitted from the service Geohelper.

Registration and configuration of delivery service

Registration of new delivery service and settings change of existing should be made by method POST /api/v5/integration-modules/{code}/edit. If delivery service integration module with code code already exists, method changes it settings, otherwise the new integration module will be created. During delivery service integration registration a unique code integrationModule[clientId] is passed in method. This code allows to identify in delivery service account the system.

Parameters:

Important: Client ID clientId is used in all queries from the system to delivery service. The key should definitely identify the client on the delivery service side.

In the integrationModule[integrations][delivery][actions] field in the form of content addressable array ("Method code": "Path") paths to concrete methods are specified. Methods list:

Some methods are not mandatory to realization. If they don`t require the integration, they can be transferred in actions array. save, get, print, shipmentSave, shipmentDelete methods are not mandatory to realization. If save method is not specified, then requests for delivery creation is not being sent. If path to method shipmentDelete is not specified, then created pick-up requests can`t edited or deleted. delete method is not mandatory, if save method is not in use. calculate method is not mandatory, if save method is not in use. In case if calculate method is not realized, integration allows to specify track number at the order and track it only manually. shipmentPointList method is not mandatory, if "selfShipmentAvailable": false. Transferring of identical values for different methods is not allowed.

In the field integrationModule[integrations][delivery][requiredFields] the fields array is forwarded, which need to be obligatory to fill for current delivery. Possible values:

List of available payer types can be specified in the field integrationModule[integrations][delivery][payerType]. In case of cash on delivery there are two payer types:

  1. Sender sender - COD sum includes delivery and items costs. Delivery services are paid by shop.
  2. Receiver receiver - COD sum includes only order items cost. Delivery cost in save request is 0. Delivery service must take COD sum from recipient and then take payment for delivery services from recipient directly.

Parameter integrationModule[integrations][delivery][selfShipmentAvailable] allows you to activate shipment terminal`s field. If true, field will be added in the order`s card. This field contains list of shipment terminals, received by method shipmentPointList. Also, default shipment terminal for each warehouse can be specified at the integration settings page. Usually in calculate and save methods address of selected shipment warehouse is sent as shipping address. When one of the shipment terminals is selected - then terminal`s id is sent in shipping address.

Response:

{
    "code": "generic.delivery-service-code",
    "success": true,
}

Multi account support

Delivery services must provide opportunity to connect several accounts of client. For this purpose it is necessary to use method of getting the integration module. In case if integration is already registered and clientId doesn't match the current one, then it is needed to transfer delivery service code with postfix, providing the code uniqueness, to integrationModule[code] parameter (integrationModule[integrationCode] must remain unchanged). In this case new integration module will appear and client will have opportunity to work with any number of accounts in delivery service, which will be represented as delivery types. Also it is recommended to transfer description to integrationModule[integrations][delivery][description] field, which helps user to distinguish several similar integrations with different accounts (for example, it is possible to transfer several last figures of contract number or user account number "Contract number - ***42").

Formation of additional fields

Integration allows to forward an improvised set of fields in configuration, which will be read out in customer card. Field integrationModule[integrations][delivery][deliveryDataFieldList] contains list of fields, that will displayed in order card. If editable=true - fields data will be transferred when forming a delivery. If affectsCost=true - field data will be transferred upon delivery cost calculation. In integrationModule[integrations][delivery][shipmentDataFieldList] can be specified set of fields, that will be displayed in delivery shipment card (when creating pick-up request). List shipmentDataFieldList element`s format is identical to deliveryDataFieldList element`s format.

Unobliging editable text field:

{
    ...
    "deliveryDataFieldList": [
        {
            "code": "textField",
            "label": "Text field",
            "type": "text",
            "required": false,
            "affectsCost": false,
            "editable": true
        }
    ]
}

Informational text field:

{
    ...
    "deliveryDataFieldList": [
        {
            "code": "textField",
            "label": "Insurance size",
            "type": "text",
            "required": false,
            "affectsCost": false,
            "editable": false
        }
    ]
}

The field is displayed in order card. Can be filled when getting responce to delivery formation query and when refreshing delivery status.

Compulsory editable numerical field. As affectsCost=true - the field is believed to influence delivery cost and field value is forwarded in delivery cost calculation query:

{
    ...
    "deliveryDataFieldList": [
        {
            "code": "integerField",
            "label": "Number of packages",
            "type": "integer",
            "required": true,
            "affectsCost": true
        }
    ]
}

Checkbox:

{
    ...
    "deliveryDataFieldList": [
        {
            "code": "checkboxField",
            "label": "Switch",
            "type": "checkbox",
            "required": false,
            "affectsCost": true
        }
    ]
}

Multiple selection field:

{
    ...
    "deliveryDataFieldList": [
        {
            "code": "services",
            "label": "Delivery services",
            "type": "choice",
            "multiple": true,
            "choices": [
                {
                    "value": "ER3",
                    "label": "Inspecting"
                }
                {
                    "value": "RQW",
                    "label": "Delivery on weekend"
                }
            ],
            "affectsCost": true
        }
    ]
}

Autocomplete field. To use it you need to implement the method of getting hints and forward method url:

{
    ...
    "deliveryDataFieldList": [
        {
            "code": "types",
            "label": "Type of cargo",
            "type": "autocomplete",
            "autocompleteUrl": "http://selivery.service.com/api/autocomplete/types"
        }
    ]
}

Field with date:

{
    ...
    "deliveryDataFieldList": [
        {
            "code": "dateSimple",
            "label": "Delivery date",
            "type": "date"
        }
    ]
}

Get integration configuration

Method allows to get delivery service integration module data GET /api/v5/integration-modules/{code}.

Delivery cost calculation

For delivery cost calculation the system initiates POST-call of method specified in integrationModule[integrations][delivery][actions]["calculate"].

Delivery cost calculates when popup with list of delivery methods is opened.

If there is not enough data sent for some tariffs, delivery service may not forward cost, parameter for the tariff, but send a message for customer in description parameter. In this case the tariff will be not available for choice, but will be shown in the tariff list. If delivery service has no opportunity to calculate delivery cost, it is necessary to transfer integrationModule[integrations][delivery][rateDeliveryCost] parameter with false value, when configuring the integration, in this case cost delivery cost should not be transferred and cost will be calculated by rules specified in delivery type on the system's side.

Delivery creating and editing

For new delivery creating the system initiates POST query of the method specified in integrationModule[integrations][delivery][actions]["save"]. Delivery editing query is the same as the creation query, you need to send save["deliveryId"] order ID in delivery service additionally.

New delivery creates when order is saved in system, and order has delivery type, integrated with current delivery service. Delivery edited when order is saved, delivery for order already was created and there were some changes in order.

If parameter integrationModule[integrations][delivery][codAvailable]=true was specified when registering delivery integration module, then, depending on the payment type selected in the order, cash on delivery data could be sent. save[delivery][withCod] indicates is there a need to take COD sum from recipient. Total COD sum is defined as sum of save[packages][][items][][cod] by all items (be aware - the value in this field is amount of the COD payment per unit of the item), and COD payment for delivery services save[delivery][cod].

Getting delivery data

For new delivery creating the system initiates GET query of the method specified in integrationModule[integrations][delivery][actions]["get"]

Method used when new order is created or order is edited through the system`s API, and id of created delivery is received in order[delivery][data][externalId].

Delivery request deletion

For delivery deletion the system initiates POST query of the method specified in integrationModule[integrations][delivery][actions]["delete"].

Delivery deletes when order is in not in status from final status groups (Complete or Cancel), delivery status is editable (isEditable=true) and delivery type is changed or order has been transferred to status from Cancel group.

Delivery statuses refreshing

For delivery statuses refreshing, delivery service should use method POST /api/v5/delivery/generic/{subcode}/tracking. The method allows to forward statuses separately for each order at the moment of status change or send changes history of orders group after definite intervals at the delivery service discretion.

Important: You can refresh statuses for not more than 100 orders at a time. The system will respond with an error message if forwarding larger orders amount.

Delivery service printed forms

For printing forms specified in configuration integrationModule[integrations][delivery][plateList] the system initiates POST query of the method specified in integrationModule[integrations][delivery][actions]["print"].

The request is sent when the delivery service documents are printed from the order card, or from the order list.

Delivery service should form a pdf-file of the printed form and send it back in the form of byte array. Also you can send back zip-archive with set of documents, is this case content-type of response should be application/zip.

Dispatchment receiving terminals list

For working with terminals the system initiates GET query of the method specified in integrationModule[integrations][delivery][actions]["shipmentPointList"].

Requests is sent when shipment terminal is selected in order card.

Creation and editing of pick-up request

To create or edit pick-up request the system initiates POST query of the method integrationModule[integrations][delivery][actions]["shipmentSave"]

Request is sent when new delivery shipment is created or changed. If path to method integrationModule[integrations][delivery][actions]["shipmentDelete"] was not specified, then created delivery shipment can`t be changed or deleted.

Removing of pick-up request

To remove pick-up request the system initiates POST query of the method integrationModule[integrations][delivery][actions]["shipmentDelete"]

Request is send when delivery shipment status is changed to Cancel.

Data receiving query for field autocomplete

When working with autocomplete fields specified in integrationModule[integrations][delivery][deliveryDataFieldList] the system will initiate query to delivery service using GET query of the method specified in autocompleteUrl configuration of the proper field.

Integration work checking

It’s necessary to check module work in the account eComlogic before module will be publicated in marketplace. You need to choose a delivery type in an order, which is integrated with your module before checking. It’s necessary to check module work when introduction of correct or incorrect data (last dates, zero weight etc). Module has to show an error, issued by rules of work with API, which contains a message with a problem description, which the user will understand ( for example, if the user specified the last delivery date, the message has to say about it).

Checking of reception of sendings terminal order

It’s necessary on condition of integrationModule[integrations][delivery][selfShipmentAvailable] = true.

You should choose a shipment warehouse in an order and check a reception terminal order is loaded without errors.

Checking of data getting for an autocomplete field

It’s necessary if in additional fields order integrationModule[integrations][delivery][deliveryDataFieldList] there are fields which have type="autocomplete".

You can find this field in a delivery block in an order and then you should check that values list is loaded without errors.

Checking of the calculation of the delivery cost

It’s necessary if the way for calculate method was passed in integrationModule[integrations][delivery][actions][].

It’s necessary to check work of the cost calculation in the following cases:

The work result for every case must be a message about data error or tariff list which the user will understand.

Checking of creating/editing of delivery application

It’s necessary if the way for save method was passed in integrationModule[integrations][delivery][actions][].

It’s necessary to choose an integrated delivery type in an order and fill order data for delivery application creating.

It’s necessary to change order data in an order, where delivery application was chosen for order editing.

It’s necessary to check the following cases for delivery application editing/creating:

The work result of every case must be a message about data error which the user will understand or successful saving of an order and getting of a departure number for an order. After saving an order it’s necessary to check that all transfered parameters which delivery serves can process are got without errors.

Checking of printed forms

It’s necessary if the way for print method was passed in integrationModule[integrations][delivery][actions][] and the order of available printed forms integrationModule[integrations][delivery][plateList] is not empty.

It’s necessary to check document print in an order on in an order list for several orders (if integrationModule[integrations][delivery][platePrintLimit] > 1) for all document types.

Checking of delivery application deleting

It’s necessary if the way for delete method was passed in integrationModule[integrations][delivery][actions][].

It’s better to check deleting if you change the order status on cancelled in an order with delivery.

Checking of delivery data getting

It’s necessary if the way for get method was passed in integrationModule[integrations][delivery][actions][].

For this checking in your service there should be a created application for delivery with a known number. Send a request for creating an order in the system with API and send the number of the shipment in the request (order[delivery][data][externalId]). As a result, an order with a formal delivery request must be created in the system, in which all necessary shipping information from your service is loaded.

Example of the simplest order creation request:

{
    "lastName": "test",
    "delivery": {
        "code": "<delivery_type_code>",
        "data": {
            "externalId": "<delivery_external_id>"
        }
    }
}

Checking the creation/editing of the application for the products removal

It’s necessary if the way for shipmentSave method was passed in integrationModule[integrations][delivery][actions][].

It’s necessary to check the following cases:

Checking the editing of the application for the removal of products

It’s necessary if the way for shipmentDelete method was passed in integrationModule[integrations][delivery][actions][].

To delete an order for shipment, change the status of the order on cancelled.


PrintEditHistory
Page last modified on February 26, 2018, at 02:26 PM