← Назад
ordersПочатківець⏱️ 5 хв читання

Як отримати відразу список реалізацій з товарами?

Як одним запитом отримати документи реалізації разом зі складом товарів — без окремих запитів по кожному документу. Параметри, приклад відповіді, переваги перед /documents/list.

#documents#sales#products#reports

Метод GET /documents/sales_with_products повертає список документів реалізації (продажів) контрагента, і для кожного документа одразу приходить повний склад проданих товарів. Це найшвидший спосіб отримати дані для звіту “що і коли купував клієнт” — без додаткових запитів по кожному документу окремо.

Навіщо цей метод, а не /documents/list

GET /documents/list віддає лише “шапку” документа (номер, суму, склад, контрагента) — без товарних позицій. Щоб дізнатись, що саме продано в кожному документі, довелось би на кожен document_uuid зі списку робити окремий запит GET /documents/{type_}/{uuid}.

sales_with_products вирішує це одним запитом:

  • Менше запитів до API — зручно для інтеграцій які синхронізують документи.
  • Готовий склад товарів у відповіді — масив products з ціною, кількістю, брендом, артикулом і УКТ ЗЕД-кодом кожної позиції, без парсингу окремих документів.
  • Ті самі фільтри, що й у списку документів — період, контрагент, статус ЕДО, сортування, пагінація.
  • Спрощений формат — на відміну від /documents/list, де відповідь віддається за строгою схемою DocumentListSchema, тут повертається інформація по документу та товарами, без додаткових полів документа.

Параметри запиту

NameTypeDescription
client_uuidstring (uuid)UUID контрагента — обмежити документи одним клієнтом
periodstringПеріод фільтрації. Приймає ті самі ключі, що й GET /documents/filters/dates: today, yesterday, week, month, quarter, year, all
edo_signedstring (enum)all (за замовчуванням), signed, unsigned — фільтр за станом підписання ЕДО
directionstring (enum)asc / desc — напрямок сортування
pageintegerНомер сторінки, за замовчуванням 1
per_pageintegerКількість документів на сторінці
qstringПошук за номером документа
GET /documents/sales_with_products?period=year

Приклад відповіді

Відповідь (200 OK):

{
  "documents": [
    {
      "total": 4933.38,
      "currency": { "name": "ГРН" },
      "created_at": "2026-07-15T11:57:22Z",
      "number": "ДГ002239490",
      "document_uuid": "9333005056BAD76D11F1802B2CCB7C94",
      "carrier": {
        "uuid": "A38B158FEBD71FDF44901B05CFDE8A32",
        "name": "Доставка"
      },
      "ttn_status": {
        "status": "Доставлено",
        "period": "2026-07-15T13:55:27Z"
      },
      "delivery_config": {
        "name": "Доставка, Луцьк - 4, вул. Софії Ковалевської 250, Бунчужна Арія Валеріївна"
      },
      "products": [
        {
          "price": 304.56,
          "total": 304.56,
          "quantity": 1.000,
          "product": {
            "uuid": "A358000C2947F7AE11E23F6086AE9F60",
            "article": "32.01.82",
            "name": "Трос ручника (R) Renault Trafic/Opel Vivaro 01- (1503/1365mm)",
            "brand": { "name": "LINEX", "uuid": "812C000C2999A7E611E55EBD67259500" },
            "default_image": ""
          },
          "uct_zed": [
            {
              "code": "8708 30 99 98",
              "quantity": 1.000,
              "is_imported": true,
              "name_for_invoice": "Трос ручного гальма"
            }
          ]
        }
      ]
    }
  ]
}

Поля відповіді

FieldDescription
documents[].document_uuidUUID документа — використовується для GET /documents/download/{type_}/{uuid}/{file_type} чи перевірки підпису
documents[].numberНомер документа реалізації
documents[].total / currency.nameСума документа та валюта
documents[].carrierПеревізник доставки (null, якщо не застосовний)
documents[].ttn_statusСтатус ТТН (status) і час останньої зміни статусу (period)
documents[].delivery_config.nameОпис профілю доставки — перевізник, адреса, отримувач одним рядком
documents[].products[]Товарні позиції документа
products[].price / total / quantityЦіна за одиницю, сума позиції, кількість
products[].productКартка товару: uuid, article, name, brand, default_image
products[].uct_zed[]Код УКТ ЗЕД, кількість, ознака імпорту (is_imported)

Пошук

Пошук ендпоінтів, гайдів, туторіалів, реліз-ноутів по всьому порталу