Grabo Partners API » API Nodes » vouchers
Vouchers
Информация за издадените ваучери по Вашите оферти в Grabo.bg.
Функции:
vouchers/check_by_code: Проверка за валидност на ваучер по въведен номер и секретен код.
vouchers/check_by_barcode: Проверка за валидност на ваучер по сканиран баркод.
vouchers/check_by_qrcode: Проверка за валидност на ваучер по сканиран QR код.
vouchers/chronology: Връща хронология на всички издадени и анулирани ваучери.
vouchers/list: Връща списък с ваучери за конкретна оферта.
» Функция vouchers/check_by_code
Проверка за валидност на ваучер по подаден номер и секретен код. Функционалността е аналогична на уеб-базираната система за проверка на ваучери - https://grabo.bg/check:
Първо, даден ваучер, предоставен от потребител-купувач, се проверява за валидност в системата;
Ако ваучерът е валиден и потребителят е обслужен, ваучерът се маркира като използван.
Request URL:
https://grabo.bg/api/partners/vouchers/check_by_code/?api_key={api_key}&company_id={company_id}&code={code}&secret={secret}
Параметри към заявката (освен задължителните api_key и company_id):
| code | задължителен | Номер на ваучера, предоставен от потребителя. |
| secret | задължителен | Секретен код на ваучера. |
| mark_as_used | незадължителен | Ако подадете този параметър със стойност true или 1, тогава конкретният ваучер ще бъде маркиран в системата на Grabo.bg като използван. Ако не го подадете, тогава единствено ще бъде изпълнена проверка за валидност. |
Flow: За да проверите ваучер дали е валиден и впоследствие да го маркирате като използван, следва да го направите чрез две отделни API заявки към тази функция: една заявка за проверка и втора заявка за маркиране.
Примерен отговор при проверка за валидност, ако ваучерът е валиден:
{
"success": true,
"error": false,
"result": {
"warnings": [],
"voucher": {
"code": 12345678,
"secret": 87654321,
"status": "NOT_USED",
"used_date": "",
"title": "Две пици Капричоза (доматен сос, шунка, гъби, пипер, моцарела), 500гр",
"user_name": "Иван Иванов",
"date_valid": "2026-06-05",
"price_regular": 20,
"price_promo": 9.9,
"amount_prepaid": 9.9,
"amount_to_surcharge": 0,
"currency": "BGN",
"deal_extras": ["Всеки клиент с ваучер получава бонус голяма бира."],
"deal_rules": ["С предварителна резервация на тел. 0892 410 012."],
"deal_id": "0ntv5m",
"deal_url": "https://grabo.bg/...url-of-the-deal...",
"company_name": "Пицария \"При нас е вкусно\"",
}
}
}
Примерен отговор при проверка за валидност, ако ваучерът НЕ е валиден:
{
"success": false,
"error": {
"code": 1000,
"message": "Не съществува ваучер с този номер. Моля, опитайте отново."
},
"result": false
}
Възможни грешки:
» Не съществува ваучер с този номер. Моля, опитайте отново.
» Въведеният секретен код е невалиден. Моля, опитайте отново.
» Този ваучер се отнася за друга фирма, не Вашата.
» и други подобни.
» Не съществува ваучер с този номер. Моля, опитайте отново.
» Въведеният секретен код е невалиден. Моля, опитайте отново.
» Този ваучер се отнася за друга фирма, не Вашата.
» и други подобни.
Структура на отговора при проверка за валидност, ако ваучерът е валиден:
| Параметър | Тип | Стойност |
|---|---|---|
| warnings | array |
Важно: Представлява масив с евентуални предупреждения (strings), които обслужващият персонал следва да вземе предвид при обслужване на клиента. Например: » Този ваучер е маркиран, че вече е бил използван (на 24.05.2026г, 22:28ч)! » Валидността на закупената от клиента оферта е била обявена до 25.05.2026г. » и други подобни. |
| voucher | object | Информацията за ваучера (описана по-долу). |
Структура на информацията за ваучера:
| Параметър | Тип | Стойност |
|---|---|---|
| code | integer | Номер на ваучера - число с дължина от 6 до 9 цифри. |
| secret | integer | Секретен код на ваучера - число с дължина от 6 до 9 цифри. |
| status | string | Стойността е NOT_USED (ако ваучерът не е бил използван) или ALREADY_USED (ако ваучерът вече е бил използван). Важно: Клиентът следва да бъде обслужен само ако ваучерът не е бил вече използван. |
| used_date | date | Ако ваучерът вече е бил използван, тук е датата на маркирането му като използван (формат: YY-MM-DD hh:mm:ss). |
| title | string | Заглавие на закупената услуга или стока. |
| user_name | string | Име на потребителя-купувач. |
| date_valid | date | Крайна дата на валидност на ваучера (формат: YY-MM-DD). |
| price_regular | float | Регулярна цена (цена без отстъпка) на оферираната услуга/стока. |
| price_promo | float | Продажна цена на оферираната услуга/стока. |
| amount_prepaid | float | Размер на сумата, предплатена от потребителя-купувач към Grabo.bg. |
| amount_to_surcharge | float | Сума, която потребителят-купувач следва да заплати на търговеца извън вече предплатената сума. В повечето случаи стойността на този параметър е 0. |
| currency | string | BGN |
| deal_extras | array | Масив, съдържащ Бонусите към офертата (strings), ако има такива. |
| deal_rules | array | Масив, съдържащ Условията на офертата (strings), ако има такива. |
| deal_id | string | Идентификатор на закупената оферта. |
| deal_url | string | URL адрес към офертата в потребителската част на Grabo.bg. |
| company_name | string | Брандът, от чието име е публикувана офертата. |
Примерен отговор при маркиране на валиден ваучер като използван:
{
"success": true,
"error": false,
"result": true
}
» Функция vouchers/check_by_barcode
Проверка за валидност на ваучер по сканиран баркод (EAN-13).
Функционалността е идентична с горната (vouchers/check_by_code), с единствената разлика, че вместо двата параметъра code и secret се подава само един параметър - barcode.
Параметри към заявката (освен задължителните api_key и company_id):
| barcode | задължителен | Съдържание на сканирания баркод (на ваучера, предоставен от клиента). Форматът на баркода е EAN-13. |
| mark_as_used | незадължителен | Ако подадете този параметър със стойност true или 1, тогава конкретният ваучер ще бъде маркиран в системата на Grabo.bg като използван. Ако не го подадете, тогава единствено ще бъде изпълнена проверка за валидност. |
» Функция vouchers/check_by_qrcode
Проверка за валидност на ваучер по сканиран QR код.
Функционалността е сходна на горната (vouchers/check_by_code), със следната разлика: Даден QR код може в себе си да съдържа информация за множество ваучери на клиента едновременно, а не само за един ваучер. Това е приложимо когато клиент разполага с няколко ваучера по конкретанта оферта.
Параметри към заявката (освен задължителните api_key и company_id):
| qrcode | задължителен | Съдържание на сканирания QR код (на ваучера, предоставен от клиента). |
Структура на информацията за ваучерите:
При валидно сканиране, резултатът за ваучерите представлява масив. Този масив може да съдържа един или повече ваучери. Всеки елемент на масива е със структура, идентична на описаната по-горе (vouchers/check_by_code).
{
"success": true,
"error": false,
"result": {
"vouchers": [
{...първи ваучер...}
{...втори ваучер...}
{...трети ваучер...}
]
}
}
Маркиране на ваучер като използван:
Маркирането се извършва по описания по-горе начин (vouchers/check_by_code). Особеността е, че се прави ваучер по ваучер. Ако желаете да маркирате като използвани всички ваучери, предоставени чрез съответния QR код, следва за всеки от тях да изпълните отделна API заявка, използвайки mark_as_used.
» Функция vouchers/chronology
Връща хронология на всички издадени и анулирани ваучери.
Request URL:
https://grabo.bg/api/partners/vouchers/chronology/?api_key={api_key}&company_id={company_id}
Параметри към заявката (освен задължителните api_key и company_id):
| filter_deal_id | незадължителен | Дали да върне резултати само за конкретна оферта (deal_id), или всички. |
| filter_after_timestamp | незадължителен | Дали да върне информация за събития (издадени ваучери или анулирани ваучери), възникнали само след конкретна дата (unix timestamp формат). |
| num_per_page | незадължителен | По колко резултата да върне наведнъж. Трябва да е число между 10 и 500. Ако не се подаде, стойността ще бъде 50. |
| page | незадължителен | Коя "страница" от резултатите да върне (на paging принцип). По подразбиране е 1. |
Примерен отговор:
{
"success": true,
"error": false,
"result": {
"filter_deal_id": null,
"filter_after_timestamp": null,
"items_count": 120,
"num_per_page": 50,
"num_pages": 3,
"page": 1,
"items": [
// ...
]
}
}
Структура на result от отговора:
| Параметър | Тип | Стойност |
|---|---|---|
| filter_deal_id | null or string | Дали резултатите са филтрирани поради подаден параметър filter_deal_id към заявката. |
| filter_after_timestamp | null or integer | Дали резултатите са филтрирани поради подаден параметър filter_after_timestamp към заявката. |
| items_count | integer | Брой намерени оферти, отговарящи на зададените критерии. |
| num_per_page | integer | По колко резултата връща наведнъж, съобразно параметъра num_per_page. |
| num_pages | integer | Брой страници с резултати. |
| page | integer | Текуща страница, за която са върнати резултатите в items. |
| items | array | Масив с резултатите (описан по-долу), отговарящи на зададените критерии, за съответната страница page. |
Структура на всяко конкретно събитие от items:
| Параметър | Тип | Стойност |
|---|---|---|
| action | string | Тип на събитието - new за нов издаден ваучер, refunded за анулиран ваучер. |
| action_timestamp | integer | Дата на събитието в unix timestamp. При нов издаден ваучер: дата на издаването му; При анулиран ваучер: дата на анулирането. |
| code | integer | Номер на ваучера - число с дължина от 6 до 9 цифри. |
| user_name | string | Име на потребителя-купувач. |
| deal_id | string | Идентификатор на закупената оферта. |
| title | string | Заглавие на закупената услуга или стока. |
| amount_prepaid | float | Размер на сумата, предплатена от потребителя-купувач към Grabo.bg. |
| amount_prepaid_method | string | Описане на начина на плащане (например: Онлайн плащане с карта, Плащане по банков път, Плащане в брой на каса на Изипей....). |
| amount_to_surcharge | float | Сума, която потребителят-купувач следва да заплати на търговеца извън вече предплатената сума. В повечето случаи стойността на този параметър е 0. |
| currency | string | BGN |
| company_name | string | Брандът, от чието име е била публикувана закупената оферта. |
» Функция vouchers/list
Връща актуален списък с ваучери за конкретна оферта.
Request URL:
https://grabo.bg/api/partners/vouchers/list/?api_key={api_key}&company_id={company_id}&deal_id={deal_id}
Параметри към заявката (освен задължителните api_key и company_id):
| deal_id | задължителен | Идентификаторът deal_id на конкретната оферта, за която желаете да получите информацията. |
| include_refunded | незадължителен | Дали да се включат и анулираните ваучери. Ако стойността е true или 1, резултатите ще включват активни и анулирани ваучери. В противен случай ще бъдат върнати само активните (неанулирани) ваучери. |
| only_refunded | незадължителен | Дали да бъдат върнати само анулираните ваучери. Ако стойността е true или 1, резултатите ще съдържат само анулирани ваучери, без активни. |
Примерен отговор:
{
"success": true,
"error": false,
"result": {
"deal_id": "0ntv5m",
"include_refunded": true,
"only_refunded": null,
"items": [
// ...
]
}
}
Структура на result от отговора:
| Параметър | Тип | Стойност |
|---|---|---|
| deal_id | string | Идентификаторът на офертата. |
| include_refunded | null or true | Дали резултатите са филтрирани поради подаден параметър include_refunded към заявката. |
| only_refunded | null or true | Дали резултатите са филтрирани поради подаден параметър only_refunded към заявката. |
| items | array | Масив с резултатите (описан по-долу), отговарящи на зададените критерии. |
Структура на всеки конкретен ваучер items:
| Параметър | Тип | Стойност |
|---|---|---|
| code | integer | Номер на ваучера - число с дължина от 6 до 9 цифри. |
| status | string | Стойността е NOT_USED (ако ваучерът не е бил използван) или ALREADY_USED (ако ваучерът вече е бил използван). |
| used_date | date | Ако ваучерът вече е бил използван, тук е датата на маркирането му като използван (формат: YY-MM-DD hh:mm:ss). |
| title | string | Заглавие на закупената услуга или стока. |
| user_name | string | Име на потребителя-купувач. |
| date_valid | date | Крайна дата на валидност на ваучера (формат: YY-MM-DD). |
| price_regular | float | Регулярна цена (цена без отстъпка) на оферираната услуга/стока. |
| price_promo | float | Продажна цена на оферираната услуга/стока. |
| amount_prepaid | float | Размер на сумата, предплатена от потребителя-купувач към Grabo.bg. |
| amount_to_surcharge | float | Сума, която потребителят-купувач следва да заплати на търговеца извън вече предплатената сума. В повечето случаи стойността на този параметър е 0. |
| currency | string | BGN |
| deal_id | string | Идентификаторът на офертата. |
| company_name | string | Брандът, от чието име е публикувана офертата. |
| is_refunded | boolean | Параметърът указва дали конкретният ваучер е бил анулиран. Присъства само ако при заявката са ползвани филтрите include_refunded или only_refunded. |
| delivery_details | object | Параметърът присъства само ако конкретната оферта е за стока и използва системата за Управление на доставки в Партньорския панел на Grabo.bg. Представлява обект с три параметъра - city, address и notes (strings), съдържащи посочените от потребителя-купувач детайли за доставка. |