[УКР](https://hackmd.io/Xndoh9TxRPSMk1V1pPhXUQ) | ENG
:arrow_left: [Guide](https://hackmd.io/QA2NYRliRLGviJl5P4-ZCw)

# [20801] Get Directory Data

## Usage

Request [20801] is used to get directory data: names of cities, streets, numbers of houses, apartments, and account IDs for further debt request.

## Request

*See the description of the "Partner", "KeyAES" and "Sign" attributes in the section "[General API Integration Information](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ)".*

### Data Structure

Data structure for this operation is formed from the following parameters:

:::info
<details>
<summary>Data structure formation (examples are below)</summary>
<br>

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

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `dictionary` | Yes |String | A single value is sent, the data of which must be got from the directory. </br> Possible values: </br> `city` - city names; </br> `street` - street names; </br> `house` - house numbers; </br> `apartment` - apartment numbers. |`street`|
| `parentid` | Yes |Integer | Parent identifier received in the response to the same request via the `id` parameter. For example, to get data on the `street` value, the `id` value is sent, that was received on `city` value. An empty value is sent for `city` in the initial request. |`10`|
|`Transaction`|Yes|Structure|Structure transmits the transaction data. See section "[Transaction Structure](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ?view#2-Data)".|See example below.|

:::success
<details>
<summary>Example of the request [20801]</summary>
<br>

~~~md
{
"Partner": {
"PartnerToken": "72a8ddb8-9145-4a41-af1a-8c48ecaa4be1",
"OperationType": 20801
},
"Data": "{\"dictionary\": \"street\", \"parentid\": 10, \"Transaction\": {\"TransactionID\": \"187725ff2f251\", \"TerminalID\": \"1\", \"DateTime\": \"20230221 120111\"}}",
"KeyAES": "",
"Sign": ""
}
~~~
</details>
:::

## Response

*See the general information on the response structure formation in the section "[General API Integration Information](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ)"*.

### Data Structure

Data structure of the response is formed from the following parameters:

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `dictionary` | Yes |String | Parameter requested. |`city`|
| `list`^1^ | Yes | Array | Array of structures transmits the data on all items of the requested parameter. | See example below.|

^1^ Parameters of the **"list"** array:

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `id` | Yes | String | Unique identifier of single item. |`111`|
| `name` | Yes | String | Name of single item. |`Vinnitsa`|
| `giocid` | Yes | Integer | Unique identifier of the "ГІОЦ" (Eng. Ukrainian Main Information and Computing Center) for single item. |`12312`|
| `accountid` | Yes/No | String | Unique account identifier for further debt request. The parameter is only sent for the value `apartment`. |`1`|

### Response Examples

:::success
<details>
<summary>Operation Successfully Completed</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>Operation Failed</summary>
<br>

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

## Related Requests

[[208011] Get Directory City Data](https://hackmd.io/LZsuqpBMR-iPJcnBKS7DmA)
[[20802] Get Debt Data](https://hackmd.io/GuQz5QT-RpGfdoqKjhMd8g)
[[10108] Debt Repayment](https://hackmd.io/9MdA15b8Ra-SS1pGfia0oQ)

## Reference Materials

General parameters of the XPAY system are given in the section ["Reference Materials"](https://hackmd.io/16yLv895Qo-FWTvrWWQwbg):  operation types, payment types, response codes, operation status, reasons of operation rejection, etc.

:arrow_left: [Guide](https://hackmd.io/QA2NYRliRLGviJl5P4-ZCw)
:arrow_left: [General API Integration Information](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ)

<details>
<summary>XPAY Support</summary>
</br>

Phone: [phone]
Email: [e-mail]
Telegram: @xpaysupportbot
</details>