CCES Fueling API
Авторизация
Aутентификация запроса происходит при указании 2-х заголовков:
X-Org-Id
X-Api-Key
Получение списка АЗС
GET {{baseUrl}}/partner-api/v1/gas-stations
Content-Type: application/json
X-Org-Id: {{org_id}}
X-Api-Key: {{api_key}}
Пример ответа:
{
"gasStations": [
{
"id": "bfc43d01-982e-487c-979d-8ad15825f06b",
"brand": "Газпромнефть",
"name": "АЗС №75",
"address": "Адрес",
"latitude": 60.052184,
"longitude": 30.317479,
"region": "Москва",
"paymentType": "PREPAYMENT",
"nozzleTaking": "AFTER_ORDER",
"serviceType": "CLASSIC",
"fuelTypes": {
"diesel": "ДТ",
"premium-95": "G-Drive 95",
"propane": "Пропан"
}
}
]
}
Тип оплаты заказов:
| paymentType | Описание |
|---|---|
PREPAYMENT | Предоплата |
POSTPAYMENT | Постоплата |
MIXED | Доступны и предоплата, и постоплата |
Когда пользователю снимать пистолет:
| nozzleTaking | Описание |
|---|---|
AFTER_ORDER | Сначала пользователь должен нажать кнопку “Заправиться”, и только по разрешению от приложения вставлять пистолет, иначе разместить заказ не удастся |
BEFORE_ORDER | Перед тем, как нажимать кнопку “Заправиться” пользователь должен вставить пистолет в бак |
ANY | Можно вставлять пистолет в бак как перед созданием заказа, так и после |
Типы АЗС по способам обслуживания:
| serviceType | Описание |
|---|---|
CLASSIC | Обычная АЗС, на которой можно оплатить топливо оператору на кассе |
AUTOMATIC | Автоматическая безоператорная АЗС с терминалом самообслуживания |
ELECTRO | Электрическая зарядная станция |
Получение деталей АЗС
GET {{baseUrl}}/partner-api/v1/gas-stations/{{gasStationId}}?pingPumps=true
Content-Type: application/json
X-Org-Id: {{org_id}}
X-Api-Key: {{api_key}}
Параметры запроса:
pingPumps - требуются ли актуальные статусы колонок. По умолчанию - false. Если значение = false, то все колонки будут иметь статус FREE
Пример ответа:
{
"id": "bfc43d01-982e-487c-979d-8ad15825f06b",
"brand": "Газпромнефть",
"name": "АЗС №75",
"address": "Адрес",
"latitude": 60.052184,
"longitude": 30.317479,
"region": "Москва",
"paymentType": "PREPAYMENT",
"nozzleTaking": "AFTER_ORDER",
"serviceType": "CLASSIC",
"status": "ENABLED",
"pumps": [
{
"number": 1,
"fuelTypes": [ "diesel", "premium-95", "propane" ],
"status": "FREE"
},
{
"number": 2,
"fuelTypes": [ "ai-92", "premium-95", "premium-100" ],
"status": "BUSY"
}
],
"fuelTypes": {
"diesel": "ДТ",
"propane": "Пропан",
"ai-92": "АИ 92",
"premium-95": "G-Drive 95",
"premium-100": "G-Drive 100"
},
"prices": {
"diesel": 55.45,
"premium-95": 50.0,
"propane": 30.1,
"ai-92": 40.70,
"premium-100": 60.59
},
"discountPrices": {
"diesel": 53.45,
"premium-95": 40.0,
"propane": 20.1,
"ai-92": 30.70,
"premium-100": 55.59
},
"partnerUserPrices": {
"diesel": 53.45,
"premium-95": 40.0,
"propane": 20.1,
"ai-92": 30.70,
"premium-100": 55.59
}
}
prices - цены на стелле АЗС
discountPrices - цены со скидкой для партнёра
partnerUserPrices - цены для пользователей партнёра, если взиманием средств занимается ЦЦЭС (если при создании заказа используется "paymentMethod" : "SBP" или "paymentMethod" : "BANK_CARD")
| Статус АЗС | Описание |
|---|---|
ENABLED | АЗС исправна и работает |
CASHIER_SHIFT_IN_PROGRESS | На АЗС идёт пересменка |
DISABLED | АЗС отключена |
| Статус колонки | Описание |
|---|---|
FREE | Колонка свободна |
BUSY | Колонка занята |
WAITING_PAYMENT | Постоплатный заказ завершён и ожидает оплаты. Такое может быть, если клиент АЗС заправился и пошёл платить на кассу, но при этом постоплата через приложение может быть недоступна |
DISABLED | Колонка отключена |
Создание предоплатного заказа на топливо
PUT {{baseUrl}}/partner-api/v1/fuelings/{{fuelingId}}
Content-Type: application/json
X-Org-Id: {{org_id}}
X-Api-Key: {{api_key}}
fuelingId - идентификатор заказа в формате UUID
Пример запроса:
{
"fuelType": "diesel",
"gasStationId": "e3b9d1c7-0511-432d-b82a-d2b0001de064",
"userId": "bfc43d01-982e-487c-979d-8ad15825f06b",
"pumpNumber": 1,
"volume": 10.0,
"price": 55.45,
"chequeEmail": "ap1kx@example.com",
"paymentMethod": "SBP"
}
Параметры:
chequeEmail - необязательный. Указывается только в том случае, если требуется фискализация на стороне ЦЦЭС
paymentMethod - необязательный. Указывается только в том случае, если деньги с пользователя должен принять ЦЦЭС.
В текущей версии поддерживается только значение SBP
Пример ответа с оплатой через СБП:
{
"fuelingId": "ccc7d2d3-b90d-4dd4-b245-462201afdb7e",
"paymentFormUrl": "https://qr.nspk.ru/AD1000H32PWGLFF3TW6SB2RHWY6TFI87?type=02&bank=100000000001&sum=51000&cur=RUB&crc=QNCO",
"successful": true
}
Пример ответа без оплаты:
{
"fuelingId": "ccc7d2d3-b90d-4dd4-b245-462201afdb7e",
"successful": true
}
Пример ответа с ошибкой:
{
"fuelingId": "ccc7d2d3-b90d-4dd4-b245-462201afdb7e",
"successful": false,
"error": "Указана неверная цена"
}
Ошибки:
| Код | Описание |
|---|---|
400 | переданы некорректные параметры |
401 | неверные параметры авторизации |
402 | передана неверная цена |
409 | Проблема с размещением заказа на стороне поставщика |
417 | Пистолет снят раньше времени |
Получение данных о заказе
GET {{baseUrl}}/partner-api/v1/fuelings/{{fuelingId}}
Content-Type: application/json
X-Org-Id: {{org_id}}
X-Api-Key: {{api_key}}
Пример ответа:
{
"fuelingId": "ccc7d2d3-b90d-4dd4-b245-462201afdb7e",
"gasStationId": "e3b9d1c7-0511-432d-b82a-d2b0001de064",
"userId": "bfc43d01-982e-487c-979d-8ad15825f06b",
"fuelType": "diesel",
"fuelName": "ДТ",
"pumpNumber": 1,
"volume": 10.0,
"factVolume": 9.8,
"price": 55.45,
"factSum": 543.41,
"discountPrice": 54.20,
"factDiscountSum": 531.16,
"partnerUserPrice": 55.00,
"factPartnerUserSum": 539,
"status": "COMPLETED",
"chequeEmail": null,
"paymentMethod": null,
"createdAt": 1748537411442,
"finishedAt": 1748538078467,
"cheques": [
{
"chequeUrl": "https://consumer.1-ofd-test.ru/v1?fn=9999078900006242&fp=4155744073&i=9877",
"chequeType": "PREPAYMENT",
"fiscalizedAt": 1748538078467
},
{
"chequeUrl": "https://consumer.1-ofd-test.ru/v1?fn=9999078900006242&fp=2742570411&i=9857",
"chequeType": "INSTANT_PAYMENT",
"fiscalizedAt": 1748538078467
}
],
"error": null }
Параметры createdAt и finishedAt - Epoch time в миллисекундах.
| Тип чека | Описание |
|---|---|
INSTANT_PAYMENT | Чек полного расчета |
REFUND | Чек возврата |
PREPAYMENT | Чек предоплаты |
API на стороне партнёра
Обработка callback запросов для обновления статуса заказа
POST {{baseUrl}}/cces-api/callback
Content-Type: application/json
X-Org-Id: {{org_id}}
X-Api-Key: {{api_key}}
Пример запроса для успешно завершенного заказа:
{
"fuelingId": "ccc7d2d3-b90d-4dd4-b245-462201afdb7e",
"status": "COMPLETED",
"finishedAt": 1748537411442,
"factVolume": 10.0,
"factSum": 600,
"factDiscountSum": 580,
"factPartnerUserSum": 590,
"cheques": [
{
"chequeUrl": "https://consumer.1-ofd-test.ru/v1?fn=9999078900006242&fp=4155744073&i=9877",
"chequeType": "PREPAYMENT",
"fiscalizedAt": 1748538078467
},
{
"chequeUrl": "https://consumer.1-ofd-test.ru/v1?fn=9999078900006242&fp=2742570411&i=9857",
"chequeType": "INSTANT_PAYMENT",
"fiscalizedAt": 1748538078467
}
]
}
Пример запроса для промежуточных статусов:
{
"fuelingId": "ccc7d2d3-b90d-4dd4-b245-462201afdb7e",
"status": "PLACED" | "WAITING_FOR_START" | "STARTED" | "WRONG_NOZZLE_TAKEN" }
Если получен статус WRONG_NOZZLE_TAKEN - то заказ не отменяется. Пользователю следует повесить на место неправильный пистолет и снять правильный
Пример запроса для завершенного с ошибкой заказа:
{
"fuelingId": "ccc7d2d3-b90d-4dd4-b245-462201afdb7e",
"status": "CANCELLED" | "FAILED",
"finishedAt": 1748537411442,
"error": "Указана неверная цена" | "ТРК занята" | "Заказ отменён по таймауту"
}
status - статус заказа. Возможные значения:
| Статус | Описание |
|---|---|
PLACED | Заказ размещён в системе поставщика, но ждёт подтверждения |
WAITING_FOR_START | Вставьте пистолет |
STARTED | Заправка началась |
COMPLETED | Заправка завершена |
CANCELLED | Заказ отменён поставщиком |
FAILED | Заказ завершен с ошибкой |
WRONG_NOZZLE_TAKEN | Пользователь снял не тот пистолет |
WAITING_FOR_PAYMENT | Заказ ожидает оплаты (при оплате по СБП) |
