Замовлення по API та замовлення з поштовими інтеграціями

1. Підключення та безпека (Токен доступу)

Для взаємодії з API необхідно отримати ключ доступу у вашому кабінеті:

1. Перейдіть у Налаштування компанії → Інтеграція замовлень.
   
2. Натисніть «Підключити інтеграцію».
3. Оберіть блок АПІ та натисніть «Згенерувати».

⚠️ Важливо:

• Регенерація: Створення нового токена автоматично анулює попередній. Обов’язково оновіть токен у вашій системі після кожної зміни.
• Безпека: Не передавайте токен стороннім особам. У разі компрометації — видаліть старий та створіть новий.

2. ВАРІАНТ 1: Прямі замовлення по АПІ (api_order)

Використовується для реєстрації замовлень, які створюються безпосередньо через вашу систему (без контролю поштових служб).

Усі HTTP-запити до API замовлень повинні містити наступні заголовки (Headers):

Authorization: <ваш_токен_доступу>
Content-Type: application/json

2.1. Створення замовлення

Метод: POST
URL: https://kasa.vchasno.ua/api/v1/orders
Тіло запиту (JSON):

{

    "rro_fn": "4000112233",

    "data": {

        "tag": "123456",

        "fiscal": {

            "task": 1,

            "receipt": {

                "sum": 1926.5,

                "pays": [

                    {

                        "sum": 1926.5,

                        "type": 1

                    }

                ],

                "rows": [

                    {

                        "cnt": 1,

                        "disc": 0,

                        "name": "Подарунковий набір “Квітучий настрій” до 8 березня з ароматними дрібничками, солодощами та весняною атмосферою",

                        "price": 497,

                        "taxgrp": 1

                    },

                    {

                        "cnt": 11,

                        "disc": 420.5,

                        "name": "Тюльпан Рожевий",

                        "price": 100,

                        "taxgrp": 1,

                        "disc_type": 0

                    },

                    {

                        "cnt": 10,

                        "disc": 0,

                        "code": 954,

                        "name": "Тюльпан Білий",

                        "price": 75,

                        "taxgrp": 1

                    }

                ],

                "comment_down": "Коментар до чеку"

            }

        },

        "userinfo": {

            "email": "[email protected]"

        }

    },



    "order_number": "123-LK",

    "notation": "Доставка квітів м. Київ, вул. Хрещатик 99"

}

Опис полів:
rro_fn (string) — Обов’язкове. Фіскальний номер каси.
order_number (string) — Номер замовлення у вашій системі. Від 1 до 128 будь-яких символів. Значення може використовувати для пошуку за номером замовлення у вебкабінеті Вчасно.Каса
notation (string) — Примітка. Дозволено від 1 до 512 будь-яких символів. Значення використовується для пошуку за приміткою у вебкабінеті Вчасно.Каса.
data (object) — Обов’язкове. Об’єкт з даними чека. Детальний опис полів data (Postman).

Відповідь: Повертається UUID замовлення. (Власні ID створювати не можна, ідентифікатор генерується нашою системою).

⚠️ Не можна занулити наступні поля: order_number, notation, rro_fn, data

Приклад:

curl --location 'https://kasa.vchasno.ua/api/v1/orders' \
--header 'Content-Type: application/json' \
--header 'Authorization: <токен_доступу>' \
--data-raw '{
    "rro_fn": "4000112233",
    "data": {
        "tag": "123456",
        "fiscal": {
            "task": 1,
            "receipt": {
                "sum": 1926.5,
                "pays": [
                    {
                        "sum": 1926.5,
                        "type": 1
                    }
                ],
                "rows": [
                    {
                        "cnt": 1,
                        "disc": 0,
                        "name": "Подарунковий набір “Квітучий настрій” до 8 березня з ароматними дрібничками, солодощами та весняною атмосферою",
                        "price": 497,
                        "taxgrp": 1
                    },
                    {
                        "cnt": 11,
                        "disc": 420.5,
                        "name": "Тюльпан Рожевий",
                        "price": 100,
                        "taxgrp": 1,
                        "disc_type": 0
                    },
                    {
                        "cnt": 10,
                        "disc": 0,
                        "code": 954,
                        "name": "Тюльпан Білий",
                        "price": 75,
                        "taxgrp": 1
                    }
                ],
                "comment_down": "Коментар до чеку"
            }
        },
        "userinfo": {
            "email": "[email protected]"
        }
    },
    "order_number": "123-LK",
    "notation": "Доставка квітів м. Київ, вул. Хрещатик 99"
}'

2.2. Редагування та видалення

• Редагування: PATCH https://kasa.vchasno.ua/api/v1/orders/<UUID_замовлення>
• Видалення: DELETE https://kasa.vchasno.ua/api/v1/orders/<UUID_замовлення>

Опис полів:
data (object) — Обов’язкове. Об’єкт з даними чека. Детальний опис полів data (Postman).

⚠️ Важливі обмеження:
Заборона порожніх значень: неможливо передати “ttn”: null та/або “data”: null.

Приклад Редагування:

curl --location --request PATCH 'https://kasa.vchasno.ua/api/v1/orders/<ID_замовлення>' \
--header 'Content-Type: application/json' \
--header 'Authorization: <токен_доступу>' \
--data-raw '{
    
    "data": {
        "tag": "123456",
        "fiscal": {
            "task": 1,
            "receipt": {
                "sum": 1926.5,
                "pays": [
                    {
                        "sum": 1926.5,
                        "type": 15
                    }
                ],
                "rows": [
                    {
                        "cnt": 1,
                        "disc": 0,
                        "name": "Подарунковий набір “Квітучий настрій” до 8 березня з ароматними дрібничками, солодощами та весняною атмосферою",
                        "price": 497,
                        "taxgrp": 1
                    },
                    {
                        "cnt": 11,
                        "disc": 420.5,
                        "name": "Тюльпан Рожевий",
                        "price": 100,
                        "taxgrp": 1,
                        "disc_type": 0,
                        "code_a": "XX11111111113"
                    },
                    {
                        "cnt": 10,
                        "disc": 0,
                        "code": 954,
                        "name": "Тюльпан Білий",
                        "price": 75,
                        "code_a": "XX11111111113",
                        "taxgrp": 1
                    }
                ],
                "comment_down": "Коментар до чеку"
            }
        },
        "userinfo": {
            "email": "[email protected]"
        }
    }

}'

Приклад Видалення:

curl --location --request DELETE 'https://kasa.vchasno.ua/api/v1/orders/<ID_замовлення>' \
--header 'Authorization: <токен_доступу>' \
--data ''

Важливо: Редагування/видалення можливо будь-які замовлення окрім тих які в статусі 11 — Фіскалізовано
Відповідь: Статус 200 OK (пуста відповідь без опису).
Важливо: Редагувати вже фіскалізовані замовлення неможливо

3. ВАРІАНТ 2: АРІ замовлення з поштовими інтеграціями

Використовується, коли чек має бути автоматично створений у момент видачі посилки з післяплатою.

Усі HTTP-запити до API замовлень повинні містити наступні заголовки (Headers):

Authorization: <ваш_токен_доступу>
Content-Type: application/json

3.1. Створення (Пошта)

Метод: POST
URL: https://kasa.vchasno.ua/api/v1/orders
Додаткові обов’язкові поля для поштових замовлень:

• ttn (string) — Обов’язкове, для поштових замовлень номер товарно-транспортної накладної.
• type (string) — Обов’язкове, для поштових замовлень тип служби: nova_poshta, ukr_poshta, meest.
• rro_fn (string) — Обов’язкове. Фіскальний номер каси.
• order_number (string) — Номер замовлення у вашій системі. Від 1 до 128 будь-яких символів. Значення може використовувати для пошуку за номером замовлення у вебкабінеті Вчасно.Каса
• notation (string) — Примітка. Дозволено від 1 до 512 будь-яких символів. Значення використовується для пошуку за приміткою у вебкабінеті Вчасно.Каса.
• data (object) — Обов’язкове. Об’єкт з даними чека. Детальний опис полів data (Postman)

Для успішної реєстрації та фіскалізації замовлень з ТТН мають бути дотримані наступні умови:

1. Терміни: ТТН не повинна бути старшою за 3 дні на момент створення замовлення.
2. Статуси: Статус ТТН не має бути «Виконана» або «Видалена».
3. Оплата: Обов’язкова наявність послуги «Контроль оплати» (післяплата/накладений платіж).
4. Особливості Нової Пошти: * Номер ТТН не повинен починатися на 59**.
   -ТТН не має бути створена безпосередньо у відділенні.
   -ТТН не повинна бути переадресованою.
   -ТТН не повинна бути редагованою
5. Типи оплати в об’єкті data.fiscal.receipt.pays:
   -Для Нової Пошти: передаємо type: 20.
   -Для Укрпошти та Meest: передаємо type: 15.

Приклад Створення замовлення з поштовою інтеграцією:

curl --location 'https://kasa.vchasno.ua/api/v1/orders' \
--header 'Content-Type: application/json' \
--header 'Authorization: <токен_доступу>' \
--data-raw '{
    "rro_fn": "4000112233",
    "data": {
        "tag": "123456",
        "fiscal": {
            "task": 1,
            "receipt": {
                "sum": 1926.5,
                "pays": [
                    {
                        "sum": 1926.5,
                        "type": 20
                    }
                ],
                "rows": [
                    {
                        "cnt": 1,
                        "disc": 0,
                        "name": "Подарунковий набір “Квітучий настрій” до 8 березня з ароматними дрібничками, солодощами та весняною атмосферою",
                        "price": 497,
                        "taxgrp": 1
                    },
                    {
                        "cnt": 11,
                        "disc": 420.5,
                        "name": "Тюльпан Рожевий",
                        "price": 100,
                        "taxgrp": 1,
                        "disc_type": 0
                    },
                    {
                        "cnt": 10,
                        "disc": 0,
                        "code": 954,
                        "name": "Тюльпан Білий",
                        "price": 75,
                        "taxgrp": 1
                    }
                ],
                "comment_down": "Коментар до чеку"
            }
        },
        "userinfo": {
            "email": "[email protected]",
            "phone": "+380XXXXXXXXX"
        }
    },
    "order_number": "123-LK",
    "notation": "Доставка квітів м. Київ, вул. Хрещатик 99",
    "ttn": "12345678", 
    "type": "post_type"
}'

3.2. Редагування та видалення замовлень

Ці методи дозволяють вносити зміни у вже створені замовлення до моменту фіскалізації. Видаляти замовлення з будь-яким статусом.

1. Редагування замовлення
Використовуйте цей метод для оновлення даних замовлення або номера ТТН.

PATCH
URLhttps://kasa.vchasno.ua/api/v1/orders/<UUID_замовлення>

⚠️ Важливі обмеження:

• Заборона порожніх значень: неможливо передати "ttn": null та/або "data": null.
• Валідація служби: нове значення ttn повинно належати тій самій поштовій службі, з якою замовлення було створене спочатку (наприклад, не можна змінити ТТН Нової Пошти на ТТН Укрпошти в межах одного замовлення).

Приклад Редагування замовлення з поштовою інтеграцією:

curl --location --request PATCH 'https://kasa.vchasno.ua/api/v1/orders/<ID_замовлення>' \
--header 'Content-Type: application/json' \
--header 'Authorization: <токен_доступу>' \
--data-raw '{
    "ttn": "12345678",
    "data": {
        "tag": "123456",
        "fiscal": {
            "task": 1,
            "receipt": {
                "sum": 1926.5,
                "pays": [
                    {
                        "sum": 1926.5,
                        "type": 15
                    }
                ],
                "rows": [
                    {
                        "cnt": 1,
                        "disc": 0,
                        "name": "Подарунковий набір “Квітучий настрій” до 8 березня з ароматними дрібничками, солодощами та весняною атмосферою",
                        "price": 497,
                        "taxgrp": 1
                    },
                    {
                        "cnt": 11,
                        "disc": 420.5,
                        "name": "Тюльпан Рожевий",
                        "price": 100,
                        "taxgrp": 1,
                        "disc_type": 0
                    },
                    {
                        "cnt": 10,
                        "disc": 0,
                        "code": 954,
                        "name": "Тюльпан Білий",
                        "price": 75,
                        "taxgrp": 1
                    }
                ],
                "comment_down": "Коментар до чеку"
            }
        },
        "userinfo": {
            "email": "[email protected]"
        }
    }

}'

Приклад Видалення замовлення з поштовою інтеграцією:

curl --location --request DELETE 'https://kasa.vchasno.ua/api/v1/orders/<ID_замовлення>' \
--header 'Authorization: <токен_доступу>' \
--data ''

4. Моніторинг та отримання статусів замовлень

Метод дозволяє перевірити статус фіскалізації та отримати дані замовлень.

Метод: POST
URL: https://kasa.vchasno.ua/api/v1/orders/list

Тіло запиту (JSON):

{
  "statuses": [11, 0, 10], 
  "cursor": "2026-03-01T00:00:00",
  "page_size": 50
}

• У фільтр по статусам, потрібно передати код статуса
• Cursor – це спеціальний маркер, який повертається разом із результатом запиту та показує, з якого місця потрібно продовжити отримання наступної порції даних
• Пагінація виведення кількості entity у відповіді. Мінімальне значення 1, максимальне 200

Відповідь та опис полів відповіді:

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

{
   "page_size": 50,
   "has_prev": false,
   "has_next": false,
   "items": [
              {
            "id": "101f3678-027f-ec5c-2b44-db763e465196",
            "type": "api_order",
            "rro_fn": "99975855555555",
            "status": 11,
            "error_desc": null,
            "check_sum": 49950,
            "order_number": "номер заомвлення кирилицею",
            "notation": "1234567890",
            "ttn": null,
            "date_created": "2026-03-04T13:39:46.522264+02:00",
            "check_fn": "TEST_7YwMjtGxkTMgdQ"
        }
    ],
    "cursor_prev": "2026-03-11T23:59:59+02:00",
    "cursor_next": "2026-03-04T11:39:46.522264+00:00"
}

Опис полів:

• id (string) — ID замовлення (UUID).
• type (string) — Тип: api_order, ukr_poshta, nova_poshta, meest.
• rro_fn (string) — Фіскальний номер каси.
• status (integer) — Код статусу замовлення (див. таблицю статусів).
• error_desc (string) — Заповнюється лише при помилці фіскалізації поштових замовлень.
• check_sum (integer) — Сума чека (в копійках).
• order_number (string) — Номер замовлення з вашої системи.
• notation (string) — Примітка для пошуку в кабінеті.
• ttn (string) — Номер накладної (для поштових типів).
• date_created (string) — Дата та час створення замовлення.
• check_fn (string) — Фіскальний номер чека. Заповнюється лише при status -11

Довідник статусів (status):

• 0 — Created: Замовлення прийнято системою.
• 10 — Delivered: Замовлення прибуло до пункту видачі/клієнта.
• 11 — Фіскалізовано: Чек успішно зареєстровано в ДПС.
• 101 — Refusal: Клієнт відмовився від отримання.
• 2000, 2001, 2002 — Помилка: Проблема при спробі фіскалізації (опис див. у error_desc).

Приклад:

curl --location 'https://kasa.vchasno.ua/api/v1/orders/list' \
--header 'Content-Type: application/json' \
--header 'Authorization: <токен_доступу>' \
--data '{
    "statuses": [11,0],
    "cursor": "2026-01-01T23:59:59",
    "page_size": 200
}'