Procedure for integrating delivery service via API

Copy the link to the article

Copied

Under construction

History of changes

04/28/2019

Added the field integrationModule[integrations][delivery][settings] to the methods GET / api / v5 / integration-modules / {code} , POST / api / v5 / integration-modules / {code} / edit ... It allows you to get or update the integration delivery settings.

03/04/2019

In the method Callback POST {integrationModule["baseUrl"]}/{configuration["actions"]["calculate"]} (reference to the method ) in the object RequestCalculate added the transfer of the contents of the package calculate[packages][][items][].

The following fields have been added to the PackageItem object: externalId - trade offer ID in the store, xmlId - trade offer ID in the warehouse system. Object PackageItem is used in methods: Callback POST {integrationModule["baseUrl"]}/{configuration["actions"]["calculate"]} (method reference ) and Callback POST {integrationModule["baseUrl"]}/{configuration["actions"]["save"]} ([method reference [[TRANSLATE_PLACEHOLDER_980]

11/14/2017

In the POST / api / v5 / integration-modules / {code} / edit method, the integrationModule[integrations][delivery][shipmentDataFieldList][] array has been added - a list of additional fields used to create a shipment request.

Added callback methods for working with the shipment of orders to the delivery service:

• POST {integrationModule["baseUrl"]}/{configuration["actions"]["shipmentSave"]} (link to method ) create / edit shipping request
• POST {integrationModule["baseUrl"]}/{configuration["actions"]["shipmentDelete"]} (method reference ) deleting shipment request

To be able to work with these methods, in the POST / api / v5 / integration-modules / {code} / edit method in the integrationModule[integrations][delivery][actions][] parameter, pass the paths for the shipmentSave and [[TRANSLATE_PLACEHOLDER_845] methods ]].

27.09.2017

In the object Configuration in the list of required fields requiredFields, it is possible to specify the required field "Terminal of shipment", for this, add the value integrationDeliveryData.shipmentpointName to the list.

09.06.2017

Added the transfer of VAT rates to the RequestSave object of the delivery request: save[packages][][items][][vatRate] - VAT rate for goods in the order. save[delivery][vatRate] - VAT rate for delivery service. Both of these fields can take the value none which means that the goods / delivery service is not subject to VAT.

03/22/2017

An optional boolean field rateDeliveryCost has been added to Configuration (by default true). The value false is needed if the delivery service does not calculate the shipping cost and the calculate method only returns information about available rates. Also added the ability not to specify the path for the calculate method (the path for the save method should not be specified either). In this case, the integration allows you to manually enter the shipment number and synchronize delivery statuses.

An optional array Configuration has been added to Configuration - it specifies a list of countries from which shipment is available. By default, the array is empty, which means that there are no restrictions on the sending countries.

When registering delivery to a pickup point via the save method, now, in addition to the pickup code, the delivery address is transmitted.

In the response to the request for the calculate method, the field extraDataAvailable has been added - an array of field codes from the list configuration["deliveryDataFieldList"] passed in the delivery configuration request. When choosing a rate in the order card, all fields that are not in the array extraDataAvailable will be hidden.

03/01/2017

An optional text field Configuration has been added to Configuration - it can be used to transfer the description of the integration, including to determine which account in the delivery service the integration belongs to. The passed value is displayed in the integration settings and in the list of available integrations in the delivery type card;

An optional field has been added to Configuration deliveryConfigurationUrl - contains the url by which the user can go to the integration settings page on the delivery service side;

An optional text field hint has been added to the request for creating / editing the integration configuration in the DeliveryDataField object - an explanation for the user how and when to use this field can be sent. Displayed in the order card under the corresponding field;

In the objects RequestCalculate and RequestSave added the field currency containing the currency code;

In the RequestSave object, added the siteName field (store name) and the optional legalEntity (Seller's legal entity name);

Added the field offerId to the request for registration of delivery in the object PackageItem - offer identifier in the system

In response to a request for receiving printable forms of a delivery service, you can now send a zip archive, for this the response header ContentType must take the value application/zip.

Integration options

The system API allows:

1. Calculate the cost of delivery according to the order data at the request of the system user
2. Give the user of the system the set of terminals relevant for the given order
3. Form different packages within one delivery order
4. Form an order for delivery, transferring the necessary information about the order to the delivery service
5. Edit and delete a delivery order in certain statuses at the request of the system user
6. Bulk update statuses for unfinished orders
7. Submit documents for printing on orders from delivery services at the user's request
8. Create, edit and delete orders for the collection of goods by the delivery service

Working with the API is performed in accordance with the rules for working with API ]. For integration, API methods of the Delivery and Integration section are used.

For integration you need:

1. USER Request an API key from the user to access the system
2. API Register a new shipping integration module
3. USER Make the necessary settings on the system integration settings page
4. USER Create a shipping type associated with a new integration shipping
5. SYSTEM Requests related to creating and changing delivery orders will be initiated by the system during the user's work
6. API Send up-to-date data on delivery statuses

Stages marked with USER are stages where data is provided or filled in by the user. Stages marked with API are performed through API requests from the delivery service through the system API. The stage marked SYSTEM implies requests made by the system to the delivery service, taking into account the settings specified during registration.

If an error occurs during an API request to the delivery service, you must return a response (HTTP status 200) in the format:

{
 "success": false,
 "errorMsg": "Текст ошибки" // Сообщение об ошибке. Будет отображаться пользователю в карточке заказа
}

If, in response to a request for calculating the cost of delivery or in response to a request for order data from the delivery service server, an invalid response was returned, information about this will be recorded in the Action log , record type "Integration deliveries".

To identify regions, cities and streets, in addition to text names, identifiers from the Geohelper service are transmitted.

Registration and delivery service configuration

Registration of a new delivery, as well as changing the settings of an existing one, is performed using the POST / api / v5 / integration-modules / {code} / edit method. If the integration module with the code code already exists, the method changes its parameters, otherwise a new module is created. When registering a delivery, a unique code integrationModule[clientId] is transmitted, which will allow the delivery service to identify the system account.

Options:

• apiKey - system API key
• integrationModule - json containing the description of the integration module
• integrationModule[integrations][delivery] - configuration settings for integration with delivery service

The integrationModule[integrations][delivery][actions] field as an associative array ("Код метода": "Путь") specifies the paths to specific methods. List of methods:

• calculate - Shipping cost calculation method
• save - Delivery creation / editing method
• get - Method for receiving delivery data.
• delete - Method for deleting / canceling delivery. Called if the order has been canceled, or if the delivery type for the order has been changed.
• print - Method for printing documents.
• shipmentPointList - Method for obtaining a list of shipping terminals.
• shipmentSave - Method for creating / editing a shipment request.
• shipmentDelete - Method for deleting a shipment request.

Some methods are optional. If they are not required for integration, they can be omitted in the actions array. The methods save, get, print, shipmentSave, shipmentDelete are optional. If the save method is not passed, then delivery requests are not sent. If the shipmentDelete method is not passed, then you will not be able to edit and delete the shipment request. The delete method is optional unless the save method is used. The calculate method is optional unless the save method is used. If the calculate method is not implemented, the integration allows only manually specifying the shipment number in the order card and performing tracking. The shipmentPointList method is optional if "selfShipmentAvailable": false. It is not allowed to pass the same values ​​for different methods.

The integrationModule[integrations][delivery][requiredFields] field contains an array of fields that must be mandatory for this delivery. Possible values:

• lastName - Buyer's last name
• patronymic - Buyer's middle name
• phone - Buyer's phone number
• email - Buyer's E-mail
• length - Length
• width - Width
• height - Height
• shipmentDate - Date of shipment
• deliveryTime.from - Start of delivery time interval
• deliveryTime.to - End of delivery time interval
• manager - Order Manager
• deliveryAddress.regionId - When choosing a region, you must select a region from the drop-down list. This field will contain the region identifier in the geohelper service (http://geohelper.info/en/doc/api#get--api-v1-regions)
• deliveryAddress.cityId - When choosing a city, oblige to select a city from the drop-down list. This field will contain the city identifier in the geohelper service (http://geohelper.info/en/doc/api#get--api-v1-cities)
• deliveryAddress.street - Delivery street name
• deliveryAddress.streetId - When choosing a street, oblige to select a street from the drop-down list. This field will contain the street identifier in the geohelper service (http://geohelper.info/en/doc/api#get--api-v1-streets)
• deliveryAddress.flat - Apartment
• deliveryAddress.index - Postal code
• integrationDeliveryData.shipmentpointName - Terminal of shipment

In the field integrationModule[integrations][delivery][payerType] you can specify an array of possible types of payers for delivery. In the case of delivery by cash on delivery, depending on the type of payer, there are 2 options for payment for delivery:

1. Payer sender sender - cash on delivery includes the cost of delivery and the cost of goods. Delivery services are paid for by the store.
2. Payer - recipient receiver - only the cost of goods in the order is included in cash on delivery. The delivery cost is always 0. It is understood that the delivery service will have to take from the buyer the transferred amount of cash on delivery in favor of the store and separately the cost of delivery in its favor.

The integrationModule[integrations][delivery][selfShipmentAvailable] parameter allows you to activate work with shipping terminals. If the value true is passed, a field will appear in the order card where you can select a shipping terminal from the list obtained by the shipmentPointList method. Also, in the integration settings, the user can set default shipping terminals for each of his warehouses. When calculating the cost and registering delivery, the address of the shipping warehouse specified in the order card is usually sent as the shipping address. In the case when the shipping terminal is selected for the order, only the code of the selected shipping terminal is sent in the shipping address data.

Answer:

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

Support for multiple accounts

The delivery service should provide for the ability to connect multiple customer accounts. To do this, before sending a request for registration of the delivery integration module, use the obtaining information about the integration module method. If the integration is already registered and clientId does not match the current one, then you need to transfer the delivery service code to the integrationModule[code] parameter with a postfix that ensures the uniqueness of the code (integrationModule[integrationCode] should remain unchanged) ... In this case, a new integration module is created and the client will be able to work with any number of accounts in the delivery service, which will be presented as different types of delivery. It is also recommended to transmit a description in the integrationModule[integrations][delivery][description] field that will help the user to distinguish several identical integrations with different accounts (for example, you can transmit the last few digits of the contract number or the user account number "Номер договора -***42").

Formation of additional fields

Integration allows you to transfer in the configuration to produce an arbitrary set of fields. The field integrationModule[integrations][delivery][deliveryDataFieldList] lists the fields that will be displayed in the order card. If editable=true - the data of the edited fields will be transmitted when forming the delivery. If the parameter is affectsCost=true, these fields will be transmitted when calculating the shipping cost. The integrationModule[integrations][delivery][shipmentDataFieldList] field contains a set of fields that are used when working with shipment. The format of the list items shipmentDataFieldList is completely identical to the format of the items deliveryDataFieldList.

Optional editable text field:

{
 ...
 "deliveryDataFieldList": [
 {
 "code": "textField",
 "label": "Текстовое поле",
 "type": "text",
 "required": false,
 "affectsCost": false,
 "editable": true
 }
 ]
}

Informational text box:

{
 ...
 "deliveryDataFieldList": [
 {
 "code": "textField",
 "label": "Размер страховки",
 "hint": "Использовать только при международно доставке",
 "type": "text",
 "required": false,
 "affectsCost": false,
 "editable": false
 }
 ]
}

The field is displayed in the order card. It can be filled in when receiving a response to a delivery generation request or when updating the delivery status.

Mandatory editable numeric field. Because affectsCost=true - the field is considered to affect the shipping cost and the value of the field is sent in the request to calculate the shipping cost:

{
 ...
 "deliveryDataFieldList": [
 {
 "code": "integerField",
 "label": "Число мест",
 "type": "integer",
 "required": true,
 "affectsCost": true
 }
 ]
}

Checkbox:

{
 ...
 "deliveryDataFieldList": [
 {
 "code": "checkboxField",
 "label": "Переключатель",
 "type": "checkbox",
 "required": false,
 "affectsCost": true
 }
 ]
}

Multiple choice field:

{
 ...
 "deliveryDataFieldList": [
 {
 "code": "services",
 "label": "Сервисы доставки",
 "type": "choice",
 "multiple": true,
 "choices": [
 {
 "value": "ER3",
 "label": "Осмотр"
 }
 {
 "value": "RQW",
 "label": "Доставка на выходных"
 }
 ],
 "affectsCost": true
 }
 ]
}

Autocomplete field. To use it, you need to implement a method for receiving hints and pass the url of the method:

{
 ...
 "deliveryDataFieldList": [
 {
 "code": "types",
 "label": "Тип груза",
 "type": "autocomplete",
 "autocompleteUrl": "http://selivery.service.com/api/autocomplete/types"
 }
 ]
}

Date field:

{
 ...
 "deliveryDataFieldList": [
 {
 "code": "dateSimple",
 "label": "Дата доставки",
 "type": "date"
 }
 ]
}

Settings configured by the module

Integration allows you to transfer a set of settings in the configuration. The integrationModule[integrations][delivery][settings] field lists the fields that are configured by the module. It is recommended to give the ability to configure all the parameters on the module side and transfer to the system through this field. The transferred settings will be hidden in the module integration settings in the system.

Settings:

• defaultPayerType - Default shipping payer
• costCalculateBy - Default shipping cost (Possible auto | manual values)
• nullDeclaredValue - Zero declared value by default
• lockedByDefault - By default, do not send data to the delivery service
• paymentTypes - Payment methods (Object directory )
• shipmentPoints - Warehouses (Object Directory )
• statuses - Correspondence of statuses (Object directory )
• deliveryExtraData - Additional default shipping fields
• shipmentExtraData - Additional default shipment field values

An example of setting the settings:

{
 "defaultPayerType": "sender",
 "costCalculateBy": "auto",
 "nullDeclaredValue": true,
 "lockedByDefault": true,
 "paymentTypes": [
 {
 "code": "cash",
 "active": true,
 "cod": true

}
 ],
 "shipmentPoints": [
 {
 "code": "online",
 "shipmentPointId": "1234",
 "shipmentPointLabel": "Test"

}
 ],
 "statuses": [
 
{

 "code": "new",
 "trackingStatusCode": "new"

}
 ],
 "deliveryExtraData": {
 "passport": "0000 000000"
 },
 "shipmentExtraData": {
 "count": "5"
 }
}

Get the integration configuration

The method allows you to get the data of the integration module of the delivery service GET / api / v5 / integration-modules / {code} .

Calculation of shipping costs

To calculate the shipping cost, the system initiates a POST call to the method specified in the integrationModule[integrations][delivery][actions]["calculate"] configuration.

The cost is calculated when you open a popup with a list of delivery methods.

If there is not enough transmitted data for some tariffs, the delivery service may not transmit the cost parameter for the tariff, but transmit a message to the user in the description parameter. In this case, the tariff will not be available for selection, but will be displayed in the list of tariffs. If the delivery service does not have the ability to calculate the delivery cost, when configuring the integration, you can pass the integrationModule[integrations][delivery][rateDeliveryCost] parameter with the value false, in this case you do not need to transfer the delivery cost and the cost is determined according to the rules specified in the delivery type on the outside systems.