: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): коди типів операцій, типи платіжних методів, коди статусів обробки операцій, відомості та помилки, що повертаються у відповіді та ін.

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

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

Телефон: [phone]
Email: [e-mail]
Telegram: @xpaysupportbot
</details>