API АЗС
Основне завдання: мета цього API — надати банкам доступ до даних АЗС та дозволити ініціювати транзакції на заправці через взаємодію з системою ритейлера.
Авторизація
Авторизація для всіх API відбувається за допомогою Bearer Token.
Як згенерувати Bearer Token
Для генерації токена використовуйте api.
Приклад:
{
"Authorization": "Bearer {{authToken}}"
}Зверніть увагу: токен має термін дії.
Список АЗС
Опис: отримати список доступних АЗС
Метод: GET
URL: /FuelSystem/stations/{RetailerId}
Успішна відповідь
HTTP-код: 200
{
"status": true,
"stations": [
{
"codeAZS": "STATION01",
"name": "Central Fuel Station",
"address": "123 Main Street, City",
"status": "active"
},
{
"codeAZS": "STATION02",
"name": "Highway Fuel Station",
"address": "456 Highway Road, City",
"status": "active"
}
]
}Поля відповіді:
| Параметр | Тип | Опис |
|---|---|---|
status | Boolean | Статус відповіді |
stations | Array | Масив об’єктів АЗС |
codeAZS | String | Код АЗС (макс. 10 символів) |
name | String | Відображувана назва АЗС |
adress | String | Фізична адреса АЗС |
status | String | Статус доступності АЗС |
Отримання конфігурації АЗС
Опис: отримати конфігурацію АЗС
Метод: POST
URL: FuelSystem/station-config/{RetailerId}/{phoneNumber}
Тіло запиту:
{
"codeAZS": "STATION02"
}Опис основного об’єкта:
| Параметр | Тип | Обов’язковий | Опис |
|---|---|---|---|
codeAZS | String 10 | Так | Код АЗС |
Успішна відповідь
HTTP-код: 200
Тіло відповіді:
{
"status": true,
"fuelStationData": [
{
"nozzle": 3,
"goodsCode": 20002,
"dispenser": 2,
"goodsName": "Premium Gasoline 95",
"price": 32.5,
"goodsGUID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
],
"retailerToken": "Xk9mN2pQ8vR5tY3wE7sA1bC4dF6gH8iJ",
"companyId": "7890"
}Поля відповіді:
| Параметр | Тип | Обов’язковий | Опис |
|---|---|---|---|
status | Boolean | Так | Статус відповіді |
fuelStationData | Array | Так | Масив об’єктів конфігурації АЗС |
nozzle | boolean | Так | Інформаційне, для відображення конфігурації АЗС |
goodsCode | Number | Так | Обов’язкове для операцій продажу |
dispenser | Number | Так | Обов’язкове для операцій продажу |
goodsName | Number | Ні | Інформаційне, для відображення конфігурації АЗС |
price | Number | Так | АКТУАЛЬНА поточна ціна для розрахунків пального |
goodsGUID | String | Ні | Інформаційне, альтернатива GoodsCode |
retailerToken | String | Ні | ОБОВ’ЯЗКОВИЙ для всіх наступних операцій |
companyId | String | Ні | ОБОВ’ЯЗКОВИЙ для операцій з пальним |
Перевірка колонки
Опис: перевіряє, чи готова колонка до заправки. Цей крок валідує статус колонки перед продовженням продажу.
Метод: POST
URL: /FuelSystem/checkdispenser/{RetailerId}/{phoneNumber}}
Тіло запиту:
{
"retailerToken": "Xk9mN2pQ8vR5tY3wE7sA1bC4dF6gH8iJ",
"codeAZS": "STATION02",
"dispenser": "02",
"goodsCode": "20002",
"summ": 75.25,
"quantity": 0
}Опис основного об’єкта:
| Параметр | Тип | Обов’язковий | Опис |
|---|---|---|---|
retailerToken | String | Так | Авторизаційний retailerToken |
codeAZS | String | Так | Код АЗС |
dispenser | String | Так | Ідентифікатор колонки |
goodsCode | String | Так | Код типу пального |
summ | Number | Так | Сума транзакції |
quantity | Number | Так | Кількість пального (0 для розрахунку за сумою) |
Успішна відповідь
HTTP-код: 200
Тіло відповіді:
"{customerOrderId": "7a8b9c0d-1e2f-3g4h-5i6j-7k8l9m0n1o2p"}Поля відповіді:
| Параметр | Тип | Опис |
|---|---|---|
customerOrderId | String | ID замовлення клієнта |
Продаж пального
Метод: POST
URL: /FuelSystem/fuelsale/{RetailerId}/{phoneNumber}
Тіло запиту:
"retailerToken": "Xk9mN2pQ8vR5tY3wE7sA1bC4dF6gH8iJ",
"customerOrderId": "7a8b9c0d-1e2f-3g4h-5i6j-7k8l9m0n1o2p",
"paymentId": "PAY98765432",
"paymentSystem": "Mastercard",
"terminalId": "87654321",
"summ": 75.25,
"holdSumm": 75.25,
"quantity": 0,
"rrn": "123456789012345",
"cardmask": "5432********8765"Опис основного об’єкта:
| Параметр | Тип | Обов’язковий | Опис |
|---|---|---|---|
retailerToken | String | Так | Авторизаційний retailerToken |
customerOrderId | String | Так | ID замовлення клієнта з checkdispenser |
paymentId | String | Так | ID транзакції платіжної системи |
paymentSystem | String | Так | Назва платіжної системи |
terminalId | String | Так | ID терміналу |
summ | Number | Так | Авторизаційний retailerToken |
holdSumm | Number | Так | Сума холду |
quantity | Number | Так | Кількість пального |
rrn | Number | Так | Авторизаційний retailerToken |
cardmask | String | Так | Авторизаційний retailerToken |
Успішна відповідь
HTTP-код: 200
Тіло відповіді:
{"status": true}Поля відповіді:
| Параметр | Тип | Опис |
|---|---|---|
status | Boolean | Статус операції |
Рахунки
Опис: звірка платежів для перевірки транзакцій між системами партнера та АЗС.
Метод: POST
URL: /FuelSystem/invoices/{RetailerId}/{phoneNumber}
Тіло запиту:
{
"date": "2024-01-15T10:30:00Z",
"invoices": [
{
"date": "2024-01-15T14:22:15Z",
"id": "2024001",
"summ": 450.75
},
{
"date": "2024-01-15T16:45:30Z",
"id": "2024002",
"summ": 125.5
}
]
}Опис основного об’єкта:
| Параметр | Тип | Обов’язковий | Опис |
|---|---|---|---|
date | String | Так | Дата звірки (ISO 8601) |
invoices | Array | Так | Масив об’єктів рахунків |
Опис об’єкта рахунку:
| Параметр | Тип | Обов’язковий | Опис |
|---|---|---|---|
date | String | Так | Дата рахунку (ISO 8601) |
id | String | Так | Ідентифікатор рахунку |
summ | Number | Так | Сума рахунку |
Тіло відповіді:
{
"status": true,
"checkResult": [
{
"idPartner": "2024001",
"summPartner": 450.75,
"datePartner": "2024-01-15T14:22:15Z",
"order": "",
"date": "",
"summ": 0,
"idPaymentOrder": "",
"customerOrderId": "",
"difference": -450.75,
"differenceCode": 1
}
]
}Поля відповіді:
| Параметр | Тип | Опис |
|---|---|---|
status | Boolean | Статус операції |
checkResult | Array | Результати звірки |
Поля CheckResult:
| Параметр | Тип | Опис |
|---|---|---|
idPartner | String | Номер платежу партнера з методу invoices |
summPartner | Number | Сума платежу партнера |
datePartner | String | Дата платежу партнера |
order | String | Номер замовлення АЗС |
date | String | Дата замовлення на АЗС |
summ | Number | Сума замовлення на АЗС |
idPaymentOrder | String | Номер платежу з функції fuelsale |
customerOrderId | String | ID замовлення клієнта з відповіді checkdispenser |
difference | Number | Різниця між платежем і фактичною заправкою |
differenceCode | Number | Код розбіжності при звірці |
Коди розбіжностей:
| Код | Опис |
|---|---|
| 1 | Є в чеках партнера, відсутній на АЗС |
| 2 | Є в замовленнях АЗС, відсутній у партнера |
| 3 | Різниця між сумами заправки та платежу |
Обробка помилок
Формат відповіді з помилкою
Усі відповіді з помилками мають такий стандартний формат. Поле error містить конкретний код помилки для налагодження та обробки:
{
"status": false,
"error": 1,
"message": "The server is busy. Try again later."
}Поля відповіді з помилкою:
| Параметр | Тип | Опис |
|---|---|---|
status | Статус відповіді (false для помилок) | |
error | Number | Конкретний код помилки для налагодження |
message | Object | Багатомовні повідомлення про помилки |
Типи полів
| Поле | Тип | Опис |
|---|---|---|
| Status | Response | status (boolean) |
| Retailer Id | ID ідентифікації партнера або сервісу | |
| Customer Order ID | Унікальний ідентифікатор замовлення клієнта |
Опис типів полів
| Поле | Тип | Опис |
|---|---|---|
| Amount | Десяткове число з 2 знаками після коми | |
| Date | Формат: YYYY-MM-DDTHH:mm:ssZ (ISO 8601) | |
| GUID | Стандартний формат UUID |
Формати дат
- Формат дати: YYYY-MM-DDTHH:mm:ssZ (ISO 8601)
- Приклад: 2024-01-15T14:22:15Z (15 січня 2024, 14:22:15 UTC)
- Часовий пояс: UTC