---
# System prepended metadata

title: '[20801] Отримання даних довідника (v.2)'

---

![](https://i.imgur.com/ULmPUgP.jpg)
:arrow_left: [На Головну](/Mj2ZqCVpSq6A6Jzm6ladlw)


# [20801] Отримання даних довідника (v.2)

:::info
Застосування версії запитів "Оплата комунальних послуг (v.1)" чи "Оплата комунальних послуг (v.2)" визначається на етапі інтеграції.
:::

## Застосування

Для отримання даних довідника необхідно послідовно надіслати три запити: **"Довідник постачальників"**, **"Довідник послуг та метаданих"** та **"Довідник по сервісу"**.

:::info
[TOC]
:::


## [20801] Довідник постачальників

*Опис атрибутів "Partner", "KeyAES" та "Sign" див. у розділі ["Загальна інформація по підключенню (API)"](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA).*


### Структура "Data"

Структура "Data" для даної операції формується з наступних параметрів:

:::info
<details>
<summary>Формування структури "Data" (приклади наведені нижче)</summary>
<br>

~~~
{
    "dictionary": "",
    "Transaction": {
        "TransactionID": "",
        "TerminalID": "",
        "DateTime": ""
    }
}
~~~
</details>
:::


|Параметр|Обов'яз-ковість|Тип|Опис|Приклад|
|:----:|:----:|:----:|----|:----:|
| `dictionary` | Так | Рядок | Передається значення, дані якого необхідно отримати з довідника: `provider` - список доступних провайдерів (постачальників), що надають послуги.|`provider`|
|`Transaction`|Так|Структура|Структура, що передає дані про транзакцію. Див. розділ ["Структура "Transaction"](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA#2-Data).|Див. нижче.|

:::success
<details>
<summary>Приклад запиту [20801] "Довідник постачальників"</summary>
<br>

~~~md
{
  "Partner": {
    "PartnerToken": "72a8ddb8-9145-4a41-af1a-8c48ecaa4be1",
    "OperationType": 20801
  },
  "Data": "{\"dictionary\": \"provider\", \"Transaction\": {\"TransactionID\": \"0c5328f5-bda9-4376-b6a0-ca544fcb72fc\", \"TerminalID\": \"1\", \"DateTime\": \"20230221120111\"}}",
  "KeyAES": "",
  "Sign": ""
}
~~~
</details>
:::


## Відповідь на запит [20801] "Довідник постачальників"

*Загальна інформація по формуванню структури відповіді наведена у розділі [“Загальна інформація по підключенню (API)”](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA?both#%D0%A1%D1%82%D1%80%D1%83%D0%BA%D1%82%D1%83%D1%80%D0%B0-%D0%B2%D1%96%D0%B4%D0%BF%D0%BE%D0%B2%D1%96%D0%B4%D1%96).*

### Структура "Data"

Структура "Data" відповіді формується з наступних параметрів:

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `list`^1^ | Так | Масив | Масив структур, що передає дані по всім елементам запитаного параметра. |Див. приклад нижче.|


^1^ Параметри масиву **"list"**:

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `MID` |Так| Рядок | Ідентифікатор провайдера (Merchant ID). |`EP`|
| `name` | Так | Рядок | Назва провайдера. |`EasyPay`|



### Приклади відповідей

:::success
<details>
<summary>Операція проведена успішно</summary>
<br>

~~~md
{
  "Code": 200,
  "Message": "Done",
  "Data": {
    "OperationDate": "2023-02-21T15:54:42.129914+02:00",
    "OperationID": 9488897,
    "OperationStatus": 10,
    "list": [
      {
        "MID": "EP",
        "name": "EasyPay"
      },
      {
        "MID": "GRC",
        "name": "ГЕРЦ"
      }
    ]
  },
  "KeyAES": "",
  "Sign": ""
}
~~~
</details>
:::



---


## [20801] Довідник послуг та метаданих

*Опис атрибутів "Partner", "KeyAES" та "Sign" див. у розділі ["Загальна інформація по підключенню (API)"](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA).*


### Структура "Data"

Структура "Data" для даної операції формується з наступних параметрів:

:::info
<details>
<summary>Формування структури "Data" (приклади наведені нижче)</summary>
<br>

~~~
{
    "MID": "",
    "dictionary": "",
    "filter": 
      {
        "context": "",
        "location": "",
        "categoryKey": ""
      },
    "Transaction": {
        "TransactionID": "",
        "TerminalID": "",
        "DateTime": ""
    }
}
~~~
</details>
:::


|Параметр|Обов'яз-ковість|Тип|Опис|Приклад|
|:----:|:----:|:----:|----|:----:|
| `MID` |Ні| Рядок | Ідентифікатор провайдера (Merchant ID), значення отримане у відповіді на попередній запит. |`EP`|
| `dictionary` | Так | Рядок | Передається значення, дані якого необхідно отримати з довідника: `service` - список доступних сервісів за вказаним провайдером. |`service`|
|`filter`^2^|Ні|Структура|Структура, що передає додаткові параметри пошуку послуг (фільтр). При відсутності значення - передаються дані за всіма провайдерами. |Див. нижче.|
|`Transaction`|Так|Структура|Структура, що передає дані про транзакцію. Див. розділ ["Структура "Transaction"](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA#2-Data).|Див. нижче.|


^2^ Параметри структури **"filter"**:

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `context` |Так| Рядок | Строка пошуку послуг за контекстом (допускається фрагмент). Пошук може здійснюватись за наступними параметрами послуги: </br> "Name" – назва категорії, підкатегорії, послуги; </br> "Description" – опис; </br> "Location" – список міст та/або регіонів, де надається дана послуга; </br> "Cities" – міста, в яких надається послуга; </br> "City" – місто, в якому надається послуга; </br> "Regions" – регіони, в яких надається послуга; </br> "Region" – регіон, в якому надається послуга. |`Борщагівка`|
| `location` | Так | Рядок | Строка пошуку послуг за регіоном/населеним пунктом (допускається фрагмент). |`Київ`|
| `categoryKey` | Так | Рядок | Строка пошуку за категорією. Допустимі значення пошуку (повна відповідність): `bank`, `category-other`, `communal`, `distribution` `entertainment`, `games`, `Internet-tv`, `mobile`, `submenu-insurance`, `submenu-pawnshopes`, `taxi`. |`Internet-tv`|


:::success
<details>
<summary>Приклад запиту [20801] "Довідник послуг та метаданих"</summary>
<br>

~~~md
{
  "Partner": {
    "PartnerToken": "72a8ddb8-9145-4a41-af1a-8c48ecaa4be1",
    "OperationType": 20801
  },
  "Data": "{\"MID\": \"EP\", \"dictionary\": \"service\", \"filter\": {\"context\": \"Борщагівка\", \"location\": \"Київ\", \"categoryKey\": \"internet\"}, \"Transaction\": {\"TransactionID\": \"0c5328f5-bda9-4376-b6a0-ca544fcb72fc\", \"TerminalID\": \"1\", \"DateTime\": \"20230221120111\"}}",
  "KeyAES": "",
  "Sign": ""
}
~~~
</details>
:::


## Відповідь на запит [20801] "Довідник послуг та метаданих"

*Загальна інформація по формуванню структури відповіді наведена у розділі [“Загальна інформація по підключенню (API)”](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA?both#%D0%A1%D1%82%D1%80%D1%83%D0%BA%D1%82%D1%83%D1%80%D0%B0-%D0%B2%D1%96%D0%B4%D0%BF%D0%BE%D0%B2%D1%96%D0%B4%D1%96).*

### Структура "Data"

Структура "Data" відповіді формується з наступних параметрів:

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `Services`^3^ | Так | Масив | Масив структур, що передає дані по всім елементам запитаного параметра. |Див. приклад нижче.|


^3^ Параметри масиву **"Services"**:

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `AmountMax` |Так| Ціле | Максимальна сума до оплати по сервісу (у копійках). |`2999999`|
| `AmountMin` |Так| Ціле | Мінімальна сума до оплати по сервісу (у копійках). |`1`|
| `CategoryKey` |Так| Рядок | Категорія сервісу. |`communal`|
| `Icon` |Так| Рядок | Іконка сервісу. |`https://cdn.easypay.ua/ logo/logo-kyivgazenergy.png`|
| `Location`^4^ |Так| Структура | Структура, що передає список міст та/або регіонів, де надається дана послуга. |Див. нижче.|
| `MID` |Так| Рядок | Ідентифікатор провайдера (Merchant ID).  |`EasyPay`|
| `groups`^5^ |Так| Масив | Масив, що передає назву групи та список полів для оплати боргу. |Див. нижче.|
| `id` |Так| Рядок | Ідентифікатор сервісу. |`2115`|
| `name` | Так | Рядок | Назва сервісу. |`Сплата за комунальні послуги КиївГазЕнерджи`|


^4^ Параметри структури **"Location"**:

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `Cities` |Так| Структура | Структура, що передає список міст, де надається дана послуга. |`{"City": "Вінниця"}`|
| `Regions` |Так| Структура | Структура, що передає список  регіонів, де надається дана послуга. |`{"Name": "Київська обл.", "RegionID": "9"}`|


^5^ Параметри масиву **"groups"**:

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `fields`^6^ |Так| Масив | Масив, що передає список полів для оплати боргу. |Див. нижче.|
| `group` | Так | Рядок | Тип групи. |`account`|
| `groupname` | Так | Рядок | Назва групи. |`КиївГазЕнерджи (оплата боргу)`|


^6^ Параметри масиву **"fields"**:

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `autocomplete` | Так | Рядок | Назва довідника для автоматичного заповнення поля. |`dic_name`|
| `name` | Так | Рядок | Назва поля. |`Account`|
| `hint` | Так | Рядок | Підказка до поля. |`Введiть номер рахунку, на який будуть зарахованi кошти`|
| `caption` | Так | Рядок | Напис зверху поля. |`Номер рахунку`|
| `mask` | Так | Рядок | Маска поля, приклад: 2620$$$$$$$$$$, де $ - змінна, що вводиться. |`mask`|
| `max` | Так | Рядок | Максимальна кількість символів поля. |`10`|
| `min` | Так | Рядок | Мінімальна кількість символів поля. |`4`|
| `regexp` | Так | Рядок | Регулярний вираз поля. |`regexp`|
| `order` | Так | Ціле | Порядковий номер поля при виведенні на екран. |`1`|



### Приклади відповідей

:::success
<details>
<summary>Операція проведена успішно</summary>
<br>

~~~md
{
  "Code": 200,
  "Message": "OK",
  "Data": {
    "OperationDate": "2023-12-19T15:36:32.535916+02:00",
    "OperationID": 9591664,
    "OperationStatus": 10,
    "Services": [
      {
        "AmountMax": 2999999,
        "AmountMin": 1,
        "CategoryKey": "communal",
        "Icon": "https://cdn.easypay.ua/logo/logo-kyivgazenergy.png",
        "Location": {
          "Cities": {
            "City": null
          },
          "Regions": {
            "Region": [
              {
                "Name": "Київська обл.",
                "RegionID": "9"
              },
              {
                "Name": "м. Київ",
                "RegionID": "26"
              },
              {
                "Name": "TEST",
                "RegionID": "50"
              }
            ]
          }
        },
        "MID": "EasyPay",
        "groups": [
          {
            "fields": [
              {
                "autocomplete": "",
                "caption": "Номер рахунку",
                "hint": "Введiть номер рахунку, на який будуть зарахованi кошти",
                "mask": "",
                "max": "10",
                "min": "4",
                "name": "Account",
                "order": "0",
                "regex": ""
              }
            ],
            "group": "account",
            "groupname": "КиївГазЕнерджи (оплата боргу)"
          }
        ],
        "id": "2115",
        "name": "Сплата за комунальні послуги КиївГазЕнерджи"
      },
      {
        "AmountMax": 2999999,
        "AmountMin": 1,
        "CategoryKey": "communal",
        "Icon": "",
        "Location": {
          "Cities": {
            "City": null
          },
          "Regions": {
            "Region": [
              {
                "Name": "Київська обл.",
                "RegionID": "9"
              },
              {
                "Name": "м. Київ",
                "RegionID": "26"
              },
              {
                "Name": "TEST",
                "RegionID": "50"
              }
            ]
          }
        },
        "MID": "EasyPay",
        "groups": [
          {
            "fields": [
              {
                "autocomplete": "",
                "caption": "Номер особового рахунку",
                "hint": "Введіть номер особового рахунку",
                "mask": "",
                "max": "10",
                "min": "10",
                "name": "Account",
                "order": "0",
                "regex": ""
              }
            ],
            "group": "account",
            "groupname": "Оплата газу в Київській області (Тест)"
          }
        ],
        "id": "14844",
        "name": "Оплата газу в Київській області"
      },
      {
        "AmountMax": 2999999,
        "AmountMin": 1,
        "CategoryKey": "communal",
        "Icon": "",
        "Location": {
          "Cities": {
            "City": null
          },
          "Regions": {
            "Region": [
              {
                "Name": "Київська обл.",
                "RegionID": "9"
              },
              {
                "Name": "м. Київ",
                "RegionID": "26"
              },
              {
                "Name": "TEST",
                "RegionID": "50"
              }
            ]
          }
        },
        "MID": "EasyPay",
        "groups": [
          {
            "fields": [
              {
                "autocomplete": "",
                "caption": "Номер особового рахунку",
                "hint": "Введіть номер особового рахунку",
                "mask": "",
                "max": "10",
                "min": "10",
                "name": "Account",
                "order": "0",
                "regex": ""
              }
            ],
            "group": "account",
            "groupname": "КиївОблГаз Збут (ОПЛАТА БОРГУ ДО 01.05)"
          }
        ],
        "id": "4462",
        "name": "КиївОблГаз Збут (ОПЛАТА БОРГУ ДО 01.05)"
      },
      {
        "AmountMax": 100,
        "AmountMin": 100,
        "CategoryKey": "communal",
        "Icon": "https://cdn.easypay.ua/logo/logo-yasno.png",
        "Location": {
          "Cities": {
            "City": null
          },
          "Regions": {
            "Region": [
              {
                "Name": "Київська обл.",
                "RegionID": "9"
              },
              {
                "Name": "м. Київ",
                "RegionID": "26"
              },
              {
                "Name": "TEST",
                "RegionID": "50"
              }
            ]
          }
        },
        "MID": "EasyPay",
        "groups": [
          {
            "fields": [
              {
                "autocomplete": "",
                "caption": "Оберіть номер квартири",
                "hint": "Оберіть номер квартири",
                "mask": "",
                "max": "10",
                "min": "1",
                "name": "Apartment",
                "order": "3",
                "regex": ""
              },
              {
                "autocomplete": "",
                "caption": "Оберіть номер будинку",
                "hint": "Оберіть номер будинку",
                "mask": "",
                "max": "5",
                "min": "1",
                "name": "House",
                "order": "2",
                "regex": ""
              },
              {
                "autocomplete": "",
                "caption": "ПІБ",
                "hint": "Введіть прізвище, ім’я, по батькові",
                "mask": "",
                "max": "60",
                "min": "5",
                "name": "Name",
                "order": "4",
                "regex": ""
              },
              {
                "autocomplete": "",
                "caption": "Оберіть вулицю",
                "hint": "Оберіть вулицю",
                "mask": "",
                "max": "20",
                "min": "1",
                "name": "Street",
                "order": "1",
                "regex": ""
              }
            ],
            "group": "address",
            "groupname": "КЕП: передача показників лічильника"
          }
        ],
        "id": "14156",
        "name": "Київські енергетичні послуги: передача показників лічильника"
      },
      {
        "AmountMax": 2999999,
        "AmountMin": 1,
        "CategoryKey": "communal",
        "Icon": "https://cdn.easypay.ua/logo/logo-cat-lviv.png",
        "Location": {
          "Cities": {
            "City": null
          },
          "Regions": {
            "Region": [
              {
                "Name": "Львівська обл.",
                "RegionID": "13"
              },
              {
                "Name": "TEST",
                "RegionID": "50"
              }
            ]
          }
        },
        "MID": "EasyPay",
        "groups": [
          {
            "fields": [
              {
                "autocomplete": "",
                "caption": "Номер особового рахунку",
                "hint": "Сплата за послуги вивозу ТПВ. Введiть номер особового рахунку.",
                "mask": "",
                "max": "10",
                "min": "1",
                "name": "Account",
                "order": "0",
                "regex": ""
              }
            ],
            "group": "account",
            "groupname": "САТ-Львів"
          }
        ],
        "id": "3173",
        "name": "Сплата за послуги вивозу ТПВ \"САТ-Львів\""
      }
    ]
  },
  "KeyAES": "",
  "Sign": ""
}
~~~
</details>
:::

:::success
<details>
<summary>Помилка виконання операції</summary>
<br>

~~~md
{
  "Code": 200,
  "Message": "done",
  "Data": {
    "OperationID": 111,
    "OperationStatus": 21,
    "Reason": 3
  },
  "KeyAES": "",
  "Sign": ""
}
~~~
</details>
:::



---


## [20801] Довідник по сервісу

*Опис атрибутів "Partner", "KeyAES" та "Sign" див. у розділі ["Загальна інформація по підключенню (API)"](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA).*


### Структура "Data"

Структура "Data" для даної операції формується з наступних параметрів:

:::info
<details>
<summary>Формування структури "Data" (приклади наведені нижче)</summary>
<br>

~~~
{
    "MID": "",
    "parentid": ,
    "dictionary": "",
    "Transaction": {
        "TransactionID": "",
        "TerminalID": "",
        "DateTime": ""
    }
}
~~~
</details>
:::


|Параметр|Обов'яз-ковість|Тип|Опис|Приклад|
|:----:|:----:|:----:|----|:----:|
| `MID` |Так| Рядок | Ідентифікатор провайдера (Merchant ID), значення отримане у відповіді на попередній запит. |`EP`|
| `parentid` |Так| Ціле | Ідентифікатор сервісу, значення отримане у відповіді на попередній запит - `id`. |`1`|
| `dictionary` | Так | Рядок | Передається значення, дані якого необхідно отримати з довідника: `city`, `street` або `service`. |`city`|
|`Transaction`|Так|Структура|Структура, що передає дані про транзакцію. Див. розділ ["Структура "Transaction"](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA#2-Data).|Див. нижче.|


:::success
<details>
<summary>Приклад запиту [20801] "Довідник по сервісу"</summary>
<br>

~~~md
{
  "Partner": {
    "PartnerToken": "72a8ddb8-9145-4a41-af1a-8c48ecaa4be1",
    "OperationType": 20801
  },
  "Data": "{\"MID\": \"EP\", \"parentid\": \"1\", \"dictionary\": \"city\", \"Transaction\": {\"TransactionID\": \"0c5328f5-bda9-4376-b6a0-ca544fcb72fc\", \"TerminalID\": \"1\", \"DateTime\": \"20230221120111\"}}",
  "KeyAES": "",
  "Sign": ""
}
~~~
</details>
:::


## Відповідь на запит [20801] "Довідник по сервісу"

*Загальна інформація по формуванню структури відповіді наведена у розділі [“Загальна інформація по підключенню (API)”](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA?both#%D0%A1%D1%82%D1%80%D1%83%D0%BA%D1%82%D1%83%D1%80%D0%B0-%D0%B2%D1%96%D0%B4%D0%BF%D0%BE%D0%B2%D1%96%D0%B4%D1%96).*

### Структура "Data"

Структура "Data" відповіді формується з наступних параметрів:

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `dictionary` | Так | Рядок | Запитаний параметр. |`city`|
| `list`^7^ | Так | Масив | Масив структур, що передає дані по всім елементам запитаного параметра. |Див. приклад нижче.|


^7^ Параметри масиву **"list"**:

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `id` | Так | Рядок | Унікальний ідентифікатор окремого елементу. |`111`|
| `name` | Так | Рядок | Назва окремого елементу. |`Vinnitsa`|
| `giocid` | Так | Ціле | Унікальний ідентифікатор ГІОЦ (укр. головний інформаційно-обчислювальний центр) окремого елементу. |`12312`|
| `accountid` | Так | Рядок | Унікальний ідентифікатор акаунту для подальшого запиту заборгованості.  |`1`|


### Приклади відповідей

:::success
<details>
<summary>Операція проведена успішно</summary>
<br>

~~~md
{
  "Code": 200,
  "Message": "Done",
  "Data": {
    "OperationDate": "2023-02-21T15:54:42.129914+02:00",
    "OperationID": 9488897,
    "OperationStatus": 10,
    "dictionary": "city",
    "list": [
      {
        "id": "111",
        "name": "Vinnitsa",
        "giocid": 12312,
        "accountid": ""
      },
      {
        "id": "112",
        "name": "Uman",
        "giocid": 13415,
        "accountid": ""
      }
    ]
  },
  "KeyAES": "",
  "Sign": ""
}
~~~
</details>
:::

:::success
<details>
<summary>Помилка виконання операції</summary>
<br>

~~~md
{
  "Code": 200,
  "Message": "done",
  "Data": {
    "OperationID": 111,
    "OperationStatus": 21,
    "Reason": 3
  },
  "KeyAES": "",
  "Sign": ""
}
~~~
</details>
:::



## Пов'язані запити

[[20802] Отримання даних заборгованості (v.2)](https://hackmd.io/26l7UwT9TLKlmV9gNconZg)
[[10108] Погашення заборгованості (v.2)](https://hackmd.io/7lBhiykHQ6K4gTJLatww-Q)


## Довідкові матеріали 

Опис загальних параметрів системи XPAY див. у розділі ["Довідкові матеріали"](https://hackmd.io/aBE7H5cfQ-iqaN3SnwaQ-w): коди типів операцій, типи платіжних методів, коди статусів обробки операцій, відомості та помилки, що повертаються у відповіді та ін.


![](https://i.imgur.com/17gAyWb.png)
:arrow_left: [На Головну](/Mj2ZqCVpSq6A6Jzm6ladlw)
:arrow_left: [Загальна інформація по підключенню (API)](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA)

<details>
<summary>Служба підтримки XPAY</summary>
</br>

Телефон: +38 093 891 92 00
Email: info@xpay.com.ua
Telegram: @xpaysupportbot
</details>
