Получение информации по бизнес-картам

Обновлено 29 ноября 2024

Компаниям

/fintech/api/v2/corporate-cards/list

Ресурс позволяет получить информацию по всем бизнес-картам конкретного пользователя, чей access_token используется для запроса.

Для получения списка бизнес-карт пользователя необходимо отправить POST-запрос /fintech/api/v2/сorporate-cards/list с токеном доступа (access_token) пользователя в параметре Authorization заголовка и информацией о количестве карт, которое нужно вывести, в теле запроса.

В параметре scope ссылки авторизации пользователя должен быть указан сервис CORPORATE_CARDS для получения доступа к этому ресурсу.

Для обращения к методу необходимо отправлять запрос на:

• Тестовый контур https://iftfintech.testsbi.sberbank.ru:9443
• Промышленный контур https://fintech.sberbank.ru:9443

Request

/fintech/api/v2/corporate-cards/list

• Модель
• Пример

Наименование	Тип	Формат	Regexp	Обязательность	Описание
HEADER
Authorization	string	string	^([a-zA-Z0-9]){38}$	required	Access token пользователя, полученный через SSO.
BODY
pagination {
count	number	integer	^[0-9]{10000}$	required	Количество карт, которое нужно вывести на странице,
offset	number	integer	^[0-9]$	required	Оффсет, количество карт, которые необходимо пропустить.
}

POST /fintech/api/v2/corporate-cards/list HTTP/1.1
Content-Type: application/json
Authorization: Bearer xbgDF3brf456ghi789jkl012mNKFtEpqr678
 
{
    "pagination": {
      "count": 5,    
      "offset": 0
    }
  }

Responses

200 (OK)

• Модель
• Пример

Наименование	Тип	Обязательность	Описание
Cards{
cards	Array[Cards]	object
}
Cards{
businessCardId	string	required	Внешний идентификатор карты,
cardStatus	string	required	Статус карты (ACTIVE - Активна, NOT_ACTIVE - Неактивна, BLOCKED - Заблокирована клиентом, BLOCKED_BY_BANK - Заблокирована банком),
accountNumber	string	required	Номер счета, к которому привязана карта,
maskedCardNumber	string	required	Замаскированный номер карты,
embossedName	string	optional	Эмбоссированное имя клиента на карте,
holderName	string	required	ФИО держателя карты,
userIsHolder	string	required	Признак держателя карты,
cardOpenDate	string	optional	Дата выдачи карты,
cardExpiryDate	string	optional	Дата окончания действия карты.
}
pagination {
hasNextPage	boolean	required	Признак наличия следующей страницы,
count	number	required	Запрошенное количество карт,
offset	number	required	Запрошенный оффсет.
}

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
 
{
  "cards": [
    {
      "businessCardId": "53b6b78a8e23432e8e2249ad4f254a17",
      "cardStatus": "ACTIVE",
      "accountNumber": "40802810600000200000",
      "maskedCardNumber": "484349******8524",
      "embossedName": "IVAN IVANOV",
      "holderName": "ИВАН ИВАНОВИЧ И.",
      "userIsHolder": true,
      "cardOpenDate": "2023-12-31",
      "cardExpiryDate": "2028"
    }
  ],
  "pagination": {
    "hasNextPage": true,
    "offset": "0",
    "count": "5"
  }
}

400 (Bad request)

Cause	Message	Description
VALIDATION_ERROR	Ошибка валидации	Данные не соответствуют требованиям валидации. Подробные требования к атрибутам описаны в request метода, включая типы, форматы и регулярные выражения. Необходимо скорректировать заполнение атрибутов и повторить запрос.
	Ошибка валидации запроса. Код ошибки: 428-001.	Проверьте данные запроса. Попробуйте скорректировать запрос и отправить его повторно.

• Модель
• Пример

Наименование	Тип	Обязательность	Описание
errorCode	string	optional	Код ошибки,
errorName	string	optional	Название ошибки,
errorDesc	string	optional	Описание ошибки.

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
 
{
    "errorCode": "428-001",
    "errorName": "VALIDATION_ERROR",
    "errorDesc": "Ошибка валидации запроса. Код ошибки: 428-001."
}

401 (Unauthorized Error)

Cause	Message	Description
UNAUTHORIZED	accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-х	Указан некорректный или просроченный access_token. Используйте refresh_token для обновления access_token и повторите запрос.

• Модель
• Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
 
{
    "cause": "UNAUTHORIZED",
    "referenceId": "014ec3a1-3e41-4805-9e22-d07947b012af",
    "message": "accessToken not found by value = 3513f959-bbd5-490a-9f9f-67fb7380fae5-2"
}

403 (Forbidden)

Cause	Message	Description
ACTION_ACCESS_EXCEPTION	Операция не может быть выполнена: доступ к ресурсу запрещен	Используемый в запросе access_token не имеет разрешения на доступ к нужному сервису Sber API. В ссылке авторизации СберБизнес ID, в параметре scope, не указана операция CORPORATE_CARDS. Необходимо добавить эту операцию в scope. Пользователю потребуется пройти авторизацию заново. Вы получите новые токены access_token и refresh_token. Сделайте повторный запрос с новым access_token.
		Вы использовали access_token пользователя вашей организации, а не Клиента. Нужно использовать access_token пользователя Клиента.

• Модель
• Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
 
{
    "cause": "ACTION_ACCESS_EXCEPTION",
    "referenceId": "7535c2bb-7706-4b16-9882-d68aedbf2fef",
    "message": "Операция не может быть выполнена: доступ к ресурсу запрещен"
}

429 (Too Many Requests)

Cause	Message	Description
TOO_MANY_REQUESTS	Превышен лимит запросов. Повторите операцию позже.	Количество запросов к данному методу за ограниченное время превысило допустимое значение. Пользователю необходимо повторить запрос позднее

• Модель
• Пример

Наименование	Тип	Обязательность	Описание
Notice{
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

json HTTP/1.1 429 Too Many Requests Content-Type: application/json;charset=UTF-8

{ "cause": " TOO_MANY_REQUESTS ", "referenceId": "5650c1e4-5039-4038-8cad-afab64003f61", "message": " Превышен лимит запросов. Повторите операцию позже" }

500 (Internal Server Error)

Cause	Message	Description
VALIDATION_ERROR	Ошибка валидации	Данные не соответствуют требованиям валидации. Подробные требования к атрибутам описаны в request метода, включая типы, форматы и регулярные выражения. Необходимо скорректировать заполнение атрибутов и повторить запрос.
	Попробуйте позднее. Код ошибки: 428-006 / 428-007 / 428-008 / 428-029.	Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.
	Ошибка валидации ответа. Код ошибки: 428-002.	Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.
	Ошибка валидации запроса. Код ошибки: 428-003.	Недопустимые символы в теле запроса - сработало правило детектирования SQL-иньекций.
	Ошибка валидации запроса. Код ошибки: 428-004.	Недопустимые символы в теле запроса - сработало правило детектирования lfI-атаки
GATEWAY_ERROR	Ошибка подключения к прокси-серверу.	Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.
	Попробуйте позднее. Код ошибки: 428-009 / 428-010.	Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.
CONTEXT_ERROR	Ошибка получения сессионных данных.	Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.
UNEXPECTED_SERVER_ERROR	Внутренняя ошибка сервера	Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.
	Непредвиденная ошибка. Код ошибки: 428-021.	Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.
FORBIDDEN_ERROR	Отсутствуют полномочия	Недостаточно полномочий для исполнения запроса.
	Нет полномочий. Код ошибки: 428-422.	Недостаточно полномочий для исполнения запроса.
	Попробуйте позднее. Код ошибки: 428-423 / 428-424 / 428-425.	Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.
INTEGRATION_ERROR	Интеграционная ошибка	Ошибка обращения к мастер-системе.
	Попробуйте позднее. Код ошибки: 428-426 / 428-427 / 428-428.	Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.

• Модель
• Пример

Наименование	Тип	Обязательность	Описание
errorCode	string	optional	Код ошибки,
errorName	string	optional	Название ошибки,
errorDesc	string	optional	Описание ошибки.

HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
 
{
    "errorCode": "428-459",
    "errorName": "BUSINESS_LOGIC_ERROR",
    "errorDesc": "Задан слишком большой период для выборки транзакций. Код ошибки: 428-459."
}

503 (Service Temporarily Unavailable)

Cause	Message	Description
UNAVAILABLE_RESOURCE_EXCEPTION	Внутренняя ошибка сервера	Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.

• Модель
• Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 503 Service Temporarily Unavailable
Content-Type: application/json;charset=UTF-8
 
{
  "cause": "UNAVAILABLE_RESOURCE_EXCEPTION",
  "referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a67d",
  "message": "Внутренняя ошибка сервера"
}