API за управление на карти за мобилност Shell B2B – Ръководство за бързо стартиране

Версия на API: 3.1.5 | Удостоверяване: OAuth 2.0 | Статус: Производствена среда

Общ преглед

API-то за управление на картите на Shell е REST-базирано API, което позволява на разработчиците да управляват горивните карти на Shell чрез програмиране. API-то поддържа търсене на карти, поръчки, актуализации на статуса, анулиране, и различни други операции по управление на картите.

Забележка: Настоящото ръководство обхваща само крайни точки, автентифицирани чрез OAuth 2.0 (базов път: /card-management/v1). Старите крайни точки с Basic Auth (/fleetmanagement/v1/card) не са включени, тъй като постепенно се извеждат от употреба.

Основни функции

Търсене и филтриране на карти за гориво по гъвкави критерии
Поръчайте нови карти и проследявайте статуса на поръчката
Блокирайте, деблокирайте и анулирайте карти
Актуализиране на адресите за доставка на картите
Управление на настройките за автоматично подновяване на картите
Преместване на карти между групи карти и сметки
Искане на напомняния за ПИН кода

Важно съобщение – OAuth 2.0

ВАЖНО: OAuth 2.0 вече е стандартният метод за удостоверяване

Нови интеграции: Използвайте OAuth 2.0 от самото начало
Съществуващи интеграции: Планирайте миграцията си към OAuth 2.0
Стари методи: Basic Auth и API Key постепенно се премахват

Свържете се с техническата поддръжка на Shell, за да получите вашите идентификационни данни за OAuth 2.0 (client_id и client_secret).

Удостоверяване

OAuth 2.0 (стандартен метод за удостоверяване)

API-то за управление на карти на Shell използва потока за клиентски идентификационни данни на OAuth 2.0 за сигурно удостоверяване.

ПРЕДУПРЕЖДЕНИЕ: Всички клиенти трябва да планират преминаване към удостоверяване чрез OAuth 2.0. Това е препоръчителният и бъдещоориентиран метод за удостоверяване за API-то за управление на карти на Shell. Старите методи за удостоверяване постепенно се премахват.

Процес на OAuth 2.0

Стъпка 1: Получаване на токен за достъп

Искайте токен за достъп от крайната точка за OAuth токени:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=your-client-id&client_secret=your-client-secret

Стъпка 2: Използване на токена за достъп в заявките към API

Authorization: Bearer 
Content-Type: application/json

Управление на токени

Най-добри практики за управление на токени:

Токените за достъп имат ограничен срок на валидност (обикновено 15 минути)
Въведете кеширане на токените, за да избегнете ненужни заявки за токени
Обновете токените преди изтичането на валидността им, за да гарантирате непрекъсната услуга
Никога не споделяйте client_secret и не го вграждайте в код от страна на клиента

Стратегия за внедряване на OAuth 2.0

Защо да мигрирате към OAuth 2.0?

Предимства за сигурността:

Протокол за удостоверяване, отговарящ на индустриалните стандарти
Токените за достъп с ограничено време на валидност намаляват рисковете за сигурността
При всяко заявка не се предават идентификационни данни
По-добра поддръжка за ротация и отмяна на токени

Оперативни предимства:

Подобрена мащабируемост и производителност
По-добри възможности за мониторинг и одит
Опростено управление на удостоверенията
Интеграция, готова за бъдещето

Път за миграция

Ако в момента използвате остарели методи за удостоверяване, следвайте този път за миграция:

Поискайте данни за достъп по OAuth 2.0 от Техническата поддръжка на Shell
Внедрете управление на OAuth токени във вашето приложение
Тествайте изчерпателно в тестовата/Sandbox среда
Използвайте паралелна автентификация (OAuth + стари методи) по време на прехода
Наблюдавайте и валидирайте интеграцията с OAuth
Преминаване към изцяло OAuth след потвърждаване
Преустановете старата автентификация след успешна миграция

Среди

API-то е достъпно в две среди:

Среда	Базов URL	Предназначение
Производствена	https://api.shell.com	Производствена среда на живо
Тестова (Sandbox)	https://api-test.shell.com/test	Среда за тестване и разработка

Съвет: Винаги тествайте интеграцията си в тестовата среда, преди да преминете към производствената среда.

Бързо начало

1. Получете вашите OAuth идентификационни данни

Свържете се с техническата поддръжка на Shell
Поискайте идентификационни данни за OAuth 2.0 (client_id и client_secret)
Прегледайте условията за ползване

2. Получаване на токен за достъп

Първо, получите своя OAuth токен за достъп:

Пример с cURL:

curl -X POST https://api-test.shell.com/v2/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=your-client-id&client_secret=your-client-secret"

Отговор:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 899
}

3. Направете първото си API заявка

Пример: Търсене на активни карти

Пример с cURL:

curl -X POST https://api-test.shell.com/test/card-management/v1/search \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "Filters": {
 "PayerNumber": "CZ00000927",
 "AccountNumber": "CZ00000927",
 "ColCoCode": 32,
 "CardStatus": [
 "Active"
 ]
       
    },
    "Page": 1,
    "PageSize": 1
}'

Пример за отговор:

{
    "Page": 1,
    "TotalRecords": 7994,
    "Общ брой страници": 7994,
    "Размер на страницата": 1,
    "Данни": [
 {
 "Идентификатор на сметката": 1227,
            "AccountName": "Dominica1_C_1",
 "AccountNumber": "CZ00000927",
 "AccountShortName": "Dominica1_1",
            "Идентификатор на пакета": null,
 "Графици на блока на картата": null,
 "Идентификатор на групата на картата": null,
 "Име на групата на картата": null,
 "Идентификатор на картата": 491623,
            "CardTypeCode": "7027329",
 "CardTypeId": 11120,
 "CardTypeName": "CZ SFA NAT SIN - CHIP",
 "ColCoCountryCode": "CZ",
            "CreationDate": "20220810 23:53:25",
 "DriverName": "SHELL973169581",
            "EffectiveDate": "20220810",
 "ExpiryDate": "20260831",
 "FleetIdInput": true,
 "IsCRT": false,
 "IsFleet": true,
            "IsInternational": false,
 "IsNational": true,
 "IsPartnerSitesIncluded": false,
 "IsShellSitesOnly": true,
 "IssueDate": "20220812",
            "IsSuperseded": false,
 "IsVirtualCard": false,
 "LastModifiedDate": "20230614 00:05:16",
            "LastUsedDate": null,
 "LocalCurrencyCode": "CZK",
 "LocalCurrencySymbol": "Kč",
 "OdometerInput": true,
            "PAN": "7027329200001461736",
 "MaskedPAN": "7027329******461736",
 "PANID": 17268839,
            "PurchaseCategoryCode": "2",
 "PurchaseCategoryId": 102,
 "PurchaseCategoryName": "2 – Всички горивни продукти, артикули, свързани с автомобили, и TMF",
            "Причина": "Планирано за деблокиране",
 "Настройка за преиздаване": "True",
 "Описание на състоянието": "Активно",
 "Идентификатор на състоянието": 1,
            "TokenTypeID": 503742,
 "TokenTypeName": "CZ SFA NAT SIN – CHIP",
 "VRN": "VRN347886994",
            "ClientReferenceId": null,
 "IsEMVContact": true,
 "IsEMVContactless": false,
 "IsRFID": false,
 "RFIDUID": null,
            "EMAID": null,
 "EVPrintedNumber": null,
 "CardMediaCode": "100999",
 "MediumTypeID": 1,
 "MediumType": "Fuel Card"
 }
    ],
    "RequestId": "5a474d3e-70f4-4f7d-9416-5d5475b33e4f",
    "Status": "SUCCESS"
}

Справочник за API крайни точки

Търсене и извличане на карти

Крайна точка	Метод	Описание
/card-management/v1/search	POST	Търсене на карти с гъвкави филтри (OAuth 2.0)
/card-management/v1/details	POST	Извличане на подробности за отделна карта за гориво (OAuth 2.0)

Типични случаи на употреба:

Търсене по статус на картата (АКТИВНА, БЛОКИРАНА, ИЗТЕКЛА и др.)
Филтриране по име на шофьора или регистрационен номер на превозното средство
Търсене по PAN (последните 4 цифри)
Намерете карти, изтичащи след X дни

Обобщение за картата

Крайна точка	Метод	Описание
/card-management/v1/summary	POST	Получаване на обобщена информация за картите за гориво (OAuth 2.0)

Връща:

Общ брой карти по статус
Обобщени статистически данни по тип карта
Разбивка по активни и неактивни

Поръчка на карти

Крайна точка	Метод	Описание
/card-management/v1/ordercard	POST	Поръчка на една или повече карти за гориво (OAuth 2.0)
/card-management/v1/ordercardenquiry	POST	Проверка на статуса на поръчката на карти (OAuth 2.0)

Необходима информация за поръчка на карти:

ColCoCode (код на събиращата компания)
PayerNumber или PayerId
Номер на сметката
Тип и конфигурация на картата
Данни за адреса за доставка

Управление на състоянието на картата

Крайна точка	Метод	Описание
/card-management/v1/updatestatus	POST	Блокиране, деблокиране или анулиране на карти (OAuth 2.0)
/card-management/v1/schedulecardblock	POST	Планиране на заявки за блокиране/деблокиране на карти (OAuth 2.0)

Действия със статуса:

БЛОКИРАЙ - Временно блокиране на карта
ДЕБЛОКИРАНЕ - Реактивиране на блокирана карта
ПОВРЕДЕНА - Докладване на карта като повредена и заявка за замяна
TEMP_BLOCK_CUSTOMER - Временно блокиране по инициатива на клиента
TEMP_BLOCK_SHELL - Временно блокиране, инициирано от системата

ВНИМАНИЕ: Анулирането на картата е окончателно и не може да бъде отменено.

Допълнителни крайни точки

Категория	Крайна точка	Метод	Описание
Анулиране	/card-management/v1/cancel	POST	Анулиране на една или повече карти
Преместване на карти	/card-management/v1/move	POST	Преместване на карти в друга група карти или сметка
Управление на ПИН кода	/card-management/v1/pinreminder	POST	Искане на напомняне за ПИН кода на карта
Адрес за доставка	/card-management/v1/deliveryaddressupdate	POST	Актуализиране на адреса за доставка на карта
Автоматично подновяване	/card-management/v1/autorenew	POST	Актуализиране на индикатора за преиздаване

Примери за употреба

Пример 1: Търсене на карти, чийто срок на валидност изтича скоро

POST /card-management/v1/search

{
    "Filters": {
 "PayerNumber": "CZ00000927",
 "AccountNumber": "CZ00000927",
        "ColCoCode": 32,
 "CardStatus": [
 "Active"
 ],
 "ExpiringInDays" : 70
 
 },
    "Page": 1,
    "PageSize": 1
}

Пример 2: Временно блокиране на карта

POST /card-management/v1/updatestatus

{

  "Cards": [
    {
      "CardId": 125,
 "ColCoCode": 86,
 "PayerNumber": "PH50000843",
    },
    "ReasonId": 1236,
    "ReasonText": "Деблокиране",
    "TargetStatus": "Деблокиране"

  ]
}

Пример 3: Анулиране на карти

POST /card-management/v1/cancel

{
  
  "Cards": [
    {
 "CardId": 125,
      "CardExpiryDate": "20231231",
 "ColCoCode": 86,
 "PayerNumber": "PH50000843",
    }
  ],
  "ReasonText": "Изгубена",
  "RequestId": "1"
}

Обработка на грешки

Често срещани кодове за грешки

HTTP статус	Код на грешката	Описание	Решение
200	Н/Д	Статус: УСПЕХ	Н/Д
400	E0001	Грешка при валидиране	Проверете параметрите на заявката
401	E0003	Невъзможно достъп	Проверете дали OAuth токенът е валиден
403	E0003	Забранено	Проверете разрешенията на потребителя
404	E0005	Ресурсът не е намерен	Проверете дали URL адресът на крайната точка и ресурсът съществуват
500	E0002	Неизвестна грешка / Вътрешна грешка на сървъра	Свържете се с поддръжката

Най-добри практики

1. Преминете към удостоверяване чрез OAuth 2.0

ВАЖНО: Всички клиенти трябва да преминат към удостоверяване чрез OAuth 2.0. Въведете подходящо управление на токените:

Съхранявайте токените за достъп в кеш и ги използвайте повторно до изтичане на валидността им
Обновете токените преди изтичането на валидността им (препоръчително 60 секунди преди това)
Съхранявайте клиентските идентификационни данни по сигурен начин (използвайте променливи на средата или мениджър на тайни)
Никога не записвайте и не разкривайте токени за достъп в кода от страна на клиента

2. Използвайте идентификатори на заявки

Винаги включвайте уникален RequestId (в GUID формат) за проследяемост от начало до край

3. Внедрете пагинация

При големи масиви от данни използвайте пагинация, за да избегнете изтичане на времето за изчакване

4. Тествайте в тестова среда

Винаги тествайте интеграцията в тестовата среда, преди да преминете към производствена среда

SDK и примери за код

Shell предоставя официални SDK и изчерпателни примери за код, за да ускори вашата интеграция с API-то за управление на карти.

Налични езици за SDK

Python – SDK с пълен набор от функции и поддръжка на OAuth 2.0
TypeScript – SDK с типова безопасност и пълни дефиниции на типовете
Java - SDK за корпоративно ниво
C#/.NET - Пълна интеграция с .NET
PHP - Лесна за използване PHP библиотека
Ruby - Ruby gem за безпроблемна интеграция

Вижте официалните SDK и документация

Поддръжка и ресурси

Техническа поддръжка

Поддръжка: Техническа поддръжка на Shell

Документация

Получаване на помощ

Когато се свързвате с отдела за поддръжка, посочете:

Вашия client_id (никога не споделяйте client_secret или токените за достъп)
RequestId от отговора на API-то
Времева марка на заявката
Среда (Производствена/Тестова)

Последно актуализирано: 1 юли 2026 г.
Версия на документа: 1.0
Версия на API: 3.1.5

Изберете вашия език

API за управление на карти за мобилност Shell B2B – Ръководство за бързо стартиране

Общ преглед

Основни функции

Важно съобщение – OAuth 2.0

Удостоверяване

OAuth 2.0 (стандартен метод за удостоверяване)

Процес на OAuth 2.0

Стъпка 1: Получаване на токен за достъп

Стъпка 2: Използване на токена за достъп в заявките към API

Управление на токени

Стратегия за внедряване на OAuth 2.0

Защо да мигрирате към OAuth 2.0?

Предимства за сигурността:

Оперативни предимства:

Път за миграция

Среди

Бързо начало

1. Получете вашите OAuth идентификационни данни

2. Получаване на токен за достъп

Пример с cURL:

Отговор:

3. Направете първото си API заявка

Пример с cURL:

Пример за отговор:

Справочник за API крайни точки

Търсене и извличане на карти

Обобщение за картата

Поръчка на карти

Управление на състоянието на картата

Допълнителни крайни точки

Примери за употреба

Пример 1: Търсене на карти, чийто срок на валидност изтича скоро

Пример 2: Временно блокиране на карта

Пример 3: Анулиране на карти

Обработка на грешки

Често срещани кодове за грешки

Най-добри практики

1. Преминете към удостоверяване чрез OAuth 2.0

2. Използвайте идентификатори на заявки

3. Внедрете пагинация

4. Тествайте в тестова среда

SDK и примери за код

Налични езици за SDK

Поддръжка и ресурси

Техническа поддръжка

Документация

Получаване на помощ

За нас

Свържете се с

Влезте в профила си