Revision History

January 15, 2021

The history of statuses using the "Order statuses" method can be obtained only for orders created not earlier than 2020.

The provision of the additional service "Attachment Inspection" has been discontinued. Additional service is always active for online stores.
A new additional service is available in the "Order registration", "Calculator" - "Disable attachment inspection" methods. An additional service is available for online stores. Disable Attachment Inspection is incompatible with Fitting at Home and Partial Delivery.

The service is not transferred until the checkpoint.

Introduction

General Description

This document presents a procedure and format of data exchange between CDEK and its client — an online store or a partner representing online stores.

Answers to frequently asked questions can be found at https://www.cdek.ru/faq_integrator.html.

We accept questions and wishes of clients by e-mail: integrationtor@cdek.ru.

Symbols

Terms and Definitions

IS means any information system, including software, ERP solution, and online store website.

Integration means a transfer of data from different sources (IS) or provision of unified data to users.

API means an Application Programming Interface. It is a set of ready-made functions, structures and constants provided by an application (library, service) to be used in third-party software (IS).

HTTP means a Hyper Text Transfer Protocol. It is an application-layer communication protocol (originally in the form of HTML hypertext documents).

HTTPS means a Hyper Text Transfer Protocol Secure, an extension of the HTTP protocol that supports encryption. Data communicated via HTTP are “packed” into a SSL or TLS cryptographic protocol. In contrast to HTTP, HTTPS uses a ТСР port 443 by default.

Online store means a client or partner of CDEK who has concluded an online store contract.

Package is an indivisible unit of cargo sent by the online store (there may be several packages in a single order).

Shipment (order) is a sum of all packages that are simultaneously sent by the online store to the same direction.

Volumetric weight is an estimated value of weight in kg. It can be estimated on the basis of specified package dimensions according to the following formula: length * height * width/5,000. This conversion method is commonly used by carriers.

Actual weight is determined by weighing a package on a scale. Net weight and gross weight are used. Net weight is the weight of cargo without package. Gross weight is the weight of packaged cargo.

Estimated weight means the greater of volumetric weight and actual weight. Services are priced on the basis of the estimated weight.

Pickup point means a place at which receivers can pick up their orders. Pickup points may be CDEK warehouses or parcel terminals of partners.

CDS means the CDEK Courier Delivery Service.

International Order is an order where the sender country is not the same as the receiver country, and at least one of the countries is not a member of the Customs Union.

What You Should Know to Make the Integration Work

Step 1: Integration is possible only if there is an agreed contract with CDEK.

Step 2: An online store's representative should examine the documents and frequently asked questions presented on the website https://www.cdek.ru/clients/integrator.html

Step 3: Select an appropriate integration option that best suits your needs:

• Use ready-made partner modules presented on the company's website.

• Implement your own solution if ready-made solutions do not suit you for some reason.

Step 4: Test and set integration using a test account.  

• If you have selected a ready-made partner module and need advice on configuration, please refer to the developer or support service of this module.

• If you want to implement your own solution, you should try all preliminary settings under your test account.

Step 5: After everything has been verified (tested, all problems are resolved), you should receive an access key to the "combat" account (Account and Secure password) for integration. The keys can be obtained in your CDEK personal account at the link: https://lk.cdek.ru/integration/index. To do this, in your personal account in the "Integration" section, click the "Create a key" button, after which the account ID and password will appear in this section.

Step 6: You can switch over to the live account and work in the normal mode.

1. General Provisions

XML API is a solution that allows you to interact with the service online using standard НТТР/НТТРS, as well as XML protocols and formats.

XML API supports the following functionality:

1. List of Pickup Points can be used to load the actual list of pickup points with detailed information to be processed in the online store's IS.

2. Order Registration can be used to orders in the CDEK database on the basis of Client's order details contained in acceptance certificates/waybills. The entire transportation process will be based on these orders.

3. Order Update can be used to change a created order. The following details can be changed in the order: cash on delivery amount, all details of packages and items.

4. Order Deletion allows the user to delete orders from the CDEK database in case they have been imported by mistake or changed significantly. An order can be deleted only if there is no cargo movement in the CDEK warehouse (order status “Created”).

5. Printed Form of Order Receipt can be used to create a printed order receipt form in pdf format.

6. CourierInvitation: a document containing details of courier invitation, if the cargo is to be picked up from an online store's warehouse. The cargo is delivered to the CDEK warehouse.

Conditions for generating a courier invitation:

• for one day, only one courier invitation per address is possible;

• a time range for courier arrival may not be less than 3 hours.

The online store makes a preliminary notification call to the specified phone number to confirm a courier invitation and confirm the specified details.

7. Notification Call Results: a document containing results of a notification call to the receiver to agree on delivery-to-door or pickup conditions (acceptance of cargo) from the warehouse, depending on a delivery mode.

This document is used in the following cases:

• the online store provides a receiver's schedule for delivery /pickup;

• changes in receiver's details (contact person, delivery address, phone number);

• change in the amount payable for the goods.

Details are transferred for the existing orders in the CDEK databases. In the document “List of Orders for Delivery”, information on the notification Call to the Receiver can be transmitted for new orders. A delivery schedule can be transferred only for one day.

If an attempt to deliver the cargo on schedule has failed, the online store sends a delivery schedule again. Failed attempts of delivery are reported by the online store in the Order Status document (Reasons for Late Delivery).

8. Printing a Package Barcode is used to generate a printed label form in pdf format.

9. Order Status Report: allows the user to track the following details of orders:

• last status of a delivery or return order in the specified period;

• full status history for a delivery or return order;

• last status of a return order;

• full status history for a return order;

• details of parcel delivery (when, to whom);

• failed delivery attempts as compared to a delivery schedule provided by the online store.

A request can be generated both for a certain period in which statuses have changed and for a particular list of parcels.

10.  Order Information Report allows the user to track the following order details:

• tariff code under which the order has been delivered;

• price of CDEK services invoiced for the order (i.e. invoiced amount);

• date of the last change in the order amount;

• method of order delivery to the receiver (courier, pickup);

• type of cash on delivery payment.

11. List of Regions - is used to load detailed information on regions.

In order to load the list of regions, it is necessary to send request on the CDEK server.

12. List of Cities - is used to load detailed information on cities.

In order to load the list of regions, it is necessary to send request on the CDEK server.

13. Calculator allows to calculate the delivery cost of one shipment for the defined input parameters.

1.1. Parcel Identifiers and Label Information

The CDEK would prefer that the client uses CDEK labels (order receipts), which can be loaded in PDF format via XML API. If the client prefers to use its own label, this label must contain receiver's details (full name, address, phone number) and any of identifiers:

• CDEK parcel identifier. It is recommended that the CDEK order number is indicated in a barcode (it is a DispatchNumber attribute in the data exchange format).
• Identifier of an online store's order is the order number (Order. Number attribute).
• Package identifier is a package barcode (Package.BarCode attribute).

All barcodes must be provided with an explanation of an encoded text above or below a barcode so that encoded information can be entered manually. We recommend using code 128 for printing.

1.2. Retention Period for Information in the System

Information on parcels that are not in progress (status “Created”) is stored in the CDEK system within 30 days from the date of acceptance for the live account and one day for the test account. Information is deleted automatically every day at 23:00 NSK (GMT+7). Therefore, a request for creating delivery orders must be sent before the actual shipment of the goods.

1.3. Data Formats and Coding

Units:

Type of data:

Float — floating-point number. A dot, rather than a comma, is used as a decimal separator.

String — a string of characters of a given length. The string length is indicated in parentheses.

Integer — integral number

Boolean — Boolean values that can be equal to 0 or 1.

In all modules, date/time are transmitted in the format UTC (YYYY-MM-DDТhh:mm:ss), unless otherwise specified in the description.

Date Time — date and time in the format ISO 8601:2004:YYYY-MM-DDThh:mm:ss+hh:mm.

EXAMPLE: December21, 2012 , 11 hours 49 minutes 49 seconds, Moscow time should be transmitted as: 2012-12-21Т11:49:49+03:00

It may contain incomplete information. For example, only hours and minutes (15:30). In this case, time zone UTC+00:00 should be used.

Date — date in the format ISO 8601:2004:YYYY-MM-DD.

Time — time in the format hh:mm:ss.

Email — email address in the format RFC 2822, string length is limited to 255 characters.

Attention! Cyrillic addresses are valid, for example: пример@пример.рф (see page 0).

Phone — phone number. Approximate format for the RF: +7 (ХХХ) ХХХ-ХХ-ХХ, string type

Data are transmitted in the XML format in UTF-8 encoding. Please note that XML markup symbols (< > & " ') may not be entered in fields.

1.4. Client Authorization

All function calls, except for reference data, require the authorization through account data assigned to the client during the registration with the CDEK system. For registration, account data should be requested from online store’s representatives or a CDEK manager.

The online store is identified with two parameters:

To ensure the security of data transfer/request, the online store must transmit a value of the secure field, calculated according to the algorithm:

secure = md5(date.'&'. secure password), where

secure password is a security code provided by CDEK at request;

date is the document date.

All requests must be made under a single account. For example, if a request for order creation is sent through the test account, generation of a printed form and tracking must be carried out through the same test account.

If the online store is represented by several legal entities, or legal entities are substituted, each legal entity must conclude a separate contract with CDEK and, therefore, will receive its own account data.

1.5. Test Accounts and Related Restrictions

In order to facilitate the integration process, CDEK will provide separate test accounts for each client/contract:

Parcels for test accounts will not be processed and/or delivered.

The test account is tied to a test contract. Therefore, no discounts and extra charges provided for by the your contract are applicable to the test account. 

After the АPI has been implemented, integration will be tested. The test procedure consists of the following steps:

• An exchange of requests is tested by checking the data to be transmitted for correctness, as well as checking types of data and values to be transmitted in parameters of tested methods.

• Shipments are tested after the exchange of requests. This step involves sending several real orders by the online store.The full functionality, from loading the orders to delivering them to test receivers, is tested. This step is not necessary. It can be implemented as agreed upon with a CDEK manager.

Upon completion of debugging, they are notified that they are ready to switch to the combat account. At the same time, the client must have a contract with CDEK. To do this, in your personal account, in the Integration section, click the "Create Key" button, then the Account ID and Password will appear in this section.

1.6. Notifications

The online store can be notified about data transmission results by email. These notifications contain information on both successfully loaded orders and data transmission errors. The list of emails is sent to CDEK together with a request for account. The online store can unsubscribe from these notifications, but it should be noted that all data on upcoming maintenance and changes in the protocol are also sent to this email.

All notifications are sent from email: noreply@cdek.ru in the UTF-8 format.

1.7. Feedback

Contact information of CDEK Group:

Main website: http://cdek.ru.

Phone number of the Help Desk: 8-800-550-1409 (toll free).

Head Office: 101 Bolshevistskaya St., Novosibirsk 630007, Russia

If you have any questions or have found any error, please do not hesitate to contact the CDEK Technical Support Service by email address integrator@cdek.ru¹⁰. Please indicate “CDEK Integration, client ... [name of your company] and Contract No. (if any)” in the subject line.

2. CDEK Integration Algorithm for the Online Store

Recommended algorithm:

1. The online store prepares order details in its information system (IS). The online store can group orders into a single register by any parameter, for example, by date on which the cargo is handed over for delivery, or send each order separately as soon as it is created.

2. Orders with “from warehouse” tariff are registered in the Courier Delivery Service (CDS) through the IS.

3. In the IS, it is necessary to check that the CDS has accepted order details:

• if at least one order has been accepted,, the cargo can be prepared for handing over to the CDS;

• view the list of errors, make changes to orders as recommended in the list of errors, and send a request again.

4. If necessary, you can save a list of CDS order numbers in your IS (you can load it in response to an order registration request).

5. Print package barcodes and stick them on packages.

6. Print order receipts and attach them to the cargo.

7. Print an acceptance certificate, if a consolidated cargo is transferred to the CDS. You can find the acceptance certificate form in the contract or use your own one.

8. If necessary, you can invite a courier to pick up the consolidated cargo. This procedure is not required if the cargo will be delivered to the CDS by the online store itself. To invite a courier, we recommend using the request for “Courier invitation”. A courier will arrive at the address specified in the invitation form, pick up the cargo under the acceptance certificate, and take it to the CDS warehouse for further transportation.

9. After accepting the cargo to the warehouse, the CDS will deconsolidate it and deliver each cargo separately to the indicated destination and according to a chosen delivery tariff.

10. The online store can request the “Order status” in accordance with its internal regulations and display the CDS status in its IS, or compare the CDS status with the similar status of the IS and display its own status, which will be communicated to employees of the online store and the receiver.

11. In case of changing items included in the order or the cash on delivery amount, you can update your order by sending a request for update.

12. If you want to cancel an order for which no activity has been performed yet (order status “Created”), you should send a request for deletion.

13. If, under the contract, the online store shall call (inform) a receiver on its own, the online store should notify CDEK about agreed delivery by using the “Notification call to the receiver” method. The information must be transmitted when the cargo has been delivered to the receiver's city. This information is available through the Order Status Report.

14. When you receive the final status “Not delivered”, the cargo is expected to be returned to the sender. You can track the return of cargo as described in clause 9.

15. When you receive the final status “Delivered”, you may stop tracking the delivery status of the cargo.

We recommend placing a CDEK logo in a clearly visible part of the website so that receivers can identify the CDS that is delivering the cargo. Please go to https://classic.cdek.ru/website/edostavka/template/images/logo.png to load the latest version of the logo.

2.1. Interaction scheme

The process of interaction and the corresponding order statuses in the IS CDEK are presented below:

3. General Description of the API

In order to interact with the API, the online store should send a POST-request to the following URL: <basic url of the interface>/ method.

Content of the request (XML file) is sent in a variable of the POST-request or in the body of the POST-request for some methods.

An examples of a curl command for oneand another request variant:

1. curl -X POST --header 'Content-Type: application/x-www-form-urlencoded' 'http://integration.cdek.ru/integration/add' -d ‘xml_request=<?xml ...’'

2. curl -X POST --header 'Content-Type: application/xml' 'http://integration.cdek.ru/integration/addRaw' -d ‘<?xml ...’'

For the second variant (transmission in the request body) the link is similar to the first variant, but contains the suffix Raw at the end of the path.

3.1. Basic URL of the Interface

3.2. List of API Methods

3.3. Translation of integration errors

For a client who sends a request in the integration API, a contractor's language is identified and set. The language is determined by language code of the contractor's country:

• if the language has been identified, errors of integration API are displayed in the contractor's language;

• if the language code is not determined, the default language is used to display errors.

4. XML API Methods

4.1. Loading the List of Pickup Points

The method is used to load the list of active pickup points, from which the client can pick up its order.

The list of pickup points may be limited to user-defined characteristics.

4.1.1. Description of Request Parameters to be Transmitted

In order to load the list of pickup points, it is necessary to send a GET request with the following parameters:

¹ If both parameters cityid and citypostcode are indicated, the system gives priority to cityid to determine a city among all countries in which CDEK is present.

4.1.2. Response Format

The CDEK server will return a result in the form of XML:

Availability of payment in cash

Whether the pickup point is only a pickup point

Office schedule exceptions

The period of work on the specified date. If they don’t work on this day, it is not displayed

Example. List of pickup points

Making a request for the list of pickup points in Novosibirsk that accept cash on delivery
http://integration.cdek.ru/pvzlist/v1/xml?weightmax=50&cityid=270&allowedcod=1

<PvzList>
    <Pvz Code="NSK71" PostalCode="630001" Name="Na Kholodilnoy" CountryCode="1" countryCodeIso="RU" CountryName="Russia" RegionCode="23" RegionName="Novosibirsk Oblast" CityCode="270" City="Novosibirsk" WorkTime="Mon-Fri 10:00-20:00, Sat-Sun 10:00-16:00" Address="ul. Kholodilnaya, 13" FullAddress="Russia, Novosibirsk Oblast, Novosibirsk, ul. Kholodilnaya, 13" AddressComment="Ryadom s ostanovkoy Kholodilnaya ( po storone nechetnykh domov Dusi Kovalchuk) stoit dom , ot dorogi vtoroye ofisnoye pomeshcheniye." Phone="+79913770310" Email="Bibikova.m@cdek.ru" qqId="" Note="" coordX="82.885359" coordY="55.049586" Type="PVZ" ownerCode="cdek" IsDressingRoom="true" IsHandout="true" IsReception="true" HaveCashless="true" AllowedCod="true" NearestStation="Kholodilnaya" MetroStation="Zayeltsovskaya" Site="">
        <PhoneDetail number="+79913770310"/>
        <WorkTimeY day="1" periods="10:00/20:00"/>
        <WorkTimeY day="2" periods="10:00/20:00"/>
        <WorkTimeY day="3" periods="10:00/20:00"/>
        <WorkTimeY day="4" periods="10:00/20:00"/>
        <WorkTimeY day="5" periods="10:00/20:00"/>
        <WorkTimeY day="6" periods="10:00/16:00"/>
        <WorkTimeY day="7" periods="10:00/16:00"/>
    </Pvz>
</PvzList>

4.2. Order registration

This method is used to register orders to be delivered to clients. There are two types of orders:

• “online store” – available only for clients who have concluded online store contracts;

• “delivery” – can be created by any client with a contract.

Data formats for “online store” and “delivery” orders are described separately.

4.2.1. Description of Request Fields to be Transmitted

Registration of a Request from the Online Store

Registration of a Delivery Order

¹Identification of sender city and receiver city (in the case of “to the door” mode) uses the following algorithm by order of priority:

• By pickup code (PvzCode attribute).

• By unique city code (City ID) in CDEK’s database. The values are represented in SendCityCode, RecCityCode attributes.

• By the city’s postcode. The values are represented in SendCityPostCode, RecCityPostCode attributes. Along with the postcode, the country code (attributes SendCountryCode, RecCountryCode) and/or the city’s name (attributes SendCityName, RecCityName) can be used for specifying: the country code of the sought city should match with that described in the related attribute, and the transferred name of the city should be included in the name of the sought one. The city’s name can be in the client’s language (all localizations will be searched).

• By address string which is formed by concatenating the following fields: SendCityName/RecCityName + Address.Street + Address.House.

Usually, the city code serves to indicate the sender’s city, and the post code – to indicate the receiver’s city

It should be noted that the database of postal codes in the CDEK IS may contain incomplete and sometimes inaccurate information on postal codes. Therefore, the user should be able to adjust the postal code parameter, if necessary.

Note: At present, CDEK IS contains postcodes only for Russia. To identify cities of other countries, we recommend using a city code from the CDEK database.

² If CDEK delivery services are paid by the online store, rather than by the receiver, the order price may include the cost of delivery collected by the online store from the receiver, e.g., as compensation for its expenses. This amount may be different from the cost of delivery according to the CDEK tariffs. The value of the parameter is displayed in the order receipt in the “Cost of delivery” field, but it is included in the cash on delivery amount and processed as cash on delivery.

³ In the comment field, you can write any notes on the delivery of cargo. For example, if you allow a partial delivery of the cargo, you can specify “Partial delivery is allowed”. If you want to prohibit opening of the parcel, you can specify “Do not open”.

⁴ The package dimensions should be indicated if the box is used as a package. Taking into account the dimensions, the volumetric weight is calculated by the formula: SizeА * SizeВ * SizeС/5,000. The greater of actual weight and volumetric weight is used to calculate the cost of delivery.

⁵ The agreement with an e-shop specifies organization (CDEK or e-shop), responsible for obtaining delivery schedule from the receiver. If it is an e-shop, then the data is tagged as <Schedule>. The schedule can be transferred later, if necessary (see “Registration of information of the call’s result” method).

Only one schedule is permitted for one order and one date. The schedule can have several delivery days.

⁶ Courier invitation to indicated address is not a mandatory parameter. However, only one courier invitation can be included into a request to create an order. A courier can be invited to a particular address only once a day. The CallCourier tag has to be inside a tag.

⁷ For tariffs with codes 1, 10, 11, 12. 136, 137, 138, 139, the rule applies: if the weight on the order exceeds the maximum possible at the selected tariff, then the tariff automatically changes to the "Express heavy" tariff with the corresponding mode.

⁸ The value must be formed according to the instructions on the site https://честныйзнак.рф

4.2.2. Response Format

The CDEK server will return a result in the form of XML:

Example 1. Registration of an “online store” order

<?xml version="1.0" encoding="UTF-16"?>
<deliveryrequest account="0278f9e8004f6b08f37497001e804007"
    date="2019-01-22 11:20:45" number="soOEl" ordercount="1" secure="3e10b5b7d1da1dfa42cb70c329964ec2">
    <callcourier>
        <call comment="comment_soOEl1"
            date="2019-01-23" lunchbeg="14:00"
            lunchend="14:30" sendcitycode="44" sendername="name_soOEl1"
            sendphone="+79138739944" timebeg="10:00" timeend="17:00" weight="20">
            <sendaddress flat="flat_soOEl1" house="house_soOEl1" street="street_soOEl1"/>
        </call>
    </callcourier>
    <order comment="comment-soOEl0" deliveryrecipientcost="0.0"
        deliveryrecipientvatrate="VATX" deliveryrecipientvatsum="0.0"
        number="number-s785558445" phone="+79138739944" reccitycode="44"
        recipientemail="no-reply@cdek.ru" recipientname="name-soOEl0"
        sendcitycode="44" tarifftypecode="139">
        <address flat="flat-soOEl0" house="house-soOEl0" street="street-soOEl0"/>
        <sender company="company-soOEl0" name="TestName">
            <address flat="flat-soOEl0" house="house-soOEl0" street="street-soOEl0"/>
            <phone>+79138739945</phone>
            <phone>+79138739946</phone>
        </sender>
        <seller address="street_soOEl0 1" name="seller-soOEl0" INN="11111111111111111111" Phone="+77777777777" OwnershipForm="249"/>
        <package barcode="barcode-soOEl00" number="soOEl00" sizea="2.0"
            sizeb="3.0" sizec="4.0" weight="100.0">
            <item amount="2" comment="comment-soOEl000" cost="8.0"
                payment="10.0" paymentvatrate="VATX" paymentvatsum="0.0"
                warekey="warekey-soOEl000" weight="1.0"/>
        </package>
        <DeliveryRecipientCostAdv Threshold="2000" Sum="150" VATRate="vat10" VATSum="13.64"/>
		<AddService ServiceCode="30"/>
        <schedule>
            <attempt date="2019-01-23" id="soOEl00"
                timebeg="11:00:00" timeend="13:00:00">
                <address flat="flat-prozvon_adr"
                    house="house-prozvon_adr" street="street-prozvon_adr"/>
            </attempt>
        </schedule>
    </order>
</deliveryrequest>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
    <Call Number="13266932"/>
    <Call Msg="1 calls were added"/>
    <Order DispatchNumber="1105256427" Number="number-s785558445"/>
    <Order Msg="1 orders were added"/>
</response>

Example 2. Registration of a “delivery” order

<?xml version="1.0" encoding="UTF-8"?>
<deliveryrequest account="0278f9e8004f6b08f37497001e804007" date="2019-01-23 16:00:07"
    number="test_request" ordercount="2" secure="3e10b5b7d1da1dfa42cb70c329964ec2">
    <order clientside="SENDER" comment="test_comment"
       number="number-s785558446" phone="+79138739870"
       reccitycode="44" recipientcompany="company-6344227223"
       recipientcurrenc="rub" recipientemail="email_1_G4Akh0@test.ru"
       recipientname="Ivanov Ivan" sendcitycode="44" tarifftypecode="1">
       <address flat="flat-G4Akh0" house="house-G4Akh0" street="street-G4Akh0"/>
       <sender name="Petrov Petr">
           <address flat="flat-G4Akh0" house="house-G4Akh0" street="street-G4Akh0"/>
           <phone>+79138739876</phone>
           <phone>+79132873910</phone>
       </sender>
       <package number="number-p785558446" barcode="test_package" comment="test_comment"
           sizea="10.0" sizeb="20.0" sizec="30.0" weight="1000.0"/>
    </order>
    <order clientside="SENDER" comment="test_comment"
       number="number-s785558447" phone="+79138739870"
       reccitycode="44" recipientcompany="company-6344227225"
       recipientemail="email_1_G4Akh1@test.ru"
       recipientname="Ivanov Ivan" sendcitycode="44" tarifftypecode="1">
       <address flat="flat-G4Akh1" house="house-G4Akh1" street="street-G4Akh1"/>
       <sender name="Petrov Petr">
           <address flat="flat-G4Akh1" house="house-G4Akh1" street="street-G4Akh1"/>
           <phone>+79133309944</phone>
           <phone>+79138092416</phone>
       </sender>
       <package number="number-p785558446" barcode="test_package" comment="test_comment"
           sizea="10.0" sizeb="20.0" sizec="30.0" weight="1000.0"/>
    </order>
</deliveryrequest>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
    <Order DispatchNumber="1105256458" Number="number-s785558446"/>
    <Order DispatchNumber="1105256457" Number="number-s785558447"/>
    <Order Msg="2 orders were added"/>
    <TraceId>bcea8cac3e397ffd</TraceId>
</response>

4.3. Order Change Method

This method is used to change a created order. The following order details can be changed:

• cash-on-delivery amount;

• receiver information (receiver's name, telephone number, address, points of issue of the order);
• international orders information;
• additional delivery charges;

• all details of packages and items (i.e. old data will be deleted, and new data will be saved).

An order can be changed only if there is no cargo movement in the CDEK warehouse (i.e. the order status is “Created”).

4.3.1. Description of Request Fields to be Transmitted

¹ The order is identified either by “DispatchNumber” or by "Number".

4.3.2. Response Format

The CDEK server will return a result in the form of XML:

Example. Order change

<?xml version="1.0" encoding="UTF-8"?>
<updaterequest account="0278f9e8004f6b08f37497001e804007"
    date="2019-01-23 11:20:45" number="soOEl" ordercount="1" secure="3e10b5b7d1da1dfa42cb70c329964ec2">
    <order deliveryrecipientcost="10.02" deliveryrecipientvatrate="VATX" deliveryrecipientvatsum="0.0" number="number-s785558445">    
        <package barcode="barcode-soOEl00" number="soOEl00" sizea="2.0" sizeb="3.0" sizec="4.0" weight="100.0">
            <item amount="2" comment="comment-soOEl000" cost="8.0" payment="10.0" paymentvatrate="VATX" paymentvatsum="0.0" warekey="warekey-soOEl000" weight="1.0"/>
        </package>
    </order>
</updaterequest>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
    <Order DispatchNumber="1105256427" Number="number-s785558445"/>
    <Order Msg="1 orders were updated"/>
    <TraceId>5fe57a9044dc2f8d</TraceId>
</response>

4.4. Order Deletion

The method is designed to cancel /delete an order at the client's initiative. An order can be deleted only if there is no cargo movement in the CDEK warehouse (order status “Created”).

4.4.1. Description of Request Fields to be Transmitted

¹ The order is identified either by “DispatchNumber” or by "Number".

4.4.2. Response Format

The CDEK server will return a result in the form of XML:

Example. Order deletion

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<deleterequest number="soOEl" ordercount="1" account="0278f9e8004f6b08f37497001e804007" date="2019-01-23 18:41:51" secure="3e10b5b7d1da1dfa42cb70c329964ec2">
	<order number="number-s785558445"/>
</deleterequest>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
    <Order DispatchNumber="1105256427" Number="number-s785558445"/>
    <Order Msg="1 orders were deleted"/>
    <TraceId>667b31d2ef912467</TraceId>
</response>

4.5. Printing an Order Receipt

This method is designed to load a pdf file that contains printed forms of orders receipts.

To prevent the platform from being overloaded, do not transmit more than 100 order numbers per request.

4.5.1. Description of Request Fields to be Transmitted

¹ The order is identified either by “DispatchNumber” or by two parameters — Number and Date. If the request has a value of the “DispatchNumber” attribute, “Number” and “Date” attributes will be ignored.

4.5.2. Response Format

In response, the CDEK server will return a pdf file.

In case of error, the result will be returned as XML:

Example. Printing an order receipt

<?xml version="1.0" encoding="UTF-8"?>
<OrdersPrint Date="2019-01-23" Account="0278f9e8004f6b08f37497001e804007" Secure="3e10b5b7d1da1dfa42cb70c329964ec2" OrderCount="1" CopyCount="1">
    <Order DispatchNumber="1105256461"/>
</OrdersPrint>

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Order DispatchNumber="1105256461" ErrorCode="ERR_INVALID_DISPATCHNUMBER" Msg="The order is not found in the database CDEK: DispatchNumber = 1105256461"/>
</response>

4.6. Registration of a Courier Invitation

This method is designed to invite a courier for delivering a cargo.

A courier cannot be invited to the same address on the same day; otherwise, an error will be displayed in a response to the client.

The courier can be summoned from 9:00 am to 10:00 pm

4.6.1. Description of Data to be Transmitted

¹ Identification of sender city and receiver city (in the case of “to the door” mode) uses the following algorithm by order of priority:

• By unique city code (City ID) in CDEK’s database. The values are represented in SendCityCode, RecCityCode attributes.

• By the city’s postcode. The values are represented in SendCityPostCode, RecCityPostCode attributes. Along with the postcode, the country code (attributes SendCountryCode, RecCountryCode) and/or the city’s name (attributes SendCityName, RecCityName) can be used for specifying: the country code of the sought city should match with that described in the related attribute, and the transferred name of the city should be included in the name of the sought one. The city’s name can be in the client’s language (all localizations will be searched);

• By address string which is formed by concatenating the following fields: SendCityName/RecCityName + Address.Street + Address.House.

It has to be noted that the postcodes database in CDEK informational system may contain incomplete and sometimes inaccurate information about postcodes. Therefore, users need to be able to correct the postcode parameter if necessary.

Note: Currently, CDEK informational system contains only Russian postcodes. We recommend to use the City ID in CDEK’s database.

² If DispatchNumber isn't transmitted in the request then the courier invitation is registrated for pick up the console (all orders from the same sender address).

4.6.2. Response Format

The CDEK server will return a result in the form of XML:

Example. Registration of a courier invitation

<?xml version="1.0" encoding="UTF-8"?>
<callcourier account="0278f9e8004f6b08f37497001e804007" callcount="1"
    date="2019-01-23" secure="3e10b5b7d1da1dfa42cb70c329964ec2">
    <call comment="comment_QF6aD1" date="2019-01-25"
       dispatchnumber="1105256461" lunchbeg="14:00" lunchend="14:30"
       sendcitycode="44" sendername="name_QF6aD1"
       sendphone="+79138739944" timebeg="10:00" timeend="17:00" weight="20">
       <address flat="flat_QF6aD1" house="house_QF6aD1" street="street_QF6aD1"/>
    </call>
</callcourier>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
    <Call Number="13266935"/>
    <Call Msg="1 calls were added"/>
    <TraceId>21cdde0373428e05</TraceId>
</response>

4.7. Recording of Notification Call Results

This method can be used by the client to transmit results of notification calls to the receiver of an “online store” order, namely agreed delivery-to-door.

This method is used in the following cases:

• the online store provides a receiver's schedule for delivery /pickup;

• changes in delivery address;

• change in the amount to be paid for the goods.
  
  

4.7.1. Description of Input Parameters

¹ The order is identified either by “DispatchNumber” or by two parameters — Number and Date. If the request has a value of the “DispatchNumber” attribute, “Number” and “Date” attributes will be ignored.

4.7.2. Response Format

The CDEK server will return a result in the form of XML:

Example. Recording of Notification Call Results

<?xml version="1.0" encoding="UTF-8"?>
<schedulerequest account="0278f9e8004f6b08f37497001e804007"
    date="2019-01-23 17:20:45" ordercount="1" secure="3e10b5b7d1da1dfa42cb70c329964ec2">
    <order date="2019-01-23 17:20:45" dispatchnumber="1105256461" number="s785558447">
       <attempt comment="comment_0" date="2019-01-28"
           timebeg="9:00:00" timeend="15:00:00">
           <address flat="flat_0" house="fhouse_0" street="street_0"/>
       </attempt>
    </order>
</schedulerequest>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
    <ScheduleRequest Msg="Insert 1 schedule"/>
</response>

4.8. Printing a Package Barcode

This method is used to generate a printed label form in pdf format.

To prevent the platform from being overloaded, do not transmit more than 100 order numbers per request.

4.8.1. Description of Data to be Transmitted

¹ The order is identified either by “DispatchNumber” or by Number. If the request has a value of the “DispatchNumber” attribute, “Number” attribute will be ignored.

4.8.2. Response Format

In response, the CDEK server will return a pdf file.

In case of error, the result will be returned as XML:

Example. Printing a Package Barcode

<?xml version="1.0" encoding="UTF-8"?>
<OrdersPackagesPrint Account="0278f9e8004f6b08f37497001e804007" Secure="3e10b5b7d1da1dfa42cb70c329964ec2" Date="2019-01-24" OrderCount="1" printFormat="A6">
    <Order DispatchNumber="1105256461" Number="s785558447" Date="2019-01-24"/>
</OrdersPackagesPrint>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
    <Order ErrorCode="ERR_INVALID_DISPATCHNUMBER" Msg="Orders not found by dispatchNumber 1105256461"/>
    <TraceId>e32939c969dfb6d9</TraceId>
</response>

4.9. Order Status Report

This method is used to generate an order status report, including order change history.

4.9.1. Description of Data to be Transmitted

¹ The request must contain at least one of two tags: ChangePeriod or Order:

• if both the ChangePeriod tag and the list of orders in the Order tag, the result will contain details of all orders that have changed their status in the specified period;

• if only the ChangePeriod tag is specified without the list of orders in the Order tag, the result will contain details of all orders that have changed their status in the specified period;

• if the ChangePeriod tag is not transmitted and only the Order is available, information for the entire list of requested orders will be transmitted.

² The order is identified either by “DispatchNumber” or by two parameters — Number and Date. If the request has a value of the “DispatchNumber” attribute, “Number” and “Date” attributes will be ignored.
³ The maximum period for uploading changes is 31 days. Those. DateLast - DateFirst = <31 days.

Status history can be obtained for orders created no earlier than 2020.

4.9.2. Response Format

The CDEK server will return a result in the form of XML:

¹ The State tag is used only if ShowHistory = 1 (see the Description of Data to be Transmitted).

² Package and Item tags are used only in case of partial delivery (final status “Delivered” and additional status “Partial delivery”).

³ The Attempt tag is used only if the online store shall provide a delivery schedule to CDEK under the contract. The tag contains details of failed delivery attempts as compared to a delivery schedule provided by the online store.

Example. Order Status Report

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<StatusReport Account="account" Date="2018-08-08T20:23:54" Secure="secure" ShowHistory="1">
    <Order DispatchNumber="1000028000"/>
    <Order DispatchNumber="1000356200"/>
</StatusReport>

<?xml version="1.0" encoding="UTF-8"?>
<StatusReport DateFirst="2000-12-31T17:00:00+00:00" DateLast="2018-08-10T08:55:52+00:00" >
	<Order ActNumber="" Number="2080965069" DispatchNumber="1000028000"  DeliveryDate="2018-04-06T13:33:27+03:00" RecipientName="Ivanov Ivan" >
		<Status Date="2018-04-06T10:33:42+00:00" Code="4" Description="Delivered" CityCode="1081" CityName="Nalchik">
			<State Date="2018-03-21T14:54:13+00:00" Code="1" Description="Created" CityCode="44" CityName="Moscow" />
			<State Date="2018-03-21T17:32:32+00:00" Code="3" Description="Recieved at shipment warehouse" CityCode="44" CityName="Moscow" />
			<State Date="2018-03-21T17:35:12+00:00" Code="6" Description="Sent for shipment" CityCode="44" CityName="Moscow" />
			<State Date="2018-03-21T23:00:12+00:00" Code="7" Description="Handed to carrier in shipment location" CityCode="44" CityName="Moscow" />
			<State Date="2018-03-21T23:36:53+00:00" Code="21" Description="Sent to transit location" CityCode="44" CityName="Moscow" />
			<State Date="2018-03-22T19:01:19+00:00" Code="22" Description="Received at transit location" CityCode="438" CityName="Rostov-on-Don" />
			<State Date="2018-03-22T22:18:47+00:00" Code="13" Description="Accepted at transit warehouse" CityCode="438" CityName="Rostov-on-Don" />
			<State Date="2018-03-22T22:18:47+00:00" Code="19" Description="Sent for shipment in transit location" CityCode="438" CityName="Rostov-on-Don" />
			<State Date="2018-03-22T22:19:44+00:00" Code="20" Description="Handed to carrier in transit location" CityCode="438" CityName="Rostov-on-Don" />
			<State Date="2018-03-22T22:59:19+00:00" Code="8" Description="Send to destination city" CityCode="438" CityName="Rostov-on-Don" />
			<State Date="2018-03-24T15:11:53+00:00" Code="17" Description="Returned to transit warehouse" CityCode="438" CityName="Rostov-on-Don" />
			<State Date="2018-03-24T15:11:53+00:00" Code="19" Description="Sent for shipment in transit location" CityCode="438" CityName="Rostov-on-Don" />
			<State Date="2018-03-25T21:25:02+00:00" Code="20" Description="Handed to carrier in transit location" CityCode="438" CityName="Rostov-on-Don" />
			<State Date="2018-03-25T22:32:47+00:00" Code="8" Description="Send to destination city" CityCode="438" CityName="Rostov-on-Don" />
			<State Date="2018-03-26T11:13:27+00:00" Code="10" Description="Accepted at delivery warehouse" CityCode="1081" CityName="Nalchik" />
			<State Date="2018-04-06T05:28:09+00:00" Code="11" Description="Sent for delivery" CityCode="1081" CityName="Nalchik" />
			<State Date="2018-04-06T10:33:42+00:00" Code="4" Description="Delivered" CityCode="1081" CityName="Nalchik" />
		</Status>
		<Reason Code="" Description="" Date=""></Reason>
		<DelayReason Code="" Description="" Date="" ></DelayReason>
		<Call>
			<CallGood>
				<Good Date="2018-03-26T12:50:31+00:00" DateDeliv="2018-04-06" />
				<Good Date="2018-03-26T12:50:37+00:00" DateDeliv="2018-04-06" />
			</CallGood>
		</Call>
	</Order>
	<Order ActNumber="" Number="2066479243" DispatchNumber="1000356200"  DeliveryDate="2018-04-07T15:29:32+03:00" RecipientName="Petrov Petr" >
		<Status Date="2018-04-07T12:29:39+00:00" Code="4" Description="Delivered" CityCode="44" CityName="Moscow">
			<State Date="2018-04-01T14:15:20+00:00" Code="1" Description="Created" CityCode="44" CityName="Moscow" />
			<State Date="2018-04-01T18:03:43+00:00" Code="10" Description="Accepted at delivery warehouse" CityCode="44" CityName="Moscow" />
			<State Date="2018-04-02T09:04:38+00:00" Code="11" Description="Sent for delivery" CityCode="44" CityName="Moscow" />
			<State Date="2018-04-02T09:13:41+00:00" Code="18" Description="Returned to delivery warehouse" CityCode="44" CityName="Moscow" />
			<State Date="2018-04-02T09:13:41+00:00" Code="11" Description="Sent for delivery" CityCode="44" CityName="Moscow" />
			<State Date="2018-04-03T07:56:08+00:00" Code="18" Description="Returned to delivery warehouse" CityCode="44" CityName="Moscow" />
			<State Date="2018-04-07T06:14:36+00:00" Code="11" Description="Sent for delivery" CityCode="44" CityName="Moscow" />
			<State Date="2018-04-07T12:29:39+00:00" Code="4" Description="Delivered" CityCode="44" CityName="Moscow" />
		</Status>
		<Reason Code="20" Description="Partial delivery" Date="2018-04-07T12:29:39+00:00"></Reason>
		<DelayReason Code="" Description="" Date="" >
			<State Date="2018-04-03T16:56:41+00:00" Code="47" Description="Address does not exist" />
		</DelayReason>
		<Package Number="2066479243" BarCode="2066479243">
			<Item WareKey="2201073352678" Amount="1" DelivAmount="0" />
			<Item WareKey="2201084246850" Amount="1" DelivAmount="1" />
			<Item WareKey="654321" Amount="1" DelivAmount="0" />
		</Package>
		<Call>
			<CallGood>
				<Good Date="2018-04-01T14:15:46+00:00" DateDeliv="2018-04-02" />
				<Good Date="2018-04-03T16:56:41+00:00" DateDeliv="2018-04-07" />
			</CallGood>
			<CallFail>
				<Fail Date="2018-04-02T15:35:47+00:00" ReasonCode="3" ReasonDescription="Subscriber unavailable" />
			</CallFail>
		</Call>
	</Order>
</StatusReport>

4.10. Order Information Report

This method is used to load order details.

4.10.1. Description of Data to be Transmitted

¹ The order is identified either by “DispatchNumber” or by two parameters — Number and Date. If the request has a value of the “DispatchNumber” attribute, “Number” and “Date” attributes will be ignored.

4.10.2. Response Format

The CDEK server will return a result in the form of XML:

Example. Order Information Report

<?xml version="1.0" encoding="utf-8"?>
<InfoRequest Date="2019-01-23T00:00:00" Account="0278f9e8004f6b08f37497001e804007" Secure="3e10b5b7d1da1dfa42cb70c329964ec2">
	<Order DispatchNumber="1105256461"/>
</InfoRequest>

<?xml version="1.0" encoding="UTF-8"?>
<InfoReport>
    <Order Number="s785558447" Date="2019-01-23" DispatchNumber="1105256461" TariffTypeCode="139" Weight="2" DeliverySum="405" DateLastChange="" CashOnDeliv="10500" CashOnDelivFact="10500" CashOnDelivType="cashless" deliveryMode="1" deliveryVariant="COURIER">
        <SendCity Code="44" PostCode="101000" Name="??????"/>
        <RecCity Code="44" PostCode="101000" Name="??????"/>
        <Package Number="_" BarCode="10456789" Weight="1" VolumeWeight="0.005" SizeA="2"  SizeB="3" SizeC="4">
            <Item WareKey="00012345" Comment="wrap" Cost="500" Payment="500" VATRate="VAT10" VATSum="45.45" Weight="0.5" Amount="1" DelivAmount="1" />
            <Item WareKey="00078945" Comment="female jacket" Cost="5500" Payment="5500" VATRate="VAT10" VATSum="500" Weight="3" Amount="1" DelivAmount="1" />
        </Package>
        <Package Number="_" BarCode="10123456" Weight="1" VolumeWeight="0.005" SizeA="2"  SizeB="3" SizeC="4">
            <Item WareKey="00123456" Comment="sneakers" Cost="1500" Payment="1500" VATRate="VAT10" VATSum="136.36" Weight="1" Amount="1" DelivAmount="1" />
            <Item WareKey="00456123" Comment="men&#039;s shirt" Cost="2500" Payment="500" VATRate="VAT10" VATSum="45.45" Weight="0.5" Amount="1" DelivAmount="1" />
            <Item WareKey="00789456" Comment="dress" Cost="2500" Payment="2500" VATRate="VAT10" VATSum="227.27" Weight="1" Amount="1" DelivAmount="1" />
        </Package>
        <AddedService ServiceCode="30" Sum="0" />
        <AddedService ServiceCode="2" Sum="93.75" />
    </Order>
</InfoReport>

4.11. List of Regions

This method is used to load detailed information on regions. The list of regions may be limited to user-defined characteristics.

4.11.1. Description of Request Parameters to be Transmitted

In order to load the list of regions, it is necessary to send a GET request with the following parameters:

4.11.2. Response Format

The CDEK server returns a result with the following fields:

Example 1. List of Regions in JSON

http://integration.cdek.ru/v1/location/regions/json?size=3&page=0&countryCode=DE

[
    {
        "regionName": "Lower Saxony",
        "regionCode": "641",
        "regionUuid": "b94ece92-30a3-44cc-bc2b-98b40c39d38f",
        "countryName": "Germany",
        "countryCode": "DE",
        "countryCodeExt": "276"
    },
    {
        "regionName": "Bremen",
        "regionCode": "355",
        "regionUuid": "413fe600-2d4c-43f8-b2c4-ded6903af01a",
        "countryName": "Germany",
        "countryCode": "DE",
        "countryCodeExt": "276"
    },
    {
        "regionName": "Saxony",
        "regionCode": "235",
        "regionUuid": "4e845f95-1a45-4822-8e4f-5ac552b9c95f",
        "countryName": "Germany",
        "countryCode": "DE",
        "countryCodeExt": "276"
    }
]

Example 2. List of Regions in XML

http://integration.cdek.ru/v1/location/regions?size=5&page=0&countryCode=DE
OR
http://integration.cdek.ru/v1/location/regions/xml?size=5&page=0&countryCode=DE

?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Regions>
    <Region regionName="Lower Saxony" regionCode="641" regionUuid="b94ece92-30a3-44cc-bc2b-98b40c39d38f" countryName="Germany" countryCode="DE" countryCodeExt="276"/>
    <Region regionName="Bremen" regionCode="355" regionUuid="413fe600-2d4c-43f8-b2c4-ded6903af01a" countryName="Germany" countryCode="DE" countryCodeExt="276"/>
    <Region regionName="Saxony" regionCode="235" regionUuid="4e845f95-1a45-4822-8e4f-5ac552b9c95f" countryName="Germany" countryCode="DE" countryCodeExt="276"/>
</Regions>

4.12. List of Cities

This method is used to load detailed information on cities. The list of cities may be limited to user-defined characteristics.

4.12.1. Description of Request Parameters to be Transmitted

In order to load the list of cities, it is necessary to send a GET request with the following parameters:

4.12.2. Response Format

The CDEK server returns a result with the following fields:

Example 1.List of cities in JSON

http://integration.cdek.ru/v1/location/cities/json?countryCode=DE&lang=eng&regionCode=331&size=3

[ 
   { 
      "cityName":"Thanstein",
      "cityCode":"71896",
      "cityUuid":"28cf2cb3-ae3e-495c-9302-b7c7494dfb51",
      "country":"Germany",
      "countryCode":"DE",
      "region":"Bavaria",
      "regionCode":"331",
      "subRegion":"Landkreis Schwandorf",
      "latitude":49.38333,
      "longitude":12.46667,
      "paymentLimit":-1,
      "timezone":"Europe/Berlin"
   },
   { 
      "cityName":"Bad Steben",
      "cityCode":"64230",
      "cityUuid":"28fbbd82-05ec-4a24-a2f7-fe3f170b110c",
      "country":"Germany",
      "countryCode":"DE",
      "region":"Bavaria",
      "regionCode":"331",
      "subRegion":"Landkreis Hof",
      "latitude":50.36648,
      "longitude":11.64438,
      "paymentLimit":-1,
      "timezone":"Europe/Berlin"
   },
   { 
      "cityName":"Seinsheim",
      "cityCode":"67411",
      "cityUuid":"2a380d91-fe12-4f1e-b703-60bfdb038397",
      "country":"Germany",
      "countryCode":"DE",
      "region":"Bavaria",
      "regionCode":"331",
      "subRegion":"Landkreis Kitzingen",
      "latitude":49.64073,
      "longitude":10.22038,
      "paymentLimit":-1,
      "timezone":"Europe/Berlin"
   }
]

Example 2. List of cities in XML

http://integration.cdek.ru/v1/location/cities?size=5&page=0&countryCode=DE
OR
http://integration.cdek.ru/v1/location/cities/xml?size=5&page=0&countryCode=DE

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Locations>
    <Location cityName="Sprockhövel" cityCode="34133" cityUuid="1d2ec7b1-f2f1-4190-bd60-44d336a615e7" country="Germany" countryCode="DE" region="North Rhine-Westphalia" regionCode="763" subRegion="Ennepe-Ruhr-Kreis" latitude="51.34669" longitude="7.24343"/>
    <Location cityName="Lüneburg" cityCode="8810" cityUuid="1f4a11a1-99c0-4d9e-999d-ae680e4c557d" country="Germany" countryCode="DE" region="Lower Saxony" regionCode="641" subRegion="Landkreis Lüneburg" latitude="53.2509" longitude="10.41409"/>
    <Location cityName="Westerstede" cityCode="53043" cityUuid="21df83e1-7ec7-49f8-a8b5-cbcf06365638" country="Germany" countryCode="DE" region="Lower Saxony" regionCode="641" subRegion="Landkreis Ammerland" latitude="53.25682" longitude="7.92737"/>
</Locations>

4.13Calculator

4.13.1. Cost calculation on tarrifs with priority

To get the rate and transit time you should send json-object to CDEK server to the following address:

4.13.1.1. Description of Data to be Transmitted

¹ Authorization is not obligatory for regular delivery tariffs and authLogin, secure parametrs might be not provided.

² The planning shipment date dateExecute is not obligatory (in this case the current date will be used). But if you work with the authorization the date must be transmitted mandatory because the date is taking into account while decoding the password.

³ A city can be identified in one of two ways at the user's discretion:

• by unique city code from the CDEK database. Values are transferred in senderCityId and receiverCityId attributes;
• by postal code of the city. Values are transferred in senderCityPostCode and receiverCityPostCode attributes. Along with the postcode, the country code (attributes senderCountryCode, receiverCountryCode), the city’s name (attributes senderCity, receiverCity) and city longitude and city latitude (attributes senderLongitude, receiverLongitude, senderLatitude, receiverLatitude);
• if putting both values then senderCityId/receiverCityId is taking, senderCityPostCode/receiverCityPostCode should be ignored.

It should be noted that the database of postal codes in the CDEK IS may contain incomplete and sometimes inaccurate information on postal codes. Therefore, the user should be able to adjust the postal code parameter, if necessary.

Note: At present, CDEK IS contains postcodes only for Russia. To identify cities of other countries, we recommend using a city code from the CDEK database.

⁴ While specifying the rates you should choose one tariff or the list of rates with priorities. If you specified tariffId, and tariffList – tariffId will be chosen, the list will be ignored.

The list of tariffs with the priorities used in the case, if the selected direction at CDEK may not be the most beneficial to you of any particular rate of delivery.

In the case of an assignment of price list this list is checked for the possibility of delivery in a given direction with a given weight of cargo sequentially (starting from the first with the least priority) and the verify process will continue until the rate will give the possibility. In this case the price will be calculated by this rate.  In server’s reply it would be returned tariffId from the specified list tariffList, according to which the price was calculated.

The mode of delivery can be specified by modeId and it makes sense only in specifying the list of tariffs. In this case the specified list is additionally filtered by delivery mode otherwise – ignored.

⁵ For additional services 2, 24, 25 and 32, the parameter value is mandatory and must be passed in the request. For service 2 - insurance in param it is necessary to transfer the amount from which the insurance will be calculated (must be transferred in the currency of mutual settlements). Service 30 is only available for an on-line store contract, so the request must be passed the values of authLogin and secure. For services 24, 25, 32, 54-58, 61-73, 76 a quantity value is transmitted to param, for 74, 75 services a length value is transmitted.

4.13.1.2. Response Format

The CDEK server will return a result:

Example. Calculate shipping cost

{ 
	"version":"1.0",
	"dateExecute":"2018-07-27", 
	"senderCityId":"270", 
	"receiverCityId":"44", 
	"tariffId":"137", 
	"goods": 
		[ 
			{ 
				"weight":"0.3", 
				"length":"10", 
				"width":"7", 
				"height":"5" 
			}
		],
	"services": [
		{	
			"id": 2,	
			"param": 2000	
		},
		{	
			"id": 30
		}
	]
} 	

{
	"result": {
		"price": "2555",
		"deliveryPeriodMin": 2,
		"deliveryPeriodMax": 3,
		"deliveryDateMin": "2018-07-28",
		"deliveryDateMax": "2018-07-29",
		"tariffId": "137",
		"cashOnDelivery": "30000.00",
		"percentVAT": 18,
		"priceByCurrency": 2555,
		"currency": "RUB",
		"services": [
			{
				"id": 2,
				"title": "Insurance",
				"price": 15
			},
			{
				"id": 30,
				"title": "Home fitting",
				"price": 0
			}
		]
	}
}

4.13.2. Cost calculation on tariffs without priority

To get the rate and transit time you should send json-object to CDEK server to the following address:

4.13.2.1. Description of Data to be Transmitted

¹ Authorization is not obligatory for regular delivery tariffs and authLogin, secure parametrs might be not provided.

² The planning shipment date dateExecute is not obligatory (in this case the current date will be used). But if you work with the authorization the date must be transmitted mandatory because the date is taking into account while decoding the password.

³ A city can be identified in one of two ways at the user's discretion:

• by unique city code from the CDEK database. Values are transferred in senderCityId and receiverCityId attributes;
• by postal code of the city. Values are transferred in senderCityPostCode and receiverCityPostCode attributes. Along with the postcode, the country code (attributes senderCountryCode, receiverCountryCode), the city’s name (attributes senderCity, receiverCity) and city longitude and city latitude (attributes senderLongitude, receiverLongitude, senderLatitude, receiverLatitude);

• if putting both values then senderCityId/receiverCityId is taking, senderCityPostCode/receiverCityPostCode should be ignored.

It should be noted that the database of postal codes in the CDEK IS may contain incomplete and sometimes inaccurate information on postal codes. Therefore, the user should be able to adjust the postal code parameter, if necessary.

Note: At present, CDEK IS contains postcodes only for Russia. To identify cities of other countries, we recommend using a city code from the CDEK database.

⁴ While specifying the rates you should choose one tariff or the list of rates with priorities. If you specified tariffId and tariffList – tariffId will be chosen, the list will be ignored.

⁵ For additional services 2, 24, 25 and 32, the parameter value is mandatory and must be passed in the request. For service 2 - insurance in param it is necessary to transfer the amount from which the insurance will be calculated (must be transferred in the currency of mutual settlements). Service 30 is only available for an on-line store contract, so the request must be passed the values of authLogin and secure. For services 24, 25, 32, 54-58, 61-73, 76 a quantity value is transmitted to param, for 74, 75 services a length value is transmitted.

4.13.2.2. Response Format

If tariffId was transmitted in the request, then the response corresponds to that described in 4.14.1.2.
Otherwise the CDEK server will return a result:

Example. Calculate shipping cost

{
	"version":"1.0",
	"dateExecute":"2019-04-01",
	"senderCityId":"44",
	"receiverCityId":"269",
	"currency":"RUB",
	"tariffList":
		[
			{
				"id":1
			},	
			{
				"id":8
			}
		],
	"goods":
		[
			{
				"weight":"1",
				"length":"1",
				"width":"2",
				"height":"7"
			}
		],
	"services":
		[
			{
				"id":2,	
				"param":1000
			}	
		]
}

{
	"result":
	[
		{
			"tariffId":1,
			"status":true,
			"result":
				{
				"price":"1077",
				"deliveryPeriodMin":2,
				"deliveryPeriodMax":3,
				"tariffId":1,
				"priceByCurrency":1077,
				"currency":"RUB",
				"percentVAT":20,
				"services":
					[
						{
							"id":2,
							"title":"Insurance",
							"price":7.5,
							"rate":0.75
						}
					]
				}
			},
			{
				"tariffId":8,
				"status":false,
				"result":
					{
						"errors":
						{
							"code":3,
							"text":"Impossible to deliver to this area under given conditions"
						}
					}
			}
	]
}

Appendices

Appendix 1. CDEK Tariffs and Delivery Modes

Tariffs for Online Stores

Chinese Express Tariffs

Regular Delivery Tariffs