Дерево страниц
Перейти к концу метаданных
Переход к началу метаданных

Введение

API предназначен для управления данными в системе "Кактус" из внешних приложений. Позволяет синхронизировать работу вашей системы (интернет-магазина, ERP и других) с учётом данных в системе "Кактус".

API основывается на принципах REST. Обмен осуществляется в формате JSON по протоколу HTTPS посредством выполнения запросов GET | POST.

Ссылка для обращения общая для всех аккаунтов, например, для создания новых элементов номенклатуры, используется вызов:


POST https://app.kak2c.ru/api/v1/items


При вызове запроса, следует передавать следующие Headers:

  • Content-Type: application/json
  • Authorization: Basic (логин_пароль)

Для авторизации запросов используется Basic-авторизация, указывается логин и пароль зарегистрированного в системе пользователя.

Навигация

Номенклатура

Создание/редактирование номенклатуры

POST /api/v1/items

Метод создает или обновляет номенклатуру, принимая на вход массив из элементов items[].

При загрузке номенклатура, система производит поиск по полям humanid и extid, и если номенклатура найдена, проводит обновление (в противном случае создание) карточки номенклатуры.

Если по humanId и extId позиции найдено больше одного товара, то данная позиция в пакете не будет обработана и по ней будет возвращена ошибка.

Параметры
ПараметрТип \ ФорматОписание
items[]

array (массив номенклатуры)


items[][humanId]
string

Код номенклатуры, отображается пользователю.

Допускаются только цифры и латиница, и часть спец-символов.

Должен быть уникальным.

items[][extId]
string

Внешний код номенклатуры, используется для сопоставления с внешними системами.

Допускаются только цифры и латиница, и часть спец-символов.

Должен быть уникальным.

items[][article]
stringАртикул
items[][shortName]
stringСокращенное наименование номенклатуры, отображается как основное во всех формах в системе.
items[][fullName]
stringПолное наименование номенклатуры, выводится на печатные формы. Как правило, равно сокращенному наименованию, за исключением случаев, когда необходимо вывести множество дополнительной информации.
items[][description]
stringОписание номенклатуры
items[][vat]
enum

Возможные значения:

  • NO_VAT без НДС
  • VAT_0 – НДС 0%
  • VAT_10 НДС 10%
  • VAT_18 НДС 18%
  • VAT_20 НДС 20%
items[][barcodes][]
array (массив штрихкодов)
items[][barcodes][][value]
stringШтрихкод
items[][barcodes][][isDefault]
booleanПризнак основного штрихкода (например, для определения штрихкода для печати на этикетку, в случае нескольких штрихкодов у одной карточки номенклатуры)
items[][images][]
array (массив изображений)
items[][images][][url]
string

Передается прямая ссылка на картинку. Также, возможно передать саму картинку в виде base64, пример:

url("data:image/ТИП;base64,КОД")

items[][images][][description]
stringОписание картинки
items[][images][][isDefault]
booleanОтметка использования картинки в качестве заглавной
Ответ
ПараметрТип \ ФорматОписание
success
boolean

Глобальный флаг успешной передачи, имеет значение false только в случае критической ошибке, при которой не загрузилась вся номенклатура. При значении true, необходимо проверять результат загрузки по каждой переданной номенклатуре.

comment
stringКомментарий к глобальному флагу. В случае success = false, содержит описание ошибки.
result[]
array (массив результатов загрузки)
result[][humanId]
stringКод загруженной номенклатуры
result[][extId]
stringВнешний код загруженной номенклатуры
result[][success]
booleanФлаг успешной загрузки номенклатуры
result[][comment]
stringКомментарий к загрузке. Содержит описание ошибки, в случае проблем с загрузкой.


Пример запроса
{
    "items": [
        {
            "humanId"  : "humanId1",
            "extId"    : "extId1",
            "article"  : "артикул 1",
            "shortName": "краткое название 1",
            "fullName" : "полное название 1",
            "description" : "описание 1",
            "vat" : "NO_VAT",
            "barcodes" : [
                {    
                    "value" : "987654321",
                    "isDefault": "true"
                },
                {
                    "value" : "123456",
                    "isDefault": "false"
                }
            ],
            "images" : [
                {
                    "url" : "http://blahblah.com/image1.png",
                    "description" : "картинка 1",
                    "isDefault" :"true"
                }, 
                {
                    "url" : "http://blahblah.com/image2.png",
                    "description" : "картинка 2",
                    "isDefault" :"false"
                }
            ]
        },
        {
            "humanId"  : "humanId2",
            "extId"    : "extId2",
            "article"  : "артикул 2",
            "shortName": "краткое название 2",
            "fullName" : "полное название 2",
            "description" : "описание 2",
            "vat" : "VAT_18",
            "barcodes" : [
                {    
                    "value" : "111222333",
                    "isDefault": "true"
                },
                {
                    "value" : "666555444",
                    "isDefault": "false"
                }
            ],
            "images" : [
                {
                    "url" : "http://blahblah.com/image21.png",
                    "description" : "картинка 21",
                    "isDefault" :"true"
                }, 
                {
                    "url" : "http://blahblah.com/image22.png",
                    "description" : "картинка 22",
                    "isDefault" :"false"
                }
            ]
        }
    ]
}


Пример ответа
{
    "success": true,
    "comment": null,
    "result": [
        {
            "humanId": "humanId1",
            "extId": "extId1",
            "success": true,
            "comment": null
        },
        {
            "humanId": "humanId2",
            "extId": "extId2",
            "success": true,
            "comment": null
        }
    ]
}


Заказы

Создание заказа

POST /api/v1/order/add

Метод создает новый заказ в системе с указанным идентификатором humanid.

Идентификатор заказа может содержать только цифры и латинские символы. Крайне не рекомендуется использование дополнительных символов (за исключением самых базовых, таких как тире, подчеркивание и подобных), так как это может вызвать проблемы при передаче в подключенные к Кактусу системы.

Заказ может быть передан как подтвержденным (согласованным к отгрузке), так и нуждающимся в подтверждении (как правило, звонком оператора колл-центра) – с помощью параметра confirmStatus.


Параметры
ПараметрТип \ ФорматОписание
order

Объект order


order[date]
datetime

Дата заказа

order[humanId]
string

Номер заказа – основной идентификатор заказа, используется для вывода на все печатные формы, для передачи во внешние системы. Должен быть уникальным.

Идентификатор заказа может содержать только цифры и латинские символы. Крайне не рекомендуется использование дополнительных символов (за исключением самых базовых, таких как тире, подчеркивание и подобных), так как это может вызвать проблемы при передаче в подключенные к Кактусу системы.

order[externalId]
stringДополнительный идентификатор заказа, например, для технических нужд. Должен быть уникальным.
order[confirmStatus]
enum

Статус подтверждения заказа.

Заказ может быть передан как подтвержденным (согласованным к отгрузке), так и нуждающимся в подтверждении (как правило, звонком оператора колл-центра) – с помощью параметра confirmStatus.

Может иметь следующие значения:

  • NEED_CONFIRM - требуется подтверждение (согласование) заказа;
  • APPROVED - заказ подтвержден (согласован) и готов к упаковке/отгрузке.
order[confirmationType]
enum

Способ подтверждения заказа. Имеет смысл только если заказ передается не подтвержденным.

Возможные значения:

  • SELF_CONFIRM – подтверждение через встроенные рабочие места колл-центра Кактуса;
  • CALLCENTER– подтверждение через внешний колл-центр. Задание на прозвон отправляется в партнерский колл-центр для подтверждения.
order[callcenterType]
string

Идентификатор стороннего колл-центра. Имеет смысл, если confirmationType = CALLCENTER. Например, "OLINE".

order[paymentStatus]
enum

Может иметь следующие значения:

  • NOT_PAID - заказ не оплачен
  • PAID - заказ оплачен полностью (например, картой на сайте)
order[paymentMethodCode]
string

Значение способа оплаты. Передается код способа оплаты. Система позволяет создавать новые способы оплаты, либо изменить существующие.

Возможные значения по умолчанию:

  • "cod-cash" – оплата наличными;
  • "cod-card" – оплата картой курьеру;
  • "online" – предоплата картой на сайте.
order[warehouseCode]
stringСклад для отгрузки заказа. Поиск осуществляется по коду.
order[warehouseName] deprecated
string

Склад для отгрузки заказа (используется в случае, если warehouseCode пустой). Поиск осуществляется по наименованию.

Не рекомендуется использовать данный параметр.

order[rtuCreateMode]
enum

Управляет моментом для автоматического создания "Реализации товаров и услуг" по заказу. Возможные значения:

  • ON_DELIVERY – автоматически создавать "Реализацию товаров и услуг" при успешной доставке заказа;

  • ON_TAKEOUT – автоматически создавать "Реализацию товаров и услуг" при отгрузке заказа.

order[organizationInn]
string

ИНН организации, от лица которой отгружается заказ.

Если не указан, используется организация по умолчанию.

order[eshopName]
stringНаименование интернет-магазина. Свободное значение, для отображения в пользовательском интерфейсе и отчетах.
order[comment]
stringКомментарий покупателя
order[priceData]

Объект priceData

Содержит общую информацию по сумме заказа. Используется для сравнения с табличной частью.
order[priceData][currency]
stringКод валюты сумм в заказе
order[priceData][totalSumWithVat]
floatОбщая сумма заказа включая НДС
order[priceData][vatSum]
floatОбщая сумма НДС
order[deliveryData]

Объект
deliveryData


order[deliveryData][receiverPerson]
Объект
receiverPerson

order[deliveryData][receiverPerson][firstName]
stringИмя
order[deliveryData][receiverPerson][middleName]
stringОтчество
order[deliveryData][receiverPerson][lastName]
stringФамилия
order[deliveryData][receiverPerson][rawPhone]
string

Телефон (без дополнительных знаков), только цифры.

Телефон должен включать телефонный код страны, например: 79161002030.

order[deliveryData][receiverPerson][rawAlternativePhone]
string

Второй телефон (без дополнительных знаков), только цифры.

Телефон должен включать телефонный код страны, например: 74951002030.

order[deliveryData][receiverPerson][email]
stringЭлектронная почта получателя
order[deliveryData][receiverPerson][address]
Объект
address

order[deliveryData][receiverPerson][address][country]
stringКод страны (Alpha2)
order[deliveryData][receiverPerson][address][region]
stringРегион
order[deliveryData][receiverPerson][address][area]
stringРайон
order[deliveryData][receiverPerson][address][city]
stringГород
order[deliveryData][receiverPerson][address][settlement]
stringНаселенный пункт
order[deliveryData][receiverPerson][address][street]
stringУлица
order[deliveryData][receiverPerson][address][house]
stringДом
order[deliveryData][receiverPerson][address][block]
stringКорпус
order[deliveryData][receiverPerson][address][building]
stringСтроение
order[deliveryData][receiverPerson][address][flat]
stringКвартира \ офис
order[deliveryData][receiverPerson][address][fullAddress]
string

Полный адрес – необходимо заполнять только в случае, если нет возможности заполнить адрес по полям.

Полный адрес будет обновлен автоматически на основании отдельных полей (если они указаны).

order[deliveryData][receiverPerson][address][zip]
stringИндекс
order[deliveryData][deliveryCode]
stringКод канала доставки
order[deliveryData][desiredHourStart]
time

Время доставки "от".

Пример: "10:30"

order[deliveryData][desiredHourEnd]
time

Время доставки "до".

Пример: "18:00"

order[deliveryData][deliveryComment]
string

Дополнительная информация к доставке, информация для курьера.

order[deliveryData][postamatId]
stringКод постамата\пункта выдачи заказа
order[deliveryData][deliveryPrice]
float

Стоимость услуги "Доставка" для заказа.

При заполнении данного поля, автоматически будет добавлена новая строка к заказу – "Доставка" с указанной ценой и ставкой НДС по умолчанию.

Заполнение данного поля не обязательно, возможно передавать отдельную позицию "Доставка" как часть товаров.

order[items]

Объект
items


order[items][num]
integerНомер строки
order[items][sku]
Объект
sku
Информация о товаре
order[items][sku][humanId]
stringКод товара в системе "Кактус"
order[items][sku][extId]
stringВнешний код товара
order[items][quantity]
floatКоличество единиц товара
order[items][itemPriceData]
Объект
itemPriceData
Информация о стоимости товара
order[items][itemPriceData][priceWithVat]
floatСтоимость единицы товара
order[items][itemPriceData][totalWithVat]
floatОбщая стоимость по строке
order[items][itemPriceData][vat]
enum

Код ставки НДС.

Возможные значения:

  • NO_VAT – без НДС
  • VAT_0 – НДС 0%
  • VAT_10 – НДС 10%
  • VAT_18 – НДС 18%
  • VAT_20 – НДС 20%
order[items][itemPriceData][currency]
string

Код валюты.

Например: "RUB".



Пример запроса
{
  "order": {
    "date": "2018-08-15T10:45:02+03:00",
    "humanId": "2034910498",
    "comment": "",
    "externalId": "2034910498",
    "confirmStatus": "NEED_CONFIRM",
    "paymentStatus": "NOT_PAID",
    "warehouseCode": "Tempoline",
    "rtuCreateMode": "ON_TAKEOUT",
    "externalNumber": "2034910498",
    "organization-inn": "12345",
    "paymentMethodCode": "121323",
    "confirmationType": "SELF_CONFIRM",
    "callcenterType": null,
    "reserveType": "ON_IMPORT",
    "eshopName": "Ultracosmetics",
    "priceData": {
      "currency": "RUB",
      "vatSum": 280.68,
      "totalSumWithVat": 1840
    },
    "deliveryData": {
      "receiverPerson": {
        "firstName": "Олег",
        "middleName": "",
        "lastName": "Коробов",
        "rawPhone": "+7 (916) 391-2255",
        "rawAlternativePhone": "",
        "email": "korobov.oleg@gmail.com",
        "address": {
          "country": "RU",
          "region": "",
          "area": "",
          "city": "",
          "settlement": "",
          "street": "",
          "house": "",
          "block": "",
          "building": "",
          "flat": "",
          "fullAddress": "Санкт-Петербург, пр. Тореза, д.20, к.1",
          "zip": ""
        }
      },
      "deliveryCode": "GD",
      "desiredHourStart": "10:30",
      "desiredHourEnd": "20:00",
      "deliveryComment": "",
      "postamatId": "",
      "deliveryPrice": 200
    },
    "items": [
      {
        "num": 1,
        "sku": {
          "humanId": "BR00T-000117",
          "extId": "BR00T-000117"
        },
        "quantity": 1,
        "itemPriceData": {
          "priceWithVat": 1640,
          "totalWithVat": 1640,
          "vat": "VAT_18",
          "currency": "RUB"
        }
      }
    ]
  }
}
Пример ответа
{
  "order": {
    "date": "2018-08-15T10:45:02+03:00",
    "comment": "",
    "externalId": "2034910498",
    "confirmStatus": "NEED_CONFIRM",
    "paymentStatus": "NOT_PAID",
    "warehouse-name": "Tempoline",
    "rtuCreateMode": "ON_TAKEOUT",
    "externalNumber": "2034910498",
    "organization-inn": "12345",
    "payment-method-code": "Оплата наличными",
    "confirmationType": "SELF_CONFIRM",
    "callcenterType": null,
    "reserveType": "ON_IMPORT",
    "eshopName": "Ultracosmetics",
    "priceData": {
      "currency": "RUB",
      "vatSum": 280.68,
      "totalSumWithVat": 1840
    },
    "deliveryData": {
      "receiverPerson": {
        "firstName": "Георгий Иванов",
        "middleName": "",
        "lastName": "",
        "fullName": "Георгий Иванов",
        "rawPhone": "+7 (916) 391-2255",
        "rawAlternativePhone": "",
        "email": "g.ivanov@gmail.com",
        "address": {
          "country": "RU",
          "region": "",
          "area": "",
          "city": "",
          "settlement": "",
          "street": "",
          "house": "",
          "block": "",
          "building": "",
          "flat": "",
          "rawData": "Санкт-Петербург, пр. Тореза, д.20, к.1",
          "fullAddress": "Санкт-Петербург, пр. Тореза, д.20, к.1",
          "zip": ""
        }
      },
      "delivery-code": "GD",
      "desiredHourStart": "10:30",
      "desiredHourEnd": "20:00",
      "deliveryComment": "",
      "postamatId": "",
      "delivery-price": 200
    },
    "items": [
      {
        "num": 1,
        "sku": {
          "humanId": "BR00T-000117",
          "fullName": "Мега набор Ultra Cosmetics 4",
          "extId": "BR00T-000117"
        },
        "quantity": 1,
        "itemPriceData": {
          "priceWithVat": 1640,
          "totalWithVat": 1640,
          "vat": "VAT_18",
          "currency": "RUB"
        }
      }
    ]
  }
}

Состояние заказа

GET /api/v1/order


Метод позволяет получить информацию о заказе (заказах).

Поддерживается два режима поиска заказов:

  • По номеру (передается id искомого заказа)
  • Измененные заказы с определенного момента времени (передается параметр from - момент изменений).
Параметры запроса
ПараметрТип \ ФорматОписание
id
string

Идентификатор заказа.

Поиск либо по номеру заказа (humanId), либо по внешнему идентификатору заказа (externalId).

from
datetime

Момент времени, начиная с которого производится поиск изменившихся заказов


Данные ответа
ПараметрТип \ ФорматОписание
Массив заказов (order)
Массив объектов
order

Детальная информация по заказам

order

Объект
order


order[humanId]
string

Основной идентификатор заказа.

Как правило, это номер заказа, отображаемый покупателю в момент оформления заказа на сайте\маркетплейсе\прочих витринах.

Значение имеет контроль на уникальность.

order[externalId]
string

Внешний дополнительный идентификатор заказа, используемый, например для целей интеграции.

Значение имеет контроль на уникальность.

order[id]
guidВнутренний технический идентификатор заказа в системе "Кактус".
order[date]
datetimeДата заказа (по данным источника заказа).
order[updatedAt]
datetime

Дата последнего обновления заказа в системе "Кактус".

Изменяется при обновлении состояния заказа, любых изменениях.

order[comment]
stringКомментарий покупателя к заказу.
order[operatorComment]
stringКомментарий оператора к заказу. Внутренний комментарий, не отображаемый покупателю.
order[status]

enum
общий статус

Общий статус заказа, вычисляемый системой исходя из текущего состояния.

Детальнее описан в разделе: Статусы заказа клиента

order[orderVector]
enum
Общее состояние направления движения заказа:
  • IN_PROGRESS – заказ в процессе обработки, движется к выполнению
  • CANCELLING – заказ в процессе отмены, движется к отмене
  • CANCELED – заказ отменен, финальный статус
  • DONE – заказ выполнен, финальный статус
order[confirmStatus]

enum
статус подтверждения

Статус отражает состояния процесса подтверждения заказа.

Возможные значения:

  • NEED_CONFIRM – заказ нуждается в подтверждении
  • HOLD – подтверждение заказа приостановлено (например, клиент просит перезвонить позже)
  • APPROVED – заказ подтвержден, финальный статус
  • CANCELED – заказ отменен, финальный статус
  • ERROR – непредвиденная ошибка
order[paymentStatus]
enum
статус оплаты

Статус оплаты заказа:

  • PAID – заказ полностью оплачен

  • NOT_PAID – заказ не оплачен

order[ffStatus]

enum
статус комплектации

Статус задания на комплектацию (складскую обработку) заказа:

  • CREATED – задание создано
  • NEED_RESERVE – требуется резерв (отсутствует необходимое количество на остатке)
  • ON_PICKING – резерв взят, заказ на этапе подбора (комплектации)
  • PICKED (PACKED) – заказ укомплектован (собран) и готов к отгрузке
  • SHIPPED – заказ отгружен, финальный статус
  • CANCELED – заказ отменен, финальный статус
  • CANCEL_REQUESTED – затребована отмена задания на комплектацию
  • ERROR – непредвиденная ошибка
order[deliveryStatus]

enum
статус доставки

Статус задания на доставку заказа:

  • NOT_INITIALIZED / CREATED – задание создано
  • PACKED – упакован и готов к отгрузке
  • PLANNED – запланирован к доставке
  • SHIPPED_TO_COURIER – отгружен в службу доставки
  • COURIER – на доставке
  • SORT – на сортировке в курьерской службе
  • AT_TAKEOUT_POINT – в пункте выдачи заказа
  • RETURNING – на возврате
  • DELIVERED – доставлен (полностью или частично), финальный статус *
  • CANCELED – доставка отменена до начала доставки **
  • LOST – утерян
  • RETURNED – возвращен (полный возврат)
  • CANCEL_REQUESTED – запрос на отмену
  • ERROR – непредвиденная ошибка

* - если была частичная доставка, то есть доставлен хотя бы один товар, статус доставки придет в DELIVERED (финальный статус).

** - отмена доставки возможно только до начала "физического" процесса доставки, то есть до передачи отправления в службу доставки.

order[confirmMessage]
stringКомментарий системы к процессу подтверждения
order[ffMessage]
stringКомментарий системы к процессу комплектации и отгрузки
order[deliveryMessage]
stringКомментарий системы к процессу доставки
order[rtuCreateMode]
enum

Метод создания реализации по заказу:

  • ON_TAKEOUT
  • ON_DELIVERY
order[warehouseCode]
stringКод склада, с которого отгружается заказ (поле "внешний код" в настройках склада)
order[needReserve]
booleanТребуется резервирование заказа
order[reserveType]
enum

Тип резервирования заказа:

  • ON_CONFIRM
  • ON_IMPORT
order[confirmationType]
enum

Тип подтверждения:

  • SELF_CONFIRM
  • CALLCENTER
order[callcenterType]
enum
Содержит или "null" или код колл-центра
order[eshopName]
stringНаименование интернет-магазина
order[cancelComment]
stringКомментарий к отмене заказа
order[cancelReason]
stringНаименование причины отмены (из справочника системы "Причины отмены")
order[customer]
объект
customer

Содержит информацию о заказчике. Как правило, используется для объединения нескольких заказов по общему признаку "Покупатель".

Например, пользовательская учетная запись в интернет-магазине.

order[customer][extId]
stringВнешний идентификатор заказчика
order[customer][id]
guidВнутренний идентификатор в системе Кактус
order[customer][name]
stringНаименование заказчика
order[priceData]

объект
priceData

Информация об общей стоимости заказа.
order[priceData][totalSumWithVat]
decimalОбщая сумма заказа с НДС
order[priceData][vatSum]
decimalОбщая сумма НДС в заказе
order[priceData][insuranceSum]
decimal

Общая оценочная (страховая) сумма заказа.

Рассчитывается системой автоматически, исходя из настроек.

Может быть установлено вручную, если поле
insuranceSumAutoCalculation = false

order[priceData][currency]
string

Код валюты.

Например: RUB

order[insuranceSumAutoCalculation]
boolean

Признак автоматического расчета страховой стоимости.

По умолчанию включено.

order[deliveryData]

Объект
deliveryData

Содержит информацию для доставки заказа: данные получателя, адрес доставки, способ (курьерская служба) доставки.
order[deliveryData][desiredDate]
dateЖелаемая дата доставки.
order[deliveryData][desiredHourStart]
timeЖелаемый час доставки "от".
order[deliveryData][desiredHourEnd]
timeЖелаемый час доставки "до".
order[deliveryData][deliveryContract]
Объект
deliveryContract
Содержит информацию о канале доставки
order[deliveryData][deliveryContract][externalKey]
string

Внешний идентификатор канала доставки. Применяется как основной идентификатор при интеграции.

Аналогичен значению deliveryCode в методе создания заказа.

order[deliveryData][deliveryContract][id]
guidВнутренний идентификатор канала доставки в системе "Кактус".
order[deliveryData][deliveryContract][name]
stringНаименование канала доставки
order[deliveryData][receiverPerson]

Объект
receiverPerson

Содержит информацию о получателе заказа
order[deliveryData][receiverPerson][id]
guidВнутренний системный идентификатор получателя заказа
order[deliveryData][receiverPerson][firstName]
stringИмя получателя
order[deliveryData][receiverPerson][middleName]
stringОтчество (второе имя) получателя
order[deliveryData][receiverPerson][lastName]
stringФамилия получателя
order[deliveryData][receiverPerson][rawPhone]
stringТелефон в изначальном виде (как передан при создании заказа)
order[deliveryData][receiverPerson][formattedPhone]
stringФорматированный телефон (очищенный от лишних символов)
order[deliveryData][receiverPerson][rawAlternativePhone]
stringАльтернативный телефон в изначальном виде (как передан при создании заказа)
order[deliveryData][receiverPerson][formattedAlternativePhone]
stringАльтернативный форматированный телефон (очищенный от лишних символов)
order[deliveryData][receiverPerson][extId]
stringВнешний идентификатор получателя
order[deliveryData][receiverPerson][email]
stringЭлектронная почта получателя
order[deliveryData][receiverPerson][address]
Объект
address

Содержит информацию об адресе доставки получателя.

Если в системе включена автокоррекция адреса, адрес соответствует структуре ФИАС.

order[deliveryData][receiverPerson][address][country]
string

Код страны по справочнику Alpha2.

Например, "RU".

order[deliveryData][receiverPerson][address][region]
stringРегион
order[deliveryData][receiverPerson][address][area]
stringРайон
order[deliveryData][receiverPerson][address][city]
stringГород
order[deliveryData][receiverPerson][address][settlement]
stringНаселенный пункт
order[deliveryData][receiverPerson][address][street]
stringУлица
order[deliveryData][receiverPerson][address][house]
stringДом
order[deliveryData][receiverPerson][address][block]
stringКорпус
order[deliveryData][receiverPerson][address][building]
stringСтроение
order[deliveryData][receiverPerson][address][flat]
stringКвартира
order[deliveryData][receiverPerson][address][fullAddress]
string

Полный адрес.

Вычисляется автоматически сцепкой отдельных полей адреса.

order[deliveryData][receiverPerson][address][rawData]
stringСодержит "сырой" (исходный) адрес, переданный при создании заказа по API.
order[deliveryData][receiverPerson][address][fullCity]
stringПолное наименование населенного пункта \ города
order[deliveryData][receiverPerson][address][zip]
stringПочтовый индекс
order[deliveryData][postamatId]
stringИдентификатор пункта выдачи заказа (ПВЗ / постамата). Зависит от применяемого канала доставки.
order[deliveryData][deliveryComment]
stringКомментарий к адресу доставки. Например, код домофона или инструкции "как пройти".
order[deliveryPriceData]
объект
deliveryPriceData
Содержит информацию о стоимости доставки или дополнительных услуг к заказу.
order[deliveryPriceData][totalSumWithVat]
decimalОбщая сумма доставки и дополнительных услуг, с учетом НДС.
order[deliveryPriceData][vatSum]
decimalОбщая сумма НДС
order[deliveryPriceData][currency]
string

Код валюты.

Например: RUB

order[organization]
объект
ogranization
Содержит информацию об организации отправителя.
order[organization][extAccountId]
stringВнешний идентификатор организации
order[organization][id]
guidВнутренний идентификатор организации
order[organization][name]
stringНаименование организации
order[paymentMethod]
объект
paymentMethod
Содержит информацию о способе оплаты
order[paymentMethod][paymentMethod]
enum

Идентификатор способа оплаты

  • COD_CASH – наложенный платеж (наличными курьеру)
  • COD_CARD – наложенный платеж (картой курьеру)
  • ONLINE – предоплата (система контролирует факт оплаты, и не передает на склад задачу на комплектацию до подтверждения факта оплаты)
  • NO_COD – без оплаты, в данном режиме система не контролирует оплату при передаче на склад
order[paymentMethod][id]
guidВнутренний идентификатор способа оплаты в системе
order[paymentMethod][name]
string

Наименование способа оплаты

order[paymentMethod][code]
string

Внешний идентификатор способа оплаты.

Задается в настройках системы и применяется для целей интеграции.

order[deliveryServiceParams][]

массив параметров доставки

Описывает дополнительные параметры доставки заказа.

Например, услугу "примерка", или "возврат сопроводительных документов".

order[deliveryServiceParams][][id]
uidУникальный идентификатор дополнительного параметра доставки
order[deliveryServiceParams][][serviceName]
stringНаименование (код) дополнительного параметра доставки
order[deliveryServiceParams][][serviceValue]
stringЗначение дополнительного параметра доставки
order[items][]

массив
товаров

Товарные позиции (строки) заказа
order[items][][id]
uidУникальный идентификатор строки заказа
order[items][][num]
integerНомер строки заказа
order[items][][quantity]
integerКоличество товара в строке заказа
order[items][][sku]
объект
sku
Информация о товаре
order[items][][sku][humanId]
string

Основной идентификатор товара, отображается пользователю во всех экранных и печатных формах

order[items][][sku][extId]
stringВнешний дополнительный идентификатор товара (внешний код)
order[items][][sku][extAccountId]
stringИдентификатор товара для бухгалтерской системы
order[items][][sku][id]
uidВнутренний идентификатор товара в системе Кактус
order[items][][sku][shortName]
stringНаименование товара
order[items][][sku][fullName]
stringРасширенное наименование товара
order[items][][sku][article]
stringАртикул товара
order[items][][customData]
stringСодержит произвольную json структуру с дополнительными данными товарной строки заказа
order[items][][itemPriceData]
объект
itemPriceData
Описание стоимости товара в данной строке заказа
order[items][][itemPriceData][priceWithVat]
decimalЦена за единицу товара с учетом НДС
order[items][][itemPriceData][totalWithVat]
decimalОбщая стоимость по строке с учетом НДС
order[items][][itemPriceData][vat]
enum

Ставка НДС.

Возможные значения:

  • NO_VAT – без НДС
  • VAT_0 – НДС 0%
  • VAT_10 – НДС 10%
  • VAT_18 – НДС 18%
  • VAT_20 – НДС 20%
order[items][][itemPriceData][currency]
enum

Валюта стоимости.
По умолчанию - RUB.


Пример запроса
https://app.kak2c.ru/api/v1/order/?from=2018-01-01T00:00:01


Пример ответа
 {
    "orders": [
        {
            "humanId": "rrr1002",
            "date": "2018-10-18 14:02:22.000",
            "updatedAt": "2018-10-19 17:26:32.030",
            "id": "b5e0def7-5ba1-d2f9-1526-de4aca18f0e2",
            "comment": "ввести код домофона",
            "operatorComment": null,
            "externalId": "17311126",
            "ffStatus": "ERROR",
            "confirmStatus": "APPROVED",
            "paymentStatus": "NOT_PAID",
            "deliveryStatus": "NOT_INITIALIZED",
            "status": "ORDER_INFO_READY_TO_PACK",
            "deliveryData": {
                "desiredDate": "2018-10-18 21:00:00.000",
                "desiredHourStart": "00:00",
                "desiredHourEnd": "00:00",
                "deliveryContract": {
                    "externalKey": "ddd",
                    "id": "453f58e9-8b6d-d8be-3cf8-95fe0d5f431a",
                    "name": "YD темполайн black roll"
                },
                "receiverPerson": {
                    "id": "f18a8be7-2301-276b-ef81-e0fa85f4610f",
                    "firstName": "Сидоров Иван",
                    "middleName": "",
                    "lastName": "",
                    "rawPhone": "+79053650000",
                    "formattedPhone": "+79053650000",
                    "rawAlternativePhone": null,
                    "formattedAlternativePhone": null,
                    "extId": null,
                    "email": "petrov@mail.net",
                    "address": {
                        "country": "RU",
                        "region": "Москва",
                        "area": null,
                        "city": "Москва",
                        "settlement": null,
                        "street": "Озёрная",
                        "house": "23",
                        "block": "1",
                        "building": "",
                        "flat": null,
                        "fullAddress": "г Москва, Очаково-Матвеевское р-н, ул Озёрная, д 23 к 1",
                        "fullCity": null,
                        "rawData": "Москва, озерная 23",
                        "zip": "119361"
                    }
                },
                "postamatId": null,
                "deliveryComment": "ввести код домофона"
            },
            "confirmMessage": null,
            "ffMessage": "Ошибка экспорта заказа. Нет необходимого остатка у товара DF74T-000050. Требуется 1, в наличии 0",
            "deliveryMessage": null,
            "rtuCreateMode": "ON_TAKEOUT",
            "warehouseCode": "Склад Фулфилмент",
            "needReserve": true,
            "insuranceSumAutoCalculation": true,
            "reserveType": "ON_IMPORT",
            "confirmationType": "SELF_CONFIRM",
            "callcenterType": null,
            "eshopName": "insales 10",
            "orderVector": "IN_PROGRESS",
            "cancelComment": null,
            "cancelReason": null,
            "customer": {
                "extId": null,
                "id": "6916a300-b156-bb79-0e93-174d2aedb4da",
                "name": "ИВАНОВ ИВАН"
            },
            "priceData": {
                "totalSumWithVat": 2800,
                "vatSum": 273.04,
                "insuranceSum": 2500,
                "currency": "RUB"
            },
            "deliveryPriceData": {
                "totalSumWithVat": 300,
                "vatSum": 45.76,
                "insuranceSum": 0,
                "currency": "RUB"
            },
            "organization": {
                "extAccountId": null,
                "id": "0846fc5d-1693-17ce-9d52-933558ad557e",
                "name": "Моя организация"
            },
            "paymentMethod": {
                "paymentMethod": "COD_CASH",
                "id": "8f15043a-cf94-bc4c-76b9-2b695ef0d1c1",
                "name": "Оплата наличными",
                "code": "Наличным курьеру"
            },
            "deliveryServiceParams": [
                {
                    "id": "6098d8a4-1624-f593-f47b-b33f3b04b59e",
                    "serviceName": "CHECK_CONTENT",
                    "serviceValue": "false"
                },
                {
                    "id": "4255c09f-9dc9-0e15-cd20-531615e74a1d",
                    "serviceName": "PARTIAL_DELIVERY",
                    "serviceValue": "false"
                },
                {
                    "id": "db490807-f866-e53e-4eba-56939f856020",
                    "serviceName": "TRYING",
                    "serviceValue": "false"
                }
            ],
            "items": [
                {
                    "id": "104db6cd-54d0-d1d7-81e5-86da2a9c3857",
                    "num": 1,
                    "quantity": 1,
                    "sku": {
                        "humanId": "DF74T-000050",
                        "extId": null,
                        "extAccountId": null,
                        "id": "e72dbf7b-1d00-c9e4-c5f7-0a6eece59a48",
                        "shortName": "Волчонок серый, S",
                        "fullName": "Волчонок серый, S",
                        "article": "11111"
                    },
                    "customData": "",
                    "itemPriceData": {
                        "priceWithVat": 2500,
                        "totalWithVat": 2500,
                        "vat": "VAT_10",
                        "currency": "RUB"
                    }
                },
                {
                    "id": "da4505d4-3c3a-831d-949c-f90429a751e7",
                    "num": 2,
                    "quantity": 1,
                    "sku": {
                        "humanId": "DF74T-000001",
                        "extId": null,
                        "extAccountId": null,
                        "id": "8a59edbe-7ace-8a12-5c8b-7ae2b7c4477e",
                        "shortName": "Доставка",
                        "fullName": "Услуга доставки",
                        "article": null
                    },
                    "customData": "",
                    "itemPriceData": {
                        "priceWithVat": 300,
                        "totalWithVat": 300,
                        "vat": "VAT_18",
                        "currency": "RUB"
                    }
                }
            ]
        }
    ]
}


Оплата заказа

POST /api/v1/order/payments/create


Данный вызов позволяет перевести статус оплаты заказа в состояние Оплачен. Для этого необходимо передать  в вызове сумму, равную общей сумме заказа. Система на данный момент не умеет агрегировать несколько частичных оплат, поэтому необходимо передавать полную сумму одним вызовом. Если будет передана сумма, отличная от общей суммы заказа, то статус оплаты заказа не изменится. 

Структура order используется для поиска заказа, в котором надо проставить оплату. Сначала система ищет заказ по humanId = order[id] и, если заказ не найден или id не передан, то ищет по externalId = order[externalId]. Если заказ не найден или структура order не передана, то в ответе будет ошибка "Не найден заказ по заданному идентификатору."

Обязательными являются один из параметров структуры order и сумма sum. 

Запрос
ПараметрТип \ ФорматОписание
order[id]
string

HumanId заказа

order[externalId]
stringExternalId заказа
sum
floatсумма
comment
stringКомментарий
paidAt
DateTime yyyy-MM-ddTHH:mm:ssДата оплаты


Данные ответа
ПараметрТип \ ФорматОписание
success
boolean

флаг успешности

errorList
Список ошибок
errorList[errorCode]
stringкод ошибки
errorList[errorMessage]
stringописание ошибки


Пример запроса
{
	"paidAt": "2018-10-03T13:30:27",
	"sum": "505.0000",
	"comment": "",
	"order": {
		"id": "8",
		"externalId": "8"
	}
}	


Пример ответа
{
    "errorList": null,
    "success": true
}
  • Нет меток