QUINCE API. Повернення від покупця

Список методів

Отримання списку документів повернення від покупця

Назва методу: /api/v2/document/outgoing_return/list

Повертає список документів повернення від покупця. Для навігації використовується номер сторінки page. Розмір сторінки фіксований і дорівнює 100 елементам.

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

Якщо DateFrom і DateTo не передані та немає фільтра Id, API повертає документи за поточний день. Якщо передати тільки одну з дат, API поверне помилку DateFrom and DateTo are required.

Основні поля відповіді

Поля рядків Rows

Приклад запиту

{
  "filter": {
    "DateFrom": "2026-03-01",
    "DateTo": "2026-03-31"
  },
  "page": 1
}

Створення повернення від покупця

Назва методу: /api/v2/document/outgoing_return/add

Метод створює один документ за запит. Основний сценарій - створення повернення на основі документа-джерела через ParentDoc, наприклад на основі замовлення покупця. API використовує той самий механізм копіювання, що й інтерфейс QUINCEFIN: реквізити та рядки беруться з документа-джерела, після чого їх можна уточнити в запиті.

Цей endpoint є відповіддю на сценарій, коли зовнішня система вже має Id замовлення покупця в QUINCEFIN і повинна створити документ Повернення від покупця програмно. Для створення на основі замовлення передайте ParentDoc з Id замовлення. Якщо потрібно повернути не всі позиції, передайте власний масив Rows з потрібними товарами та кількостями.

Якщо array відсутній або не є масивом, API повертає Not valid format or empty array. Якщо передати більше одного документа, API поверне помилку Only one record can be added at a time.

Поля запиту

Поля рядків

Приклад створення на основі замовлення

{
  "array": [
    {
      "ParentDoc": 12345,
      "Date": "2026-06-01",
      "Comment": "Повернення товару за замовленням покупця",
      "Fixed": false
    }
  ]
}

У відповіді API повертає success: true і data[].Id створеного повернення. Якщо передати Fixed: true, документ буде проведено після створення або в елементі data повернеться поле Message з текстом помилки проведення.

Мінімальний робочий сценарій для інтеграції:

1. Отримайте або збережіть Id замовлення покупця з /api/v2/order/list або /api/v2/order/add.
2. Викличте /api/v2/document/outgoing_return/add з ParentDoc.
3. Якщо повернення часткове, передайте Rows тільки з позиціями, які повертаються.
4. Передайте Fixed: true, якщо документ потрібно одразу провести.
5. Якщо проведення не вдалося, перевірте поле Message у відповіді та проведіть документ після виправлення даних через update.

Приклад створення з уточненням рядків

{
  "array": [
    {
      "ParentDoc": 12345,
      "Date": "2026-06-01",
      "Comment": "Часткове повернення за замовленням покупця",
      "Fixed": true,
      "Rows": [
        {
          "Product": 1001,
          "Qty": 1,
          "Price": 450.00,
          "Sum": 450.00
        }
      ]
    }
  ]
}

Оновлення повернення від покупця

Назва методу: /api/v2/document/outgoing_return/update

Метод оновлює один документ за запит. Якщо передати більше одного документа, API поверне помилку Only one record can be updated at a time.

Для зміни рядка передайте його Id, який повертається у списку документів у полі Rows. Якщо рядок передати без Id, API створить новий рядок. Рядки, яких немає в переданому масиві, видаляються з документа.

Приклад оновлення

{
  "array": [
    {
      "Id": 67890,
      "Date": "2026-06-02",
      "Comment": "Уточнене часткове повернення",
      "Fixed": false,
      "Rows": [
        {
          "Id": 70001,
          "Product": 1001,
          "Qty": 1,
          "Price": 450.00,
          "Sum": 450.00
        }
      ]
    }
  ]
}

Проведення документа

Окремого endpoint fix для цього документа немає. Його аналог для інтеграційного сценарію:

• при POST /api/v2/document/outgoing_return/add передати Fixed: true
• або при POST /api/v2/document/outgoing_return/update передати Fixed: true.

API зберігає документ і викликає проведення після збереження.

Якщо потрібно спочатку створити чернетку, передайте Fixed: false або не передавайте це поле. Пізніше той самий документ можна провести через update з Id документа і Fixed: true.

Зняття з проведення

Назва методу: /api/v2/document/outgoing_return/unpublish

Метод знімає з проведення один документ за запит. Він викликає Document.UnApply: документ не видаляється і не архівується. Якщо array відсутній, не є масивом, містить більше одного документа або не має Id, API поверне помилку.

Приклад запиту

{
  "array": [
    {
      "Id": 67890
    }
  ]
}

Після успішного виконання документ лишається в системі, але його рухи скасовуються. Для повторного проведення оновіть документ через update з Fixed: true або проведіть його в інтерфейсі QUINCEFIN.