integrationModule[integrations][delivery][shipmentDataFieldList][] has been added. Array can contain list of additional fields, used when creating pick-up request.
- 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.
integrationDeliveryData.shipmentpointName in object Configuration in list of required fields requiredFields.
rateDeliveryCost (true by default) has been added to Configuration. false value is needed for case, if delivery service doesn`t calculate delivery cost and calculate method returns only information on available tariffs. Also the possibility not to specify the path for calculate method has been added (path for save method also should not be specified). In this case integration allows to enter the track number manually and synchronize the delivery statuses.
availableShipmentCountries has been added to Configuration it is a list of countries, from which the sending is available. By default the array is empty, what means there are no restrictions on sending country.
save method now, delivery address is being transferred besides pickup point code.
calculate method request the extraDataAvailable field has been added - fields codes array from configuration["deliveryDataFieldList"] list, transferred in delivery configuration request. When choosing the tariff at order, all fields, which are absent in extraDataAvailable array, will be hidden.
description has been added to Configuration - it may be used for transferring of integration description, including determining which delivery service account the integration relates to. Transferred value is displayed in integration settings and in the list of available integrations at delivery type page;
deliveryConfigurationUrl has been added to Configuration - it contains url, by which the user can go to integration settings on delivery service`s side;
hint has been added to DeliveryDataField object - there can be transferred clarification for user how and when this field should be used. It is displayed at the order under appropriate field;
currency field, containing currency code, has been added in RequestCalculate and RequestSave objects;
siteName field (shop name) and optional field legalEntity (legal entity name) has been added in RequestSave object;
offerId field (offer identifier in the system) has been added in PackageItem object in request for delivery creation;
ContentType header of response should take the value application/zip.
The system API allows to:
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:
USER Request the API-key of user for access to the system
API Register new delivery integration module
USER Make the necessary settings on the integration settings page in the system
USER Create delivery type related with new integrated delivery service
SYSTEM Requests on creation and editing of orders on delivery will be initiated by system in working process of user
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 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:
apiKey - system API-key
integrationModule - json with basic integration module data
integrationModule[integrations][delivery] - delivery service integration settings
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:
calculate - delivery cost calculation method
save - delivery creating/editing method
get - delivery data getting method. Not necessary for realization - may be not forwarded
delete - delivery deletion/cancel method. The method is called if order was cancelled, or if order delivery type was changed.
print - method of printing documents. Not necessary for realization - may be not forwarded.
shipmentPointList - Shipment terminals list getting method. Not necessary if "selfShipmentAvailable": false
shipmentSave - creation|editing of pick-up request method.
shipmentDelete - removing of pick-up request method.
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:
lastName - customer surname
patronymic - customer patronymic
phone - customer phone number
email - customer email
length - length
width - width
height - height
shipmentDate - date of shipment
manager - order manager
deliveryAddress.regionId - when selecting region oblige to choose region from the dropdown list. The region ID at geohelper service will be in this field (http://geohelper.info/ru/doc/api#get--api-v1-regions)
deliveryAddress.cityId - when selecting city oblige to choose city from the dropdown list. The city ID at geohelper service will be in this field (http://geohelper.info/ru/doc/api#get--api-v1-cities)
deliveryAddress.street - delivery street name
deliveryAddress.streetId - when selecting street oblige to choose street from the dropdown list. The street ID at geohelper service will be in this field (http://geohelper.info/ru/doc/api#get--api-v1-streets)
deliveryAddress.flat - flat
deliveryAddress.index - postal index
integrationDeliveryData.shipmentpointName - shipment terminal
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:
sender - COD sum includes delivery and items costs. Delivery services are paid by shop.
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,
}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").
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"
}
]
}Method allows to get delivery service integration module data GET /api/v5/integration-modules/{code}.
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.
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].
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].
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.
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.
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.
When required to display an error message to the user, the response should have a 400 code. The content of the response should be the standard response with the error message.
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.
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.
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.
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.
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).
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.
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.
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:
integrationModule[integrations][delivery][codAvailable]=true)
integrationModule[integrations][delivery][allowPackages]=true)
integrationModule[integrations][delivery][payerType])
The work result for every case must be a message about data error or tariff list which the user will understand.
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:
integrationModule[integrations][delivery][selfShipmentAvailable]=true)
integrationModule[integrations][delivery][codAvailable]=true)
integrationModule[integrations][delivery][allowPackages]=true)
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.
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.
When required to display an error message to the user, the response should have a 400 code. The content of the response should be the standard response with the error message
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.
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>"
}
}
}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.