B2B Mobility Customer Data v3.0.5 | Ръководство за бързо стартиране: Данни за клиентите на B2B Mobility

Бързо начало с данните за клиенти на B2B Mobility

Въведение

API-то за данни за клиенти на B2B Mobility е RESTful услуга, която ви позволява да извличате и управлявате данни за клиентски профили, групи карти и свързани с тях конфигурации в рамките на платформата Shell Cards. Този API предлага гъвкави възможности за търсене, поддържа разбиване на страници и ви позволява да извличате информация за акаунти, адреси за доставка на карти, ценови листи и типове карти. Той също така поддържа операции за създаване и актуализиране на групи карти, както и преместване на карти между групи.

Предимства	Описание
Цялостно управление на акаунти	Достъп до подробна информация за клиентските акаунти, включително фактуриране, обобщения за картите и статус
Операции с групи карти	Създаване, актуализиране и прекратяване на групи карти с гъвкави възможности за преместване на карти
Достъп до ценови листи	Извличане на национални и международни ценови листи с отстъпки, специфични за клиента
Гъвкаво търсене	Заявка за данни с множество критерии за търсене и поддръжка на разбиване на страници

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

Този API поддържа както Basic Authentication, така и OAuth 2.0. OAuth 2.0 е препоръчителният метод за удостоверяване за повишена сигурност.

Забележка за миграция

API-то вече поддържа удостоверяване чрез OAuth 2.0. Ако в момента използвате „Основна автентификация“, препоръчваме да мигрирате към OAuth 2.0 за по-голяма сигурност. Базовият URL адрес е актуализиран и всички крайни точки вече са версирани под пътя /v1. Моля, вижте Поддръжката за миграция към OAuth 2.0 за подробни указания за миграцията.

Процес на оторизация

Искане на клиентски идентификатор и тайна

Свържете се с екипа на Shell API, за да поискате достъп до OAuth автентификация. Екипът на Shell API ще ви предостави клиентски идентификатор и тайна.

Искане на Bearer токен

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

Пример за заявка:

curl --location --request POST 'https://api-test.shell.com/v2/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=**************' \
--data-urlencode 'client_secret=**************' \
--data-urlencode 'grant_type=client_credentials'

В отговора ще получите токен от типа „Bearer“:

{
   "access_token": "**************",
   "expires_in": "899",
   "token_type": "Bearer"
}

Забележка: Времето за изтичане на валидността на токена „Bearer“ се посочва в секунди.

Упълномощаване на API заявки

При извикване на Shell API-та включете следното в заглавката на заявката.

Authorization: Bearer access_token

Базови URL адреси

Среда	URL
Тестова	https://api-test.shell.com/test
Производствена среда	https://api.shell.com

Основна интеграция

1. Извличане на данни за вписания потребител

Описание: Този ендпойнт извлича данните на вписания потребител, включително достъпните плащатели, сметки и роли. Тази операция трябва да се извика след успешна автентификация, за да се получи PayerId, необходим за последващи API извиквания.

Път: POST /user-management/v1/loggedinuser

Примерно заявка

curl --location 'https://api-test.shell.com/test/user-management/v1/loggedinuser' \
--header 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "Filters": {
    "IncludePayerGroup": false,
    "IncludeEIDDetails": false,
    "RequestedAPIName": "v1/Card/OrderCard"
  }
}'

Параметри на заявката

Параметър	Тип	Задължителен	Описание
RequestId	string	Да	Задължителен UUID (RFC 4122) за проследяване на заявката
IncludePayerGroup	boolean	Не	Включва информация за групата на платеца, когато стойността е true (по подразбиране: false)
IncludeEIDDetails	boolean	Не	Включва данни за електронната фактура, когато стойността е true (по подразбиране: false)

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

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
 "UserName": "John123",
 "DisplayName": "John A.",
      "HasAPIAccess": true,
 "Payers": [
 {
 "IsDefault": true,
 "ColcoId": 1,
 "ColcoCode": 86,
          "PayerId": 1234,
 "PayerNumber": "GB000000123",
 "PayerName": "MATTHEW ALGIE & COMPANY LIMITED"
 }
 ]
    }
  ]
}

Полета в отговора

Поле	Тип	Описание
UserName	string	Идентификатор на вписания потребител
DisplayName	string	Име на вписания потребител
HasAPIAccess	булева стойност	Истинска, ако потребителят има достъп до искания API
PayerId	цяло число	Идентификатор на платеца за използване в последващи заявки
PayerNumber	string	Номер на платеца за използване в последващи заявки

2. Заявка за клиентски сметки

Описание: Този ендпойнт позволява да се правят заявки за подробности за клиентски сметки от платформата Shell Cards с гъвкави критерии за търсене и поддръжка на разбиване на страници. Използвайте PayerId, получен от предишната стъпка.

Път: POST /customer-management/v1/accounts

Примерно заявка

curl --location 'https://api-test.shell.com/test/customer-management/v1/accounts' \
--header 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "Filters": {
    "ColCoCode": 86,
    "PayerNumber": "GB000000123",
    "Status": "ACTIVE",
    "IncludeCardSummary": true
  },
  "Page": 1,
  "PageSize": 50
}'

Параметри на заявката

Параметър	Тип	Задължително	Описание
ColCoCode	цяло число	Да	Код на събиращата компания (код на Shell)
PayerNumber	string	Да	Номер на платеца на клиента
Status	string	Не	Филтър за състоянието на сметката (ACTIVE, BLOCKED, ОТМЕНЕН и др.)
IncludeCardSummary	булева стойност	Не	Включване на подробности за обобщението на картата (по подразбиране: true)
Page	цело число	Не	Номер на страницата (по подразбиране: 1)
Размер на страницата	цело число	Не	Брой записи на страница (по подразбиране: 50)

Примерен отговор

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
 "AccountId": 1,
 "AccountNumber": "GB000000124",
 "AccountFullName": "Acme Corporation",
 "Status": "Active",
      "CurrencyCode": "EUR",
 "TotalCards": 1000,
 "TotalActiveCards": 500
    }
  ],
  "Page": 1,
  "TotalRecords": 100,
  "TotalPages": 2,
  "PageSize": 50
}

Полета на отговора

Поле	Тип	Описание
AccountId	цело число	Идентификатор на сметката
AccountNumber	низ	Номер на сметката
AccountFullName	string	Пълно име на сметката
Status	string	Текущ статус на сметката
CurrencyCode	string	ISO код на валутата
TotalCards	цело число	Общ брой карти към сметката
TotalActiveCards	цело число	Брой активни карти

3. Заявка за групи карти

Описание: Този ендпойнт извлича подробности за групите карти от платформата Shell Cards с гъвкави критерии за търсене и разбиване на страници. Групите карти помагат за организирането на картите в рамките на една сметка.

Пътека: POST /customer-management/v1/cardgroups

Примерно заявка

curl --location 'https://api-test.shell.com/test/customer-management/v1/cardgroups' \
--header 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "Filters": {
    "ColCoCode": 86,
    "PayerNumber": "GB000000123",
    "Status": "ACTIVE"
  },
  "Page": 1,
  "PageSize": 50
}'

Параметри на заявката

Параметър	Тип	Задължителен	Описание
ColCoCode	цело число	Да	Код на събиращата компания
PayerNumber	низ	Да	Номер на платеца на клиента
Статус	низ	Да	Статус на групата карти (АКТИВЕН, ПРЕКРАТЕН, ВСИЧКИ)
CardGroupName	string	Не	Филтриране по име на група карти (мин. 2 символа)

Примерен отговор

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
      "CardGroupId": 40000,
 "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
 "Status": "ACTIVE",
 "PrintOnCard": true,
      "CardTypeId": 1234,
 "TotalCards": 1234,
 "ActiveCards": 999
    }
  ],
  "Page": 1,
  "TotalRecords": 100,
  "TotalPages": 2,
  "PageSize": 50
}

Полета в отговора

Поле	Тип	Описание
CardGroupId	цело число	Идентификатор на групата карти
CardGroupName	string	Име на групата карти
Status	string	Статус на групата карти
TotalCards	цело число	Общ брой карти в групата
ActiveCards	цело число	Брой активни карти в групата

4. Създаване на група карти

Описание: Този ендпойнт създава нова група карти в платформата Shell Cards и по избор премества до 500 карти в новосъздадената група. Заявките за преместване на карти се поставят в опашка след валидиране.

Път: POST /customer-management/v1/createcardgroup

Примерно заявка

curl --location 'https://api-test.shell.com/test/customer-management/v1/createcardgroup' \
--header 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "ColCoCode": 86,
  "PayerNumber": "GB000000123",
  "AccountNumber": "GB000000124",
  "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
  "PrintOnCard": true,
  "Cards": [
    {
 "AccountNumber": "GB99215176",
 "PAN": "7002051006629890645"
    }
  ]
}'

Параметри на заявката

Параметър	Тип	Задължителен	Описание
ColCoCode	цело число	Да	Код на събиращата компания
PayerNumber	низ	Да	Номер на платеца на клиента
AccountNumber	низ	Да	Номер на сметката на клиента
CardGroupName	низ	Да	Име на новата група карти (1–40 символа)
PrintOnCard	булева	Да	Дали името на групата карти да се отпечата върху картите
Карти	масив	Не	Списък с картите, които да се преместят (макс. 500)

Примерен отговор

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
 "MainReference": 1234,
 "NewCardGroupReference": 5672,
 "SuccessfulRequests": [
        {
 "PAN": "7002051123456789145",
 "Reference": 12345
 }
 ],
 "ErrorCards": []
    }
  ]
}

Полета на отговора

Поле	Тип	Описание
MainReference	цело число	Референтен номер за проследяване на цялостното заявка
NewCardGroupReference	цело число	Референтен номер за създаване на група карти
SuccessfulRequests	масив	Списък с успешно поставени в опашката заявки за преместване на карти
ErrorCards	масив	Списък с карти, които не са преминали валидация

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

API-то използва стандартни HTTP статусни кодове. В случай на грешка в тялото на отговора ще бъдат предоставени допълнителни подробности.

Код на грешката	Описание	Решение
E0001	Грешка при валидиране	Проверете параметрите на заявката за липсващи или невалидни стойности
E0003	Няма разрешение	Проверете удостоверенията и се уверете, че потребителят има достъп до операцията
E0005	Ресурсът не е намерен	Потвърдете, че исканият ресурс съществува и е достъпен
9015	Дублирано име на група карти	Използвайте уникално име на група карти за клиента

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

B2B Mobility Customer Data 3.0.5

Бързо начало с данните за клиенти на B2B Mobility

Въведение

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

Забележка за миграция

Процес на оторизация

Базови URL адреси

Основна интеграция

1. Извличане на данни за вписания потребител

Примерно заявка

Параметри на заявката

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

Полета в отговора

2. Заявка за клиентски сметки

Примерно заявка

Параметри на заявката

Примерен отговор

Полета на отговора

3. Заявка за групи карти

Примерно заявка

Параметри на заявката

Примерен отговор

Полета в отговора

4. Създаване на група карти

Примерно заявка

Параметри на заявката

Примерен отговор

Полета на отговора

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

За нас

Свържете се с

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