1 Использование API
2 Транспорт и протокол
3 Общие положения
4 Коды ответа
5 Коды ошибок и их описание
- 5.1 Объект ошибки
6 Создание мерчанта
- 6.1 Формат запроса
- 6.2 Формат ответа
7 Верификация пользователя
- 7.1 Формат запроса
- 7.2 Формат ответа
8 Повторная отправка СМС
- 8.1 Формат запроса
- 8.2 Формат ответа
9 Проверка статуса мерчанта
- 9.1 Формат запроса
- 9.2 Формат ответа
10 Аутентификация
- 10.1 Формат запроса
- 10.2 Формат ответа
11 Получение списка юридических лиц
- 11.1 Формат запроса
- 11.2 Формат ответа
12 Получение информации по юридическому лицу
- 12.1 Формат запроса
- 12.2 Формат ответа
13 Получение информации по банковским реквизитам
- 13.1 Формат запроса
- 13.2 Формат ответа
14 Создание магазина мерчанта
- 14.1 Формат запроса
- 14.2 Формат ответа
15 Обновление магазина мерчанта
- 15.1 Формат запроса
- 15.2 Формат ответа
16 Удаление магазина мерчанта
- 16.1 Формат запроса
- 16.2 Формат ответа
17 Получение списка магазинов
- 17.1 Формат запроса
- 17.2 Формат ответа

Использование API

Для начала работы с маркетинговым движком необходимо пройти регистрацию. В системе SWiP есть сущности merchantUser (представитель мерчанта) и merchant (торгово-сервисное предприятие).

При регистрации через веб-панель создание этих сущностей происходит по отдельности. Сначала представитель мерчанта регистрируется как пользователь, дальше пользователь регистрирует мерчанта.

При регистрации через API создание сущностей происходит в одно действие.

Для защиты от возможных атак добавлена верификация через СМС. После создания мерчанта необходимо смотреть на его статус, поскольку в функциональности верификации может не быть необходимости. При статусе мерчанта VERIFY требуется верификация.

Транспорт и протокол

В качестве транспорта используется HTTPS протокол. Сообщения представлены в JSON формате.

Общие положения

Для выполнения большинства запросов необходима аутентификация. Запрос должен содержать заголовок X-Auth-Token, значением которого является JWT-токен.

Название поля	Пример значения	Описание

Название поля	Пример значения	Описание
X-Auth-Token	eyJhbGciOiJIUzUxMM....9rZ8VQ54JqWFe1Q	Токен приходит после регистрации.

Коды ответа

HTTP-код	Описание	Код ошибки

HTTP-код	Описание	Код ошибки
200	Успешный запрос.
201	Пользователь успешно создан.	created
400	Неправильный запрос из-за нарушения правил взаимодействия с API.	bad_request
401	Неудачная авторизация.	unauthorized
403	Доступ запрещен.	forbidden
404	Ресурс по указанному id не был найден в системе SWiP.	not_found
405	Используется запрещенный или неподдерживаемый метод.	method_not_allowed
429	Отправлено слишком много запросов за короткий промежуток времени.	too_many_request
500	Внутренняя ошибка сервера.	internal_server_error

Коды ошибок и их описание

Код ошибки	Описание

Код ошибки	Описание
1	INTERNAL SERVER ERROR Внутренняя ошибка сервера.
2	AUTHENTICATION ERROR Неудачная аутентификация.
4	ACCESS DENIED Доступ запрещен.
5	VALIDATION FAILED Некорректная валидация.
6	ILLEGAL STATE Ошибка неправильного состояния текущей операции.
7	METHOD NOT SUPPORTED Метод не поддерживается.
8	DUPLICATE Дублицирование данных.
9	NOT FOUND Ресурс не найден.
10	UNSUPPORTED MESSAGE Неподдерживаемое сообщение.
11	ORDER FLOW VIOLATION Нарушение процесса обработки заказа.
12	SMS CODE EXPIRED Истек срок действия СМС-кода.
13	OPERATION TIMED OUT Истекло время ожидания операции.
14	DOESNT MATCH Несовпадение данных.
15	PAYMENTS BLOCKED Платежи заблокированы.
16	TOKEN EXPIRED Истек срок действия JWT токена.
17	JWT TOKEN ERROR Ошибка процессинга токена.
18	CONCURRENT PAYMENT ERROR Ошибка из-за осуществления параллельных платежей.
19	BANK PAYMENT ERROR Ошибка оплаты банка.
21	ACCOUNTING ERROR Ошибка в расчетах.
22	REQUEST LIMIT EXCEEDED Превышен лимит количества запросов.
23	EXTERNAL SYSTEM ERROR Внешняя ошибка системы.
25	OPERATION IN PROGRESS Операция находится в процессе выполнения.

Объект ошибки

Если при выполнении запроса произошла ошибка, вернется следующий объект:

{
  "code": 0,                        // код внутренней ошибки SWiP
  "description": "string",          // описание ошибки
  "fieldErrors": [                  // массив объектов с детальным описанием
    {
      "field": "string",            // поле, в котором произошла ошибка
      "message": "string",          // детали ошибки
      "objectName": "string"        // класс объекта, у которого произошла ошибка
    }
  ]
}

Создание мерчанта

Чтобы зарегистрировать новый магазин в системе SWiP, необходимо создать объект мерчанта. Результатом обработки запроса является создание мерчанта и передача его реквизитов.

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

POST /merchant-user-signups

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

Параметр	Тип	Описание	Формат

Параметр	Тип	Описание	Формат
`legalPerson`	array	Список юридических лиц.	Ненулевое значение, в массиве должен быть минимум 1 объект.
`bankDetails`	array	Банковские реквизиты.	Ненулевое значение, в массиве должен быть минимум 1 объект.
`accountsName`	string	Название счёта.	Строка длиной от 1 до 100 символов.
`bank`	string	Название банка.	Строка длиной от 1 до 100 символов.
`bik`	string	БИК.	Строка длиной 9 цифр.
`checkingAccount`	string	Текущий счет.	Строка длиной от 1 до 100 символов.
`correspondentAccount`	string	Корреспондентский счет.	Строка длиной от 1 до 100 символов.
`default`	boolean	Использование счета по умолчанию (необходим при указании нескольких счетов).
`inn`	string	ИНН.	Строка длиной 10 или 12 цифр.
`mainAccount`	string	Главный счёт.	Строка длиной от 1 до 100 символов.
`corporateInformation`	array	Информация о компании.	Ненулевое значение, в массиве должен быть минимум 1 объект.
`ceoName`	string	Имя руководителя компании.	Строка длиной от 1 до 100 символов.
`employeesCount`	integer	Количество сотрудников	Длина от 1 до 100 символов.
`inn`	string	ИНН компании.	Строка длиной 10 или 12 цифр.
`kpp`	string	КПП.	Строка длиной 9 цифр.
`ogrn`	string	ОГРН.	Строка длиной 13 цифр.
`okpo`	string	ОКПО.	Строка длиной 8 или 10 цифр.
`okwed`	string	ОКВЭД.	Строка длиной от 1 до 100 символов.
`registrationDate`	string	Дата регистрации.	Дата в формате ISO 8601.
`customerInformation`	array	Информация о мерчанте.	Ненулевое значение, в массиве должен быть минимум 1 объект.
`аctualAddress`	string	Фактический адрес.	Строка длиной от 1 до 100 символов.
`address`	string	Адрес.	Строка длиной от 1 до 100 символов.
`cashboxProvider`	string	Поставщик кассы.	Строка длиной от 1 до 100 символов.
`cashboxType`	string	Тип кассы.	Строка длиной от 1 до 100 символов.
`email`	string	Электронный адрес.	Валидный e-mail.
`name`	string	Имя юридического лица.	Строка длиной от 1 до 100 символов.
`phone`	string	Телефон.	Телефон в формате "+7ХХХХХХХХХХ", "7ХХХХХХХХХХ", "8ХХХХХХХХХХ".
`postalAddress`	string	Почтовый адрес.	Строка длиной от 1 до 100 символов.
`merchantName`	string	Название мерчанта.	Строка длиной от 2 до 60 символов.
`password`	string	Пароль, необходимый для входа в маркетинговый движок.	Строка длиной от 4 символов.
`phone`	string	Номер телефона.	Телефон в формате "+7ХХХХХХХХХХ", "7ХХХХХХХХХХ", "8ХХХХХХХХХХ".
`username`	string	Имя пользователя. Используется e-mail.	Валидный e-mail.

Пример тела запроса

{
  "legalPersons": [                           // список юридических лиц
    {
      "bankDetails": [                        // список банковских счетов
        {
          "accountsName": "string",
          "bank": "string",
          "bik": "string",
          "checkingAccount": "string",
          "correspondentAccount": "string",
          "default": true,
          "inn": "string",
          "mainAccount": "string"
        }
      ],
      "corporateInformation": {
        "ceoName": "string",
        "employeesCount": 0,
        "inn": "string",
        "kpp": "string",
        "ogrn": "string",
        "okpo": "string",
        "okwed": "string",
        "registrationDate": "2019-05-13T11:33:42.007Z"
      },
      "customerInformation": {
        "actualAddress": "string",
        "address": "string",
        "cashboxProvider": "string",
        "cashboxType": "string",
        "email": "string",
        "name": "string",
        "phone": "string",
        "postalAddress": "string"
      },
      "products": [
        "string"
      ]
    }
  ],
  "merchantName": "Name",
  "password": "supersecret",
  "phone": "79160000000",                   // номер телефона в виде 11 цифр
  "username": "test@email.email"
}

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

В ответ на запрос придет идентификатор мерчанта и идентификатор пользователя мерчанта в системе SWiP, статус мерчанта и токен, необходимый для авторизации.

Пример тела ответа

{ 
  "merchantId": "ABCD",                 // id мерчанта в системе SWiP
  "merchantUserId": "string",           // id пользователя мерчанта в системе SWiP
  "status": "NEW",                      // статус мерчанта 
  "token": "string"                     // токен, который будет дальше использоваться для авторизации доступа к сервисам SWiP
}

Поле status может принимать следующие значения:

Значение	Описание

Значение	Описание
`VERIFY`	Необходимо подтвердить учетную запись кодом из СМС.
`NEW`	Мерчант создан, ожидается проверка на стороне SWiP.
`ACTIVE`	Мерчант проверен и активирован, можно принимать оплату.

Верификация пользователя

Вызывает метод верификации пользователя. Необходим, если при создании мерчанта пришел статус VERIFY.

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

POST /merchant-user-verifications

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

Параметр	Тип	Описание

Параметр	Тип	Описание
`code`	string, обязательный	Код из СМС.
`deviceId`	string, обязательный	Идентификатор устройства.
`email`	string, обязательный	Электронный адрес мерчанта.
`mobilePhone`	string, обязательный	Мобильный телефон, указанный при регистрации.

Пример тела запроса

{
  "code": "666666",                   // код из СМС
  "deviceId": "string",               // идентификатор устройства
  "email": "test@email.email",        // электронный адрес мерчанта
  "mobilePhone": "79160000000"        // номер телефона в виде 11-ти цифр
}

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

Если данные прошли проверку, то придет успешный ответ.

Пример тела ответа

{ "verified": true }

В случае неподтверждения данных, придет ответ с ошибкой.

Пример тела ответа

{
  "code":9,                                             // код ошибки
  "description":"Sms code[666666] not found",           // текстовое описание ошибки	
  "fieldErrors":null							
}

Повторная отправка СМС

Запрашивает метод для повторной отправки СМС. Необходим, если на мобильный телефон не пришло сообщение с кодом для верификации пользователя.

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

PUT /merchant-user-verifications

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

Параметр	Тип	Описание

Параметр	Тип	Описание
`merchantUserId`	string, обязательный	Идентификатор пользователя мерчанта.

Пример тела запроса

1
2
3

{
  "merchantUserId": "test@mail.ru"
}

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

Если СМС было отправлено, придет успешный ответ.

Пример тела ответа

{ "sent": true }

Проверка статуса мерчанта

Запрашивает статус мерчанта на сервере SWiP.

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

GET /merchants/{merchantId}/status

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

Параметр	Тип	Описание

Параметр	Тип	Описание
`merchantId`	string, обязательный	Уникальный идентификатор мерчанта. Присваивается после регистрации.

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

В ответе вернется статус мерчанта. Поле может принимать следующие значения:

Значение	Описание

Значение	Описание
`VERIFY`	Необходимо подтвердить учетную запись кодом из СМС.
`NEW`	Мерчант создан, ожидается проверка на стороне SWiP.
`ACTIVE`	Мерчант проверен и активирован, можно принимать оплату.

Пример тела ответа

{ "status": ACTIVE }

Если мерчант по указанному ID не был найден, придет ответ с ошибкой.

Пример тела ответа

{
  "code": 9,                                            // код ошибки
  "description": "Merchant[mercantId] not found",       // текстовое описание ошибки
  "fieldErrors": null
}

Аутентификация

Аутентификация необходима после истечения срока действия токена. Токен действителен в течение 1 часа.

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

POST /auth

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

Параметр	Тип	Описание

Параметр	Тип	Описание
`password`	string, обязательный	Пароль, необходимый для входа в маркетинговый движок.
`username`	string, обязательный	Имя пользователя.

Пример тела запроса

{
  "password": "string",
  "username": "string"
}

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

В ответ на запрос приходит следующий объект.

Пример тела ответа

{
  "refreshPeriod": 0,
  "refreshToken": "string",
  "token": "string"
}

Получение списка юридических лиц

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

GET /legal-entities

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

В ответ приходит список юридических лиц мерчанта с полной информацией о них.

Пример тела ответа

[
  {
    "bankDetails": [
      {
        "accountsName": "string",
        "bank": "string",
        "bik": "string",
        "checkingAccount": "string",
        "correspondentAccount": "string",
        "default": true,
        "id": "string",
        "inn": "string",
        "mainAccount": "string"
      }
    ],
    "corporateInformation": {
      "ceoName": "string",
      "employeesCount": 0,
      "inn": "string",
      "kpp": "string",
      "ogrn": "string",
      "okpo": "string",
      "okwed": "string",
      "registrationDate": "2019-01-14T20:24:28.483Z"
    },
    "customerInformation": {
      "actualAddress": "string",
      "address": "string",
      "cashboxProvider": "string",
      "cashboxType": "string",
      "email": "string",
      "name": "string",
      "phone": "string",
      "postalAddress": "string"
    },
    "merchantName": "string",
    "personId": "string",
    "products": [
      "string"
    ],
    "status": "NEW"
  }
]

Получение информации по юридическому лицу

Запрос позволяет получить информацию о юридическом лице по его уникальному идентификатору.

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

GET /legal-entities/{personId}

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

Параметр	Тип	Описание

Параметр	Тип	Описание
`personId`	string, обязательный	Уникальный идентификатор юридического лица в системе SWiP.

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

В ответ приходит объект с информацией о юридическом лице.

Пример тела ответа

{
    "bankDetails": [
      {
        "accountsName": "string",
        "bank": "string",
        "bik": "string",
        "checkingAccount": "string",
        "correspondentAccount": "string",
        "default": true,
        "id": "string",
        "inn": "string",
        "mainAccount": "string"
      }
    ],
    "corporateInformation": {
      "ceoName": "string",
      "employeesCount": 0,
      "inn": "string",
      "kpp": "string",
      "ogrn": "string",
      "okpo": "string",
      "okwed": "string",
      "registrationDate": "2019-01-14T20:24:28.483Z"
    },
    "customerInformation": {
      "actualAddress": "string",
      "address": "string",
      "cashboxProvider": "string",
      "cashboxType": "string",
      "email": "string",
      "name": "string",
      "phone": "string",
      "postalAddress": "string"
    },
    "merchantName": "string",
    "personId": "string",
    "products": [
      "string"
    ],
    "status": "NEW"
  }

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

Запрос позволяет получить информацию о банковских реквизитах по уникальному идентификатору юридического лица.

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

GET /legal-entities/{personId}/bank-details/{bankDetailId}

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

Параметр	Тип	Описание

Параметр	Тип	Описание
`personId`	string, обязательный	Уникальный идентификатор юридического лица в системе SWiP.
`bankDetailId`	string, обязательный	Уникальный идентификатор банковских реквизитов в системе SWiP.

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

В ответ на запрос приходит список объектов с информацией о банковских реквизитах.

Пример тела ответа

{
  "accountsName": "string",
  "bank": "string",
  "bik": "string",
  "checkingAccount": "string",
  "correspondentAccount": "string",
  "default": true,
  "id": "string",
  "inn": "string",
  "mainAccount": "string"
}

Создание магазина мерчанта

Чтобы провести оплату для определенной торговой точки мерчанта, надо создать объект торговой точки - MerchantStore. Он содержит информацию о магазине и его прикреплении к юридическому лицу и банковскому счету.

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

POST /stores

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

Параметр	Тип	Описание

Параметр	Тип	Описание
`name`	string, обязательный	Название торговой точки.
`bankAccount`	UUID, обязательный	Идентификатор банковского счета, к которому привязан магазин в системе SWiP.
`address`	string, необязательный	Адрес торговой точки.
`phone`	string, необязательный	Номер телефона торговой точки.
`description`	string, необязательный	Описание деятельности торговой точки.
`latitude`	string, необязательный	Координаты широты месторасположения торговой точки.
`longitude`	string, необязательный	Координаты долготы месторасположения торговой точки.
`monFri`	string, необязательный	Рабочие часы с ПН по ПТ.
`satSun`	string, необязательный	Рабочие часы с СБ по ВС.

Пример тела запроса

{
  "name": "string",
  "bankAccount": "string",
  "address": "string",			
  "description": "string",
  "latitude": 0,
  "longitude": 0,
  "phone": "string",
  "monFri": "string",
  "satSun": "string",
}

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

В ответ на запрос приходит идентификатор магазина в системе SWiP.

Пример тела ответа

{"merchantStoreId":"string"}

Обновление магазина мерчанта

Запрос необходим для редактирования текущей информации о магазине.

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

PUT /stores/{id}

Для обновления информации о торговой точке мерчанта необходимо отправить запрос с передачей следующих параметров:

Параметр	Тип	Описание

Параметр	Тип	Описание
`id`	string, обязательный	Уникальный идентификатор торговой точки в системе SWiP.
`name`	string, обязательный	Название торговой точки.
`bankAccount`	UUID, обязательный	Идентификатор банковского счета, к которому привязан магазин в системе SWiP.
`address`	string, необязательный	Адрес торговой точки.
`description`	string, необязательный	Описание деятельности торговой точки.
`latitude`	double, необязательный	Координаты широты месторасположения торговой точки.
`longitude`	double, необязательный	Координаты долготы месторасположения торговой точки.
`phone`	string, необязательный	Номер телефона торговой точки.
`monFri`	string, необязательный	Рабочие часы с ПН по ПТ.
`satSun`	string, необязательный	Рабочие часы с СБ по ВС.

Пример тела запроса

{
  "name": "string",
  "bankAccount": "string",
  "address": "string",			
  "description": "string",
  "latitude": 0,
  "longitude": 0,
  "phone": "string",
  "monFri": "string",
  "satSun": "string",
}

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

В ответ на запрос приходит объект MerchantStore с отредактированной информацией.

Пример тела ответа

{
  "name": "string",
  "bankAccount": "string",
  "address": "string",			
  "description": "string",
  "latitude": 0,
  "longitude": 0,
  "phone": "string",
  "monFri": "string",
  "satSun": "string",
}

Удаление магазина мерчанта

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

DELETE /stores/{id}

Если для данного магазина запущены активные кэшбэк кампании, то его удаление из системы невозможно.

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

Параметр	Тип	Описание

Параметр	Тип	Описание
`id`	string, обязательный	Идентификатор магазина в системе SWiP.

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

В ответ на запрос приходит идентификатор магазина.

Пример тела ответа

{"merchantStoreId":"string"}

Получение списка магазинов

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

GET /stores

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

В ответ приходит список магазинов мерчанта с полной информацией о них.

Пример тела ответа

[
  {
    "id": "string",
    "name": "string",
    "bankAccount": "string",
    "address": "string",			
    "description": "string",
    "latitude": 0,
    "longitude": 0,
    "phone": "string",
    "monFri": "string",
    "satSun": "string",
   }
]

API регистрации

Использование API

Транспорт и протокол

Общие положения

Коды ответа

Коды ошибок и их описание

Объект ошибки

Создание мерчанта

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

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

Верификация пользователя

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

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

Повторная отправка СМС

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

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

Проверка статуса мерчанта

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

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

Аутентификация

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

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

Получение списка юридических лиц

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

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

Получение информации по юридическому лицу

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

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

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

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

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

Создание магазина мерчанта

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

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

Обновление магазина мерчанта

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

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

Удаление магазина мерчанта

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

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

Получение списка магазинов

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

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