Инструменты страницы

Описание протокола взаимодействия с сервисом

Взаимодействие с сервисом происходит по протоколу REST.

Формат запроса

Запросы осуществляются посредством протокола HTTP 1.1 с использованием SSL (HTTPS), на адрес:

https://3dsec.sberbank.ru/sbersafe/<имя_метода>

Подробнее см. раздел Координаты подключения к сервису.

HTTP-запросы должны содержать заголовки. Состав представлен в таблице ниже.

Элемент заголовка и его значение Описание
POST /api/bindings/ HTTP/1.1 Тип взаимодействия с сервером, используемый запрос и версия протокола HTTP.
Host: 3dsec.sberbank.ru/sbersafe Сервер, на который направляется запрос.
Content-Type: application/json Тип содержимого.
Accept: application/json; version=1.0 Версия API.
Authorization: <access_token> Аутентификационный токен (подробнее см. раздел Аутентификация).

Каждый параметр указывается парой «ключ»:«значение» внутри документа JSON.

Должна использоваться кодировка UTF-8.

Ниже представлен пример запроса.

POST /api/bindings/ HTTP/1.1

Host: 3dsec.sberbank.ru/sbersafe

Content-Type: application/json

Accept: application/json; version=1.0

Authorization: 410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456

789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEF

GHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123


{

«phone»:«9997778866»

}

Требования безопасности

  • Все сетевые взаимодействия производятся только по HTTPS.
  • Приложение должно проверять корректность SSL-сертификата сервера. Если SSL-сертификат не прошел проверку, необходимо немедленно прекратить сеанс, чтобы не допустить утечку данных авторизации.
  • Не храните аутентификационный токен в открытом виде, в том числе в виде cookie-файлов.
  • Никогда не используйте аутентификационный токен в параметрах запросов POST.

Формат ответа

Ответ сервиса представляет собой JSON-документ в кодировке UTF-8 (см. The application/json Media Type for JavaScript Object Notation (JSON) и официальный сайт JSON - на английском языке).

В каждый ответе содержится уникальный requestId в формате UUID.

Содержимое документа зависит от результата выполнения запроса (см. пример ниже). 

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: <content-lenght>
Expires: Thu, 01 Dec 2018 16:00:00 GMT
Cache-Control: no-cache
{
  "response":{
    "param1":"value1",
    "param2":"value2"
  },
  "requestId":"requestId uuid",
  "status":"SUCCESS"
}

В ответе могут также присутствовать поля, не описанные в настоящем документе. Они должны быть проигнорированы.

При отказе в авторизации сервер отвечает HTTP-кодом 4xx. Возможные причины отказа:

  • запрос невозможно разобрать;
  • в запросе отсутствует HTTP-заголовок Authorization (подробнее см. раздел Аутентификация);
  • в заголовке Authorization указан несуществующий, некорректный или просроченный токен (подробнее см. раздел Аутентификация);
  • запрошена операция, на которую у токена нет прав.

Ответ содержит заголовок WWW-Authenticate (согласно стандарту The OAuth 2.0 Authorization Framework: Bearer Token Usage - на английском языке).

При отказе по запросу в ответе присутствуют следующие поля:

Поле Описание Пример
code

Короткий код ошибки. Можно использовать для автоматической обработки. Для всех ошибок разработки, таких как неверный формат входного поля, несуществующий идентификатор объекта и т. п. следует использовать один код, например, inernalError.

expiredCard
description Описание ошибки своими английскими словами. Не для автоматической обработки, а для отладки и в помощь разработчику. Required field 'pan' is empty
message Сообщение для отображения пользователю. Ваша карта просрочена

Коды причины отказа операции:

HTTP-код ответа Значение поля error_code Описание
400 invalidRequest Формат HTTP-запроса не соответствует протоколу. Запрос невозможно разобрать, либо заголовок Authorization отсутствует, либо имеет некорректное значение.
429 tooManyRequests Сервер перегружен повторите позже.

Ниже представлен пример ответа с сообщением об ошибке. 

HTTP/1.1 400 Bad Request
WWW-Authenticate: error="invalidRequest", error_description="Invalid request", error_message=""
{
  "error": {
    "code":"general.error",
    "description":"Some error occurrend in Java",
    "message":"Внутренняя ошибка"
  },
  "requestId":"gbhjnkme-rdcfgv-hbjnkm-7689ui-okp3ew",
  "status":"FAIL"
}

Типы данных

Тип данных протокола Соответствующий тип JSON Описание
string string Текстовая строка в кодировке UTF-8.
amount number Сумма. Число с фиксированной точкой, две цифры после точки.
boolean boolean Логическое значение: true, false.
int number 32-битное знаковое целое число.
long number 64-битное знаковое целое число.
object object Вложенный объект JSON.
array array Массив объектов JSON.
datetime string Временная метка согласно стандарту RFC3339 в следующем формате yyyy-MM-dd'T'HH:mm:ssZZ (см. расшифровку ниже).

Расшифровка формата datetime:

  • YYYY - год, всегда 4 цифры;
  • MM - месяц, всегда 2 цифры (например, 01=Январь);
  • DD - день месяца, точно 2 цифры (от 01 до 31);
  • T - латинский символ «T» в верхнем регистре;
  • hh - часы, всегда 2 цифры (24-часовой формат, от 00 до 23);
  • mm - минуты, всегда 2 цифры (от 00 до 59);
  • ss - секунды, всегда 2 цифры (от 00 до 59);
  • ZZ - Описатель временной зоны, обязательный параметр. Может принимать значения:
    • Z – UTC, символ «Z» в верхнем регистре;
    • +hh или -hh – смещение относительно UTC (показывает, что указано локальное время, которое опережает или отстает от UTC на указанное число часов и минут).

2012-01-31T12:00:00Z
или
2018-07-21T19:30:45+04:00 — 19 часов 30 минут 45 секунд 21 июля 2018 года, часовой пояс Europe/Moscow (UTC+04:00)