API регистрации
- 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 | Токен приходит после регистрации. |
Коды ответа
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 |
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 |
Объект ошибки
Если при выполнении запроса произошла ошибка, вернется следующий объект:
1
2
3
4
5
6
7
8
9
10
11
{
"code": 0, // код внутренней ошибки SWiP
"description": "string", // описание ошибки
"fieldErrors": [ // массив объектов с детальным описанием
{
"field": "string", // поле, в котором произошла ошибка
"message": "string", // детали ошибки
"objectName": "string" // класс объекта, у которого произошла ошибка
}
]
}
Создание мерчанта
Чтобы зарегистрировать новый магазин в системе SWiP, необходимо создать объект мерчанта. Результатом обработки запроса является создание мерчанта и передача его реквизитов.
Формат запроса
1
POST /merchant-user-signups
Для создания мерчанта необходимо отправить запрос с передачей следующих параметров:
| array | Список юридических лиц. | Ненулевое значение, в массиве должен быть минимум 1 объект. |
| array | Банковские реквизиты. | Ненулевое значение, в массиве должен быть минимум 1 объект. |
| string | Название счёта. | Строка длиной от 1 до 100 символов. |
| string | Название банка. | Строка длиной от 1 до 100 символов. |
| string | БИК. | Строка длиной 9 цифр. |
| string | Текущий счет. | Строка длиной от 1 до 100 символов. |
| string | Корреспондентский счет. | Строка длиной от 1 до 100 символов. |
| boolean | Использование счета по умолчанию (необходим при указании нескольких счетов). | |
| string | ИНН. | Строка длиной 10 или 12 цифр. |
| string | Главный счёт. | Строка длиной от 1 до 100 символов. |
| array | Информация о компании. | Ненулевое значение, в массиве должен быть минимум 1 объект. |
| string | Имя руководителя компании. | Строка длиной от 1 до 100 символов. |
| integer | Количество сотрудников | Длина от 1 до 100 символов. |
| string | ИНН компании. | Строка длиной 10 или 12 цифр. |
| string | КПП. | Строка длиной 9 цифр. |
| string | ОГРН. | Строка длиной 13 цифр. |
| string | ОКПО. | Строка длиной 8 или 10 цифр. |
| string | ОКВЭД. | Строка длиной от 1 до 100 символов. |
| string | Дата регистрации. | Дата в формате ISO 8601. |
| array | Информация о мерчанте. | Ненулевое значение, в массиве должен быть минимум 1 объект. |
| string | Фактический адрес. | Строка длиной от 1 до 100 символов. |
| string | Адрес. | Строка длиной от 1 до 100 символов. |
| string | Поставщик кассы. | Строка длиной от 1 до 100 символов. |
| string | Тип кассы. | Строка длиной от 1 до 100 символов. |
| string | Электронный адрес. | Валидный e-mail. |
| string | Имя юридического лица. | Строка длиной от 1 до 100 символов. |
| string | Телефон. | Телефон в формате "+7ХХХХХХХХХХ", "7ХХХХХХХХХХ", "8ХХХХХХХХХХ". |
| string | Почтовый адрес. | Строка длиной от 1 до 100 символов. |
| string | Название мерчанта. | Строка длиной от 2 до 60 символов. |
| string | Пароль, необходимый для входа в маркетинговый движок. | Строка длиной от 4 символов. |
| string | Номер телефона. | Телефон в формате "+7ХХХХХХХХХХ", "7ХХХХХХХХХХ", "8ХХХХХХХХХХ". |
| string | Имя пользователя. Используется e-mail. | Валидный e-mail. |
Пример тела запроса
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
{
"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, статус мерчанта и токен, необходимый для авторизации.
Пример тела ответа
1
2
3
4
5
6
{
"merchantId": "ABCD", // id мерчанта в системе SWiP
"merchantUserId": "string", // id пользователя мерчанта в системе SWiP
"status": "NEW", // статус мерчанта
"token": "string" // токен, который будет дальше использоваться для авторизации доступа к сервисам SWiP
}
Поле status
может принимать следующие значения:
| Необходимо подтвердить учетную запись кодом из СМС. |
| Мерчант создан, ожидается проверка на стороне SWiP. |
| Мерчант проверен и активирован, можно принимать оплату. |
Верификация пользователя
Вызывает метод верификации пользователя. Необходим, если при создании мерчанта пришел статус VERIFY.
Формат запроса
1
POST /merchant-user-verifications
Для верификации пользователя необходимо отправить запрос с передачей следующих параметров:
| string, обязательный | Код из СМС. |
| string, обязательный | Идентификатор устройства. |
| string, обязательный | Электронный адрес мерчанта. |
| string, обязательный | Мобильный телефон, указанный при регистрации. |
Пример тела запроса
1
2
3
4
5
6
{
"code": "666666", // код из СМС
"deviceId": "string", // идентификатор устройства
"email": "test@email.email", // электронный адрес мерчанта
"mobilePhone": "79160000000" // номер телефона в виде 11-ти цифр
}
Формат ответа
Если данные прошли проверку, то придет успешный ответ.
Пример тела ответа
1
{ "verified": true }
В случае неподтверждения данных, придет ответ с ошибкой.
Пример тела ответа
1
2
3
4
5
{
"code":9, // код ошибки
"description":"Sms code[666666] not found", // текстовое описание ошибки
"fieldErrors":null
}
Повторная отправка СМС
Запрашивает метод для повторной отправки СМС. Необходим, если на мобильный телефон не пришло сообщение с кодом для верификации пользователя.
Формат запроса
1
PUT /merchant-user-verifications
Для повторной отправки СМС необходимо послать запрос с передачей следующих параметров:
| string, обязательный | Идентификатор пользователя мерчанта. |
Пример тела запроса
1
2
3
{
"merchantUserId": "test@mail.ru"
}
Формат ответа
Если СМС было отправлено, придет успешный ответ.
Пример тела ответа
1
{ "sent": true }
Проверка статуса мерчанта
Запрашивает статус мерчанта на сервере SWiP.
Формат запроса
1
GET /merchants/{merchantId}/status
Для проверки статуса мерчанта необходимо отправить запрос с передачей следующих параметров:
| string, обязательный | Уникальный идентификатор мерчанта. Присваивается после |
Формат ответа
В ответе вернется статус мерчанта. Поле может принимать следующие значения:
| Необходимо подтвердить учетную запись кодом из СМС. |
| Мерчант создан, ожидается проверка на стороне SWiP. |
| Мерчант проверен и активирован, можно принимать оплату. |
Пример тела ответа
1
{ "status": ACTIVE }
Если мерчант по указанному ID не был найден, придет ответ с ошибкой.
Пример тела ответа
1
2
3
4
5
{
"code": 9, // код ошибки
"description": "Merchant[mercantId] not found", // текстовое описание ошибки
"fieldErrors": null
}
Аутентификация
Аутентификация необходима после истечения срока действия токена. Токен действителен в течение 1 часа.
Формат запроса
1
POST /auth
Для получения токена необходимо отправить запрос с передачей следующих параметров:
| string, обязательный | Пароль, необходимый для входа в маркетинговый движок. |
| string, обязательный | Имя пользователя. |
Пример тела запроса
1
2
3
4
{
"password": "string",
"username": "string"
}
Формат ответа
В ответ на запрос приходит следующий объект.
Пример тела ответа
1
2
3
4
5
{
"refreshPeriod": 0,
"refreshToken": "string",
"token": "string"
}
Получение списка юридических лиц
Формат запроса
1
GET /legal-entities
Формат ответа
В ответ приходит список юридических лиц мерчанта с полной информацией о них.
Пример тела ответа
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
[
{
"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"
}
]
Получение информации по юридическому лицу
Запрос позволяет получить информацию о юридическом лице по его уникальному идентификатору.
Формат запроса
1
GET /legal-entities/{personId}
Для получения информации по юридическому лицу необходимо отправить запрос с передачей следующих параметров:
| string, обязательный | Уникальный идентификатор юридического лица в системе SWiP. |
Формат ответа
В ответ приходит объект с информацией о юридическом лице.
Пример тела ответа
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
{
"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"
}
Получение информации по банковским реквизитам
Запрос позволяет получить информацию о банковских реквизитах по уникальному идентификатору юридического лица.
Формат запроса
1
GET /legal-entities/{personId}/bank-details/{bankDetailId}
Для получения информации по банковским реквизитам необходимо отправить запрос с передачей следующих параметров:
| string, обязательный | Уникальный идентификатор юридического лица в системе SWiP. |
| string, обязательный | Уникальный идентификатор банковских реквизитов в системе SWiP. |
Формат ответа
В ответ на запрос приходит список объектов с информацией о банковских реквизитах.
Пример тела ответа
1
2
3
4
5
6
7
8
9
10
11
{
"accountsName": "string",
"bank": "string",
"bik": "string",
"checkingAccount": "string",
"correspondentAccount": "string",
"default": true,
"id": "string",
"inn": "string",
"mainAccount": "string"
}
Создание магазина мерчанта
Чтобы провести оплату для определенной торговой точки мерчанта, надо создать объект торговой точки - MerchantStore. Он содержит информацию о магазине и его прикреплении к юридическому лицу и банковскому счету.
Формат запроса
1
POST /stores
Для создания торговой точки мерчанта необходимо отправить запрос с передачей следующих параметров:
| string, обязательный | Название торговой точки. |
| UUID, обязательный | Идентификатор банковского счета, к которому привязан магазин в системе SWiP. |
| string, необязательный | Адрес торговой точки. |
| string, необязательный | Номер телефона торговой точки. |
| string, необязательный | Описание деятельности торговой точки. |
| string, необязательный | Координаты широты месторасположения торговой точки. |
| string, необязательный | Координаты долготы месторасположения торговой точки. |
| string, необязательный | Рабочие часы с ПН по ПТ. |
| string, необязательный | Рабочие часы с СБ по ВС. |
Пример тела запроса
1
2
3
4
5
6
7
8
9
10
11
{
"name": "string",
"bankAccount": "string",
"address": "string",
"description": "string",
"latitude": 0,
"longitude": 0,
"phone": "string",
"monFri": "string",
"satSun": "string",
}
Формат ответа
В ответ на запрос приходит идентификатор магазина в системе SWiP.
Пример тела ответа
1
{"merchantStoreId":"string"}
Обновление магазина мерчанта
Запрос необходим для редактирования текущей информации о магазине.
Формат запроса
1
PUT /stores/{id}
Для обновления информации о торговой точке мерчанта необходимо отправить запрос с передачей следующих параметров:
| string, обязательный | Уникальный идентификатор торговой точки в системе SWiP. |
| string, обязательный | Название торговой точки. |
| UUID, обязательный | Идентификатор банковского счета, к которому привязан магазин в системе SWiP. |
| string, необязательный | Адрес торговой точки. |
| string, необязательный | Описание деятельности торговой точки. |
| double, необязательный | Координаты широты месторасположения торговой точки. |
| double, необязательный | Координаты долготы месторасположения торговой точки. |
| string, необязательный | Номер телефона торговой точки. |
| string, необязательный | Рабочие часы с ПН по ПТ. |
| string, необязательный | Рабочие часы с СБ по ВС. |
Пример тела запроса
1
2
3
4
5
6
7
8
9
10
11
{
"name": "string",
"bankAccount": "string",
"address": "string",
"description": "string",
"latitude": 0,
"longitude": 0,
"phone": "string",
"monFri": "string",
"satSun": "string",
}
Формат ответа
В ответ на запрос приходит объект MerchantStore с отредактированной информацией.
Пример тела ответа
1
2
3
4
5
6
7
8
9
10
11
{
"name": "string",
"bankAccount": "string",
"address": "string",
"description": "string",
"latitude": 0,
"longitude": 0,
"phone": "string",
"monFri": "string",
"satSun": "string",
}
Удаление магазина мерчанта
Формат запроса
1
DELETE /stores/{id}
Если для данного магазина запущены активные кэшбэк кампании, то его удаление из системы невозможно.
Для удаления магазина мерчанта необходимо отправить запрос с передачей следующих параметров:
| string, обязательный | Идентификатор магазина в системе SWiP. |
Формат ответа
В ответ на запрос приходит идентификатор магазина.
Пример тела ответа
1
{"merchantStoreId":"string"}
Получение списка магазинов
Формат запроса
1
GET /stores
Формат ответа
В ответ приходит список магазинов мерчанта с полной информацией о них.
Пример тела ответа
1
2
3
4
5
6
7
8
9
10
11
12
13
14
[
{
"id": "string",
"name": "string",
"bankAccount": "string",
"address": "string",
"description": "string",
"latitude": 0,
"longitude": 0,
"phone": "string",
"monFri": "string",
"satSun": "string",
}
]