Skip to main content

/api/lite/purchase_orders

Запрос списка поставок на склад (заказов поставщиков)

/api/lite/purchase_orders

Метод возвращает список заказов с заданной фильтрацией.

Можно использовать как для получения списка, так и единичного заказа.

 

Фильтрация

Для фильтрации есть следующие возможности:

  • id - по номеру заказа
  • filter_states - по статусам заказов (можно указывать несколько через зяпятую) 
  • filter_external_id, filter_external_id_2, filter_external_id_3, filter_external_id_4, filter_external_id_5 - по внешним идентификаторам
  • date_from - по дате заказа, от.    формат: 2020-02-19T12:35:31
  • date_to - по дате заказа, до
  • updated_from - по дате/времени изменения. формат: 2020-02-19T12:35:31. Не суммируется с другими параметрами фильтрации
  • supllier_id - по id поставщика
  • consignor_id - по id грузоотправителя
  • date_of_accept_from - по фактической дате приемки, от. формат 2020-02-19T12:35:31
  • date_of_accept_to - по фактической дате приемки, до. формат 2020-02-19T12:35:31
  • arrival_date_from - по фактической дате прибытия поставки на склад, от. формат 2020-02-19T12:35:31
  • arrival_date_to - по фактической дате прибытия поставки на склад, до. формат 2020-02-19T12:35:31
  • statuses - список статусов поставки через запятую

 

Пейджинация

Для пейджинации используются параметры page и size: size - записей на странице, page - номер страницы.

Пример: /api/lite/orders?page=0&size=200

Если параметры не переданы, то дефолтные значения page=0&size=100

Также для отображение пейджинации следует анализировать параметр recordsTotal, возвращающий общее количество записей (с учетом примененной фильтрации, если она есть).

 

Сортировка

Для сортировки задается параметр order, принимающий код поля для сортировки и направление сортировки (asc, desc), отделенное символом плюса.

Пример сортировки по дате (возрастание): /api/lite/orders?order=date+asc

Пример сортировки по дате (убывание): /api/lite/orders?order=date+desc

Доступные коды сортировки:

  • date (дата заказа)
  • id (номер заказа)

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

Полный комплект данных по заказам будет передан только если в запросе будет параметр full_info=true

Точечное описание некоторых полей, которые возвращает запрос по поставкам

purchaseArrivalDate формат 2021-04-02 15:50:48.032 фактическая дата прихода поставки на склад
finishlDate формат 2021-04-02 15:50:48.032  фактическая дата закрытия поставки
date формат 2021-04-02 15:50:48.032  дата создания поставки в лк Кактус
status статус поставки
supplier объект, содержит информацию о поставщике
consignor объект, содержит информацию о грузоотправителе
files список объектов, содержит информацию о файлах в поставке
warehouseName  название склада
warehouseCode код склада
comment комментарий к поставке

 

 

Пример запроса по одному заказу и полными данными:

GET api/lite/purchase_orders?id=1001&full_info=true

Пример результата запроса

{
    "purchaseOrders": [
        {
            "confirmStatus": "APPROVED",
            "currency": "RUB",
            "date": "2025-11-24 12:28:52",
            "factItems": [
                {
                    "article": "dvn",
                    "barcode": "127351263",
                    "batchAccountingAttributes": {
                        "batchAccountingNumber": "1-4",
                        "expirationDate": "2025-10-01",
                        "productionDate": "2022-10-02",
                        "useBatchAccounting": true,
                        "useExpiration": true
                    },
                    "factBatchAccountingAttributes": [
                        {
                            "batchAccountingNumber": "1-4",
                            "expirationDate": "2025-10-01",
                            "productionDate": "2022-10-02",
                            "useBatchAccounting": true,
                            "useExpiration": true
                        }
                    ],
                    "name": "Маска для волос Davines",
                    "num": 1,
                    "productId": "1256636009",
                    "quantity": 0,
                    "quantityDefective": 0,
                    "quantityFact": 20,
                    "quantityRaw": 20,
                    "skuType": "SKU",
                    "sum": 0,
                    "variantId": "566335809"
                }
            ],
            "files": [
                {
                    "fileExt": "pdf",
                    "fileName": "mx1.pdf",
                    "fileSource": "FULFILLMENT",
                    "fileType": "PDF",
                    "id": "e65bdeb6-a966-d0fd-3765-441334a536d9",
                    "success": true,
                    "url": "https://storage.yandexcloud.net/cactuswms/3b808083-7b6c-43ae-aa3e-48f5c161240d.pdf"
                },
                {
                    "fileExt": "pdf",
                    "fileName": "torg2.pdf",
                    "fileSource": "FULFILLMENT",
                    "fileType": "PDF",
                    "id": "19f46185-8fe7-f352-660e-b65aae210ad6",
                    "success": true,
                    "url": "https://storage.yandexcloud.net/cactuswms/c04781b1-4127-4a33-905f-5efe98d816f3.pdf"
                }
            ],
            "finishDate": "2025-11-24 12:31:54",
            "hasLinkedOrders": false,
            "id": "1006896419",
            "isTakeInDiff": true,
            "items": [
                {
                    "article": "dvn",
                    "barcode": "127351263",
                    "batchAccountingAttributes": {
                        "batchAccountingNumber": "1-4",
                        "expirationDate": "2025-10-01",
                        "productionDate": "2022-10-02",
                        "useBatchAccounting": true,
                        "useExpiration": true
                    },
                    "factBatchAccountingAttributes": [
                        {
                            "batchAccountingNumber": "1-4",
                            "expirationDate": "2025-10-01",
                            "productionDate": "2022-10-02",
                            "useBatchAccounting": true,
                            "useExpiration": true
                        }
                    ],
                    "name": "Маска для волос Davines",
                    "num": 1,
                    "productId": "1256636009",
                    "quantity": 0,
                    "quantityDefective": 0,
                    "quantityFact": 20,
                    "quantityRaw": 20,
                    "skuType": "SKU",
                    "sum": 0,
                    "variantId": "566335809"
                }
            ],
            "planItems": [
                {
                    "article": "dvn",
                    "barcode": "876543",
                    "factBatchAccountingAttributes": [],
                    "multiplicity": 10,
                    "name": "Маска для волос Davines (Квант 10 шт)",
                    "num": 1,
                    "optionsUsed": [],
                    "price": 2000.00,
                    "productId": "1256636009",
                    "quantity": 20,
                    "quantityDefective": 0,
                    "quantityFact": 0,
                    "quantityRaw": 0,
                    "skuType": "SKU",
                    "sum": 400000.00,
                    "variantId": "566335810",
                    "vatRate": "NO_VAT"
                }
            ],
            "purchaseArrivalDate": "2025-11-24 12:29:50",
            "status": "COMPLETED_WITH_DIFFERENCE",
            "supplier": {
                "id": "096e2fba-3cf9-2df1-f83c-50f51f1ffef4",
                "name": "Романова Виктория",
                "person": {
                    "address": {
                        "area": "",
                        "block": "",
                        "building": "",
                        "city": "",
                        "country": "Россия",
                        "countryCode": "RU",
                        "flat": "",
                        "house": "",
                        "region": "",
                        "settlement": "",
                        "street": "",
                        "zip": ""
                    },
                    "alternativePhone": "",
                    "fullName": "Романова Виктория",
                    "name": "Виктория",
                    "passport": {},
                    "phone": "79999999999",
                    "surname": "Романова"
                },
                "type": "PERSON"
            },
            "takeInType": "STANDARD",
            "totalFactOrderSum": 0,
            "totalFactQuantity": 20,
            "totalFactVATSum": 0,
            "totalOrderSum": 400000.00,
            "totalQuantity": 200,
            "totalVATSum": 0.00,
            "updateTs": "2025-11-24 12:32:33.610",
            "warehouseCode": "21ad85be-09a9-c4f8-72e1-4976f9d5bda6",
            "warehouseFFExportError": false,
            "warehouseFFExported": true,
            "warehouseFFSync": true,
            "warehouseFFSyncDate": "2025-11-24 12:28:55",
            "warehouseName": "NEW WMS!"
        }
    ],
    "recordsTotal": 1,
    "success": true
}

 

Ниже — официальное дополнение к текущей инструкции.
Текст оформлен так, чтобы его можно было напрямую вставить в существующий документ (рекомендуемое место — после раздела «Точечное описание некоторых полей» или перед примерами ответов).

Дополнение. Плановые и фактические позиции поставки (planItems, factItems)

В ответе метода
GET /api/lite/purchase_orders
(при использовании параметра full_info=true) для поставки могут возвращаться дополнительные наборы товарных строк:

  • planItems

  • factItems

Данные поля предназначены для разделения плановых данных клиента и фактических данных складской приемки.

Общая схема данных поставки

Для одной поставки система может возвращать до трёх наборов товарных позиций:

Поле Описание
planItems План поставки — данные, переданные клиентом
factItems Фактическая приемка — данные, зафиксированные складом
items Текущее агрегированное состояние поставки

planItems — план поставки

planItems содержит плановые позиции поставки, сформированные на основании данных, переданных клиентом при создании или редактировании заказа поставщику (POST /api/lite/purchase_orders).

Характеристики planItems

  • Формируются только из данных клиента

  • Не изменяются складом

  • Фиксируют исходные плановые количества и цены

  • Используются как эталон для сравнения с фактической приемкой

  • До начала приемки:

    • quantityFact = 0

    • quantityRaw = 0

Назначение

  • Анализ плановых поставок

  • Сравнение план / факт

  • Выявление расхождений при приемке

Пример planItems

"planItems": [
  {
    "num": 1,
    "variantId": "566335837",
    "productId": "1256636029",
    "barcode": "25704_1",
    "name": "Плакат 25704",
    "quantity": 2000,
    "price": 5.00,
    "vatRate": "NO_VAT",
    "quantityFact": 0,
    "quantityRaw": 0,
    "quantityDefective": 0,
    "sum": 10000.00,
    "skuType": "PACKING_MATERIAL_OTHER",
    "factBatchAccountingAttributes": [],
    "optionsUsed": []
  }
]

factItems — факт приемки поставки

factItems содержит фактически принятые складом товарные позиции.

Характеристики factItems

  • Формируются автоматически складской системой

  • Наполняются в процессе приемки, по мере сканирования и учета товара

  • Могут отличаться от planItems по количеству

  • Используются для расчета фактических итогов и расхождений

Поведение factItems во времени

Этап поставки Состояние factItems
До начала приемки Отсутствуют или пустые
Приемка в процессе Частично заполнены
Приемка завершена Полностью отражают фактически принятый товар

Пример factItems

"factItems": [
  {
    "num": 1,
    "variantId": "566335837",
    "productId": "1256636029",
    "barcode": "25704_1",
    "name": "Плакат 25704",
    "quantity": 2000,
    "quantityFact": 2000,
    "quantityRaw": 2000,
    "quantityDefective": 0,
    "price": 5.00,
    "vatRate": "NO_VAT",
    "sum": 10000.00,
    "skuType": "PACKING_MATERIAL_OTHER"
  }
]

items — текущее состояние поставки

Поле items отражает текущее агрегированное состояние товарных строк поставки.

Правила формирования

  • До начала приемки — соответствует planItems

  • В процессе приемки — отражает частично принятые данные

  • После завершения приемки — как правило совпадает с factItems

Рекомендации

  • Для отображения текущего состояния поставки использовать items

  • Для анализа и контроля расхождений использовать planItems и factItems

Связь с статусами поставки

Статус поставки planItems factItems
NEW Есть Нет
READY_TO_TAKE_IN Есть Нет
TAKE_IN_PROCESS Есть Заполняются
COMPLETED Есть Есть
COMPLETED_WITH_DIFFERENCE Есть Есть (есть расхождения)
DIFFERENCE Есть Есть
CANCELED Есть Нет

Пример запроса по списку поставок:

GET /api/lite/purchase_orders

Пример результата запроса:

{
  "success": true,
  "recordsTotal": 2,
  "purchaseOrders": [
    {
      "id": "1001",
      "externalId": "extId",
      "externalId2": "extId2",
      "externalId3": "extId3",
      "externalId4": "extId4",
      "externalId5": "extId5",
      "date": "2021-04-02 15:50:41",
      "updateTs": "2021-04-02 15:50:48.032",
      "status": "COMPLETED",
      "totalOrderSum": 0,
      "comment": "",
      "totalQuantity": 100,
      "supplier": {
        "id": "da1686cf-0551-db1d-57b9-c04120309fae",
        "type": "PERSON",
        "role": null,
        "name": "Розничный покупатель",
        "organization": null,
        "person": {
          "name": "",
          "surname": "",
          "patronymic": "",
          "fullName": "Розничный Покупатель",
          "phone": "",
          "rawPhone": null,
          "alternativePhone": "",
          "email": null,
          "post": null,
          "personType": null,
          "address": {
            "country": null,
            "countryCode": null,
            "region": null,
            "area": null,
            "city": null,
            "settlement": null,
            "street": null,
            "house": null,
            "block": null,
            "building": null,
            "flat": null,
            "fullAddress": null,
            "fullCity": null,
            "rawData": null,
            "zip": null,
            "regionFias": null,
            "areaFias": null,
            "cityFias": null,
            "settlementFias": null
          }
        }
      },
      "items": [
        {
          "num": 1,
          "variantId": "1001",
          "productId": "1001",
          "name": "товар тест 3",
          "quantity": 100,
          "quantityFact": 100,
          "quantityRaw": 100,
          "quantityDefective": 0,
          "vatRate": "NO_VAT",
          "price": 0,
          "img": "https://storage.yandexcloud.net/images-k2c/05d7a992-1c61-4f39-87c6-1401405055e2.jpg",
          "skuType": "SKU",
          "barcode": "",
          "orderDocId": "5703-1013"
        }
      ],
      "files": [
                {
                    "id": "43f79bac-0d82-2d82-f11d-abd1a53b26a0",
                    "fileType": "PDF",
                  	"fileSource": "FULFILLMENT", //ESHOP | USER
                    "fileName": "МХ1",
                    "fileExt": "pdf",
                    "url": "https://yadi.sk/d/BzKXkRigQZtVnB",
                    "printWhenPacking": true,
                    "copiesQty": 1
                }
           	 ],
      "warehouseName": "Свой склад",
      "warehouseCode": "373b1e28-a6d7-545f-9303-65af3a652d48",
      "confirmStatus": "APPROVED",
      "warehouseFFExported": false,
      "warehouseFFSync": false,
      "currency": "RUB"
    },
    
    {
      "id": "1002",
      "date": "2021-04-03 15:50:41",
      "updateTs": "2021-04-02 15:50:48.032",
      "status": "COMPLETED",
      "totalOrderSum": 0,
      "comment": "",
      "totalQuantity": 100,
      "supplier": {
        "id": "da1686cf-0551-db1d-57b9-c04120309fae",
        "type": "PERSON",
        "role": null,
        "name": "Розничный покупатель",
        "organization": null,
        "person": {
          "name": "",
          "surname": "",
          "patronymic": "",
          "fullName": "Розничный Покупатель",
          "phone": "",
          "rawPhone": null,
          "alternativePhone": "",
          "email": null,
          "post": null,
          "personType": null,
          "address": {
            "country": null,
            "countryCode": null,
            "region": null,
            "area": null,
            "city": null,
            "settlement": null,
            "street": null,
            "house": null,
            "block": null,
            "building": null,
            "flat": null,
            "fullAddress": null,
            "fullCity": null,
            "rawData": null,
            "zip": null,
            "regionFias": null,
            "areaFias": null,
            "cityFias": null,
            "settlementFias": null
          }
        }
      },
      "items": [
        {
          "num": 1,
          "variantId": "1001",
          "productId": "1001",
          "name": "товар тест 3",
          "quantity": 100,
          "quantityFact": 100,
          "quantityRaw": 100,
          "quantityDefective": 0,
          "vatRate": "NO_VAT",
          "price": 0,
          "img": "https://storage.yandexcloud.net/images-k2c/05d7a992-1c61-4f39-87c6-1401405055e2.jpg",
          "skuType": "SKU",
          "barcode": ""
        }
      ],
      "files": [
                {
                    "id": "43f79bac-0d82-2d82-f11d-abd1a53b26a0",
                    "fileType": "PDF",
                  	"fileSource": "FULFILLMENT", //ESHOP | USER
                    "fileName": "МХ1",
                    "fileExt": "pdf",
                    "url": "https://yadi.sk/d/BzKXkRigQZtVnB",
                    "printWhenPacking": true,
                    "copiesQty": 1
                }
           	 ],
      "warehouseName": "Свой склад",
      "warehouseCode": "373b1e28-a6d7-545f-9303-65af3a652d48",
      "confirmStatus": "APPROVED",
      "warehouseFFExported": false,
      "warehouseFFSync": false,
      "currency": "RUB"
    }
  ]
}

 

Возможные статусы заказа:
NEW
READY_TO_TAKE_IN
TAKE_IN_PROCESS
COMPLETED
COMPLETED_WITH_DIFFERENCE
DIFFERENCE
CANCELED

Создание/редактирование поставки (заказа поставщику)

/api/lite/purchase_orders

Создание/редактирование заказа для кабинета.

Если указан параметр id - то система будет пробовать найти заказ с указанным номером и отредактировать его, иначе - создаст новый с указанным id.

Если параметр id не указан - система создаст новый заказ и присвоит внутренний номер.

 

Поле Тип Обязательный Комментарий
warehouseCode string да Код склада на который будет поставка, из справочника складов аккаунта
supplier Объект да Данные о поставщике из справочника контрагентов аккаунта
supplier.id string да

Код контрагента-поставщика из справочника контрагентов аккаунта.
Также можно использовать внешний код контрагента. Для этого нужно передавать его в поле extId. В таком случае поле id можно уже не передавть.
consignor Объект нет Данные о грузоотправителе из справочника контрагентов аккаунта
consignor.id string нет Код контрагента-грузоотправителя из справочника контрагентов аккаунта

items

 

 Объект да Текущее агрегированное состояние поставки
planItems Объект да План поставки — данные, переданные клиентом
factItems Объект да Фактическая приемка — данные, зафиксированные складом
items.num integer да Номер строки (последовательно с 1, без пропусков)
items.quantity integer да Количество товара (более 0)
items.price money да Цена за шт
items.vatRate

enum

Значения: NO_VAT,

VAT_0, VAT_10, VAT_20

 да Ставка НДС
items.variantId string да (если настроен поиск по этому полю) Код товара в аккаунте 
items.variantExtId string да (если настроен поиск по этому полю) Внешний код товара в аккаунте 
items.tag string нет Тег, присвоенный товару
searchColumnType enum:
HUMANID - дефолтный, можно не передавать, если не требуется другой,
EXTID,
ARTICLE,
BARCODE		 Обязательный, если нужен поиск не по variantId  
items.orderDocId string нет Для согласованных кроссдок поставок - номер привязанного заказа
items.batchAccountingAttributes Объект нет Атрибуты партии для данного товара
confirmStatus

enum 
Значения: APPROVED, NEED_CONFIRM, 

CANCELED

 нет Статус подтверждения. Только если статус = APPROVED - поставка выгружается на склад для приемки.
comment string нет Комментарий к поставке для склада
dateOfDeliveryPlan DateTime нет Ориентровочная дата поступления поставки
externalId - externalId5 string нет Внешние коды поставки из клиенстких систем

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

{
  
  "id": "1006896489",
  "items": [
    {
      "article": "dvn",
      "barcode": "876543",
      "factBatchAccountingAttributes": [],
      "multiplicity": 10,
      "name": "Маска для волос Davines (Квант 10 шт)",
      "num": 1,
      "optionsUsed": [],
      "price": 2000,
      "productId": "1256636009",
      "quantity": 20,
      "quantityDefective": 0,
      "quantityFact": 0,
      "quantityRaw": 0,
      "skuType": "SKU",
      "sum": 400000,
      "variantId": "566335810",
      "vatRate": "NO_VAT"
    }
  ],
  "paymentStatus": "NOT_PAID",
  "planItems": [
    {
      "num": 1,
      "variantId": "566335810",
      "productId": "1256636009",
      "name": "Маска для волос Davines ",
      "quantity": 20,
      "quantityRaw": 0,
      "price": 2000,
      "vatRate": "NO_VAT",
      "article": "dvn",
      "skuType": "SKU",
      "orderDocId": null,
      "shortName": "Маска для волос Davines"
    },
    {
      "num": 2,
      "variantId": "121220209",
      "productId": "34563121212",
      "name": "Крем для волос Davines ",
      "quantity": 1,
      "quantityRaw": 0,
      "price": 3500,
      "vatRate": "NO_VAT",
      "article": "dvnwow6",
      "skuType": "SKU",
      "orderDocId": null,
      "shortName": "Крем для волос Davines"
    }

 

В ответ возвращается:

{
    "success": true,
    "orderId": "111",
    "c": "2b92b631-7f1b-c52a-897e-30bc628f87e5"
}

 

Ошибка: 

{
"success": false,
"errors": [
 {
 "code": 0,
 "message": "Текст ошибки"
 }
]
}
Наверх