Swagger API Личный кабинет Центр поддержки
  • Languages Русский

Загрузка xlsx файла c данными о заказах #

Адрес метода #

POST /orders/upload

Параметры запроса #

РазделПараметрОписаниеТипОбязательныйПример
providerKeyКод службы доставкиСтрокаДаcdek
modeМетод создания заказовsync - синхронное создание заказовasync - асинхронное создание заказовСтрокаНетsync
errorsToFileФлаг возвращения base64 строки исходного файла с ошибками создания заказов, если имеются. (true - в исходный файл будут записаны ошибки создания и в ответе будет возвращена base64 строка данного файла; false - в файл не будут записаны ошибки)(ошибки в ответе будут присутствовать и без этого параметра)Булев(Логический)Нетfalse
file
urlСсылка на файлСтрокаДа 1http://test.ru/test.xlsx
base64Строка закодированного в base64 файлаСтрокаДа 2iVBORw0KGgoAAAANSUhEUgAAB4AAAAQ4CAYAAADo08FDAA…
typeТип файла, который будет получен в результате декодирования base64 или по ссылкеxlsxСтрокаНетxlsx (по умолчанию)
columnSettings
dateFormatФормат даты в таблицеСтрокаY-m-d
nameFormatФормат ФИО в таблицеtrue(или 1) - ФИО в разных столбцахfalse(или 0) - ФИО в одном столбцеБулев(Логический)Даfalse
itemsNewRowТип расположения данных о товарных вложениях 3 true - располагаются в строке информации о заказеfalse - располагаются под информацией о заказеБулев(Логический)Даtrue
timeFormatФормат времени в таблицеСтрокаДаH:i:s
rowStartПорядковый номер первой считываемой строки таблицы 4ЧислоНет1
rowEndПорядковый номер последней считываемой строки таблицыЧислоНет10
columnMap[5]
order.clientNumberНомер заказа в системе клиентаСтрокаДаA
order.weightВес всего заказа в граммахЧислоДаB
order.heightВысота заказа в сантиметрахЧислоНетC
order.lengthДлина заказа в сантиметрахЧислоНетD
order.widthШирина заказа в сантиметрахЧислоНетE
order.providerKeyКод службы доставкиСтрокаДаF
order.providerConnectIdID подключения к СДЧислоНетG
order.pickupTypeТип забора груза 1 - от двери клиента 2 – клиент привозит заказ на склад СДЧислоДаH
order.deliveryTypeТип доставки 1 - до двери 2 – до ПВЗЧислоДаI
order.pointInIdИдентификатор точки забора товара в системе apishipЧислоНет 5
order.pointOutIdИдентификатор точки выдачи товара в системе apishipЧислоНет 6
order.tariffIdТариф службы доставки по которому осуществляется доставкаЧислоДаJ
order.deliveryTimeStartНачальное время доставкиВремяНетK
order.deliveryTimeEndКонечное время доставкиВремяНетL
cost.assessedCostОценочная стоимость / сумма страховки (в рублях)ЧислоДаM
cost.codCostСумма наложенного платежа с учетом НДС (в рублях)ЧислоДаN
cost.deliveryCostСтоимость доставки с получателя. codCost должен содержать в себе эту сумму.ЧислоНетO
sender.phoneКонтактный телефонСтрокаДаP
sender.companyNameНазвание компанииСтрокаНетR
sender.contactNameФИО контактного лицаСтрокаДаS
sender.countryCodeКод страны в соответствии с ISO 3166-1 alpha-2СтрокаДаT
sender.regionОбласть или республика или крайСтрокаДаU
sender.cityГород или населенный пунктСтрокаДаV
sender.streetУлицаСтрокаДаW
sender.houseДомСтрокаДаX
sender.blockСтроение/КорпусСтрокаНетY
sender.officeОфис/КвартираСтрокаНетZ
sender.emailКонтактный email адресСтрокаНетAA
sender.addressStringАдрес одной строкойСтрокаДа[7]AB
recipient.phoneКонтактный телефонСтрокаДаAC
recipient.companyNameНазвание компанииСтрокаНетAD
recipient.contactNameФИО контактного лицаСтрокаДаAE
recipient.countryCodeКод страны в соответствии с ISO 3166-1 alpha-2СтрокаДаAF
recipient.regionОбласть или республика или крайСтрокаДаAG
recipient.cityГород или населенный пунктСтрокаДаAH
recipient.streetУлицаСтрокаДаAI
recipient.houseДомСтрокаДаAJ
recipient.blockСтроение/КорпусСтрокаНетAK
recipient.officeОфис/КвартираСтрокаНетAL
recipient.emailКонтактный email адресСтрокаНетAM
recipient.addressStringАдрес одной строкойСтрокаДа 7AN
place.placeNumberНомер места в информационной системе клиентаСтрокаНетAO
place.barcodeШтрихкод местаСтрокаНетAP
place.heightВысота места в сантиметрахЧислоДаAR
place.widthШирина места в сантиметрахЧислоДаAS
place.lengthДлина места в сантиметрахЧислоДаAT
place.weightВес места в граммахЧислоДаAU
place.itemsСодержимое местаitemДаAV
item.descriptionНаименование товараСтрокаДаAW
item.quantityКол-во товараЧислоДаAX
item.articulАртикул товараСтрокаНетAY
item.barcodeШК предметаСтрокаНетAZ
item.assessedCostОценочная стоимость единицы товара в рубляхСтрокаНетBA
item.costНаложенная стоимость товара в рубляхСтрокаНетBB
item.weightВес единицы товара в граммахСтрокаДаBC
item.heightВысота единицы товара в сантиметрахСтрокаНетBD
item.lengthДлина единицы товара в сантиметрахСтрокаНетBE
item.widthШирина единицы товара в сантиметрахЧислоНетBF
extraParams.{param_name}Дополнительная услуга 8СтрокаНетBG
defaultData 9
{Название поля из раздела columnMap}Установка значения по умолчанию для указанного поля из columnMapСтрокаНет“sender.phone”: “+791111111”

Пример запроса #

Файл:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

{
    "file": {
        "url": "http://test.ru/test.xlsx"
    },
    "mode": "sync",
    "errorsToFile": true,
    "providerKey": "cdek",
    "columnMap": {
        "order.clientNumber": "A",
        "recipient.contactName": "C",
        "recipient.addressString": "E",
        "recipient.phone": "F",
        "item.articul": "G",
        "item.description": "H",
        "item.quantity": "I",
        "item.cost": "J",
        "item.assessedCost": "K",
        "item.weight": "M",
        "order.deliveryTimeStart": "O",
        "order.deliveryTimeEnd": "P",
        "extraParams.DopRecno": "Q"
    },
    "columnSettings": {
        "dateFormat": "d.m.Y",
        "timeFormat": "H i",
        "rowStart": 2,
        "itemsNewRow": 0,
        "nameFormat": 0
    },
    "defaultData": {
        "sender.phone": "+791111111",
        "sender.city": "Москва",
        "sender.countryCode": "RU",
        "sender.street": "Тверская",
        "sender.house": "2",
        "sender.contactName": "Test",
        "order.pickupType": "2",
        "order.deliveryType": "1",
        "order.tariffId": "52",
        "cost.codCost": "sumByOrderRows(J)",
        "cost.assessedCost": "sumByOrderRows(K)",
        "order.weight": "sumByOrderRows(M)"
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

<request>
    <file>
        <url>http://test.ru/test.xlsx</url>
    </file>
    <providerKey>cdek</providerKey>
    <mode>sync</mode>
    <errorsToFile>0</errorsToFile>
    <columnMap>
        <order.clientNumber>A</order.clientNumber>
        <recipient.contactName>C</recipient.contactName>
        <recipient.addressString>E</recipient.addressString>
        <recipient.phone>F</recipient.phone>
        <item.articul>G</item.articul>
        <item.description>H</item.description>
        <item.quantity>I</item.quantity>
        <item.cost>J</item.cost>
        <item.assessedCost>K</item.assessedCost>
        <item.weight>M</item.weight>
        <order.deliveryTimeStart>O</order.deliveryTimeStart>
        <order.deliveryTimeEnd>P</order.deliveryTimeEnd>
        <extraParams.DopRecno>Q</extraParams.DopRecno>
    </columnMap>
    <columnSettings>
        <dateFormat>d.m.Y</dateFormat>
        <timeFormat>H i</timeFormat>
        <rowStart>2</rowStart>

        <itemsNewRow>0</itemsNewRow>
        <nameFormat>0</nameFormat>
    </columnSettings>
    <defaultData>
        <sender.phone>+791111111</sender.phone>
        <sender.city>Москва</sender.city>
        <sender.countryCode>RU</sender.countryCode>
        <sender.street>Тверская</sender.street>
        <sender.house>2</sender.house>
        <sender.contactName>Test</sender.contactName>
        <order.pickupType>2</order.pickupType>
        <order.deliveryType>1</order.deliveryType>
        <order.tariffId>52</order.tariffId>
        <cost.codCost>sumByOrderRows(J)</cost.codCost>
        <cost.assessedCost>sumByOrderRows(K)</cost.assessedCost>
        <order.weight>sumByOrderRows(M)</order.weight>
    </defaultData>
</request>

Параметры корректного ответа #

РазделПараметрОписаниеТипОбязательныйПример
base64Файл в base64 с описанием ошибок создания заказаСтрока
resultItems
clientNumberНомер заказа в системе клиентаСтрокаДа204479
rowНомер строки, на которой расположен заказ в таблицеЧислоДа5
orderIdНомер заказа в ApiShipЧислоДа4561111
providerNumberНомер заказа в системе СДСтрокаНет[1]564897498
createdДата создания заказаДата и времяДа2018-01-01T10:00:00+03:00

[1] Обязательно при передаче в запросе mode = sync.

Пример ответа #

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

{
    "resultItems":[
        {
            "clientNumber":"204479",
            "row":"2",
            "orderId": "4561111",
            "created": "2018-01-01T10:00:00+03:00"
        },
        {
            "clientNumber":"204480",
            "row":"5",
            "orderId": "4561112",
            "created": "2018-01-01T10:00:00+03:00"
        }
    ],
    "base64":null
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <resultItems>
        <item>
            <clientNumber>204479</clientNumber>
            <row>2</row>
            <orderId>4561111</orderId>
            <created>2018-01-01T10:00:00+03:00</created>
        </item>
        <item>
            <clientNumber>204480</clientNumber>
            <row>5</row>
            <orderId>4561112</orderId>
            <created>2018-01-01T10:00:00+03:00</created>
        </item>
    </resultItems>
    <base64>null</base64>
</response>

Структура ответа API при ошибках #

РазделПараметрОписаниеТипОбязательныйПример
codeКод ошибкиЧислоДа040000
messageОписание типа ошибкиСтрокаДаОшибка валидации
descriptionОписание ошибкиСтрокаНетОбщая ошибка валидации, смотрите документацию
moreInfoДополнительная информацияСтрокаНетВопросы пишите на адрес support@apiship.ru
errorsМассив значенийМассивНет
fieldПоле запроса к которому относится ошибкаСтрокаДаlogin

Пример данных ошибки #

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

{
    "resultItems": [
        {
            "clientNumber": "204479",
            "row": 2,
            "code": "040002",
            "message": "Ошибка валидации",
            "description": "Ошибка валидации",
            "moreInfo": "Вопросы пишите на адрес support@apiship.ru",
            "errors": [
                {
                    "field": "clientNumber",
                    "message": "«Номер заказа в системе клиента» должен быть уникальным в пределах одной компании клиента"
                },
                {
                    "field": "recipient.countryCode",
                    "message": "Необходимо заполнить «Код страны»."
                }
            ]
        },
        {
            "clientNumber": "2q0447911",
            "row": 4,
            "code": "040002",
            "message": "Ошибка валидации",
            "description": "Ошибка валидации",
            "moreInfo": "Вопросы пишите на адрес support@apiship.ru",
            "errors": [
                {
                    "field": "clientNumber",
                    "message": "«Номер заказа в системе клиента» должен быть уникальным в пределах одной компании клиента"
                },
                {
                    "field": "recipient.countryCode",
                    "message": "Необходимо заполнить «Код страны»."
                }
            ]
        }
    ],
    "base64": null
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <resultItems>
        <item>
            <clientNumber>204479</clientNumber>
            <row>2</row>
            <code>040002</code>
            <message>Ошибка валидации</message>
            <description>Ошибка валидации</description>
            <moreInfo>Вопросы пишите на адрес support@apiship.ru</moreInfo>
            <errors>
                <item>
                    <field>clientNumber</field>
                    <message>«Номер заказа в системе клиента» должен быть уникальным в пределах одной компании клиента</message>
                </item>
                <item>
                    <field>recipient.countryCode</field>
                    <message>Необходимо заполнить «Код страны».</message>
                </item>
            </errors>
        </item>
        <item>
            <clientNumber>2q0447911</clientNumber>
            <row>4</row>
            <code>040002</code>
            <message>Ошибка валидации</message>
            <description>Ошибка валидации</description>
            <moreInfo>Вопросы пишите на адрес support@apiship.ru</moreInfo>
            <errors>
                <item>
                    <field>clientNumber</field>
                    <message>«Номер заказа в системе клиента» должен быть уникальным в пределах одной компании клиента</message>
                </item>
                <item>
                    <field>recipient.countryCode</field>
                    <message>Необходимо заполнить «Код страны».</message>
                </item>
            </errors>
        </item>
    </resultItems>
    <base64>null</base64>
</response>

  1. Заполнение поля url не обязательно, если заполнено поле base64. ↩︎

  2. Заполнение поля base64 не обязательно, если заполнено поле url. ↩︎

  3. При значении true (1) предполагается, что для каждого товара из одного заказа есть строка с полной информацией о заказе, то есть отсутствует перекрытие колонок. При значении false (0) предполагается, что информация о товарах находится под информацией о заказе (на следующей за ней строке), то есть присутствует перекрытие некоторых столбцов. ↩︎

  4. Следует учитывать наличие описательных заголовков столбцов, так как считывание не должно начинаться с такой строки, то есть значение поля rowStart должно равняться следующему за заголовочной строкой номеру. ↩︎

  5. Значения полей в данном разделе представляют собой обозначения столбцов, то есть расставляется соответствие поля заказа и названия столбца. ↩︎

  6. Обязательно, если тип забора(получения) (order.deliveryType) = 2, то есть забор/получение на ПВЗ. ↩︎

  7. Заполнение поля addressString обязательно, если не заполнены другие обязательные поля адреса (countryCode,city,region,street). В случае заполнения addressString - адрес будет разобран на составляющие и будут использоваться данные полученные в следствии разбора строки addressString. ↩︎

  8. Данное поле после точки должно содержать значение extraParamName соответствующей службы доставки. Количество полей, начинающихся с extraParams, ограничено лишь списком доступных дополнительных услуг, список которых для каждого провайдера можно получить в документации api по ссылке https://api.apiship.ru/doc/#!/lists/getListServices. ↩︎

  9. В данном разделе можно передавать несколько параметров со значением по умолчанию. Также доступно использование функции подсчёта суммы для поля, например, “cost.codCost”: “sumByOrderRows(J)” - данное значение поля укажет на то, что в cost.codCost нужно поместить сумму значений из колонки J текущего обрабатываемого заказа. ↩︎