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

Использование 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
Операция находится в процессе выполнения.

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

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

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

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

Параметр

Тип

Описание

Формат

Параметр

Тип

Описание

Формат

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.

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

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 может принимать следующие значения:

Значение

Описание

Значение

Описание

VERIFY

Необходимо подтвердить учетную запись кодом из СМС.

NEW

Мерчант создан, ожидается проверка на стороне SWiP.

ACTIVE

Мерчант проверен и активирован, можно принимать оплату.

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

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

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

1 POST /merchant-user-verifications

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

Параметр

Тип

Описание

Параметр

Тип

Описание

code

string, обязательный

Код из СМС.

deviceId

string, обязательный

Идентификатор устройства.

email

string, обязательный

Электронный адрес мерчанта.

mobilePhone

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

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

Параметр

Тип

Описание

Параметр

Тип

Описание

merchantUserId

string, обязательный

Идентификатор пользователя мерчанта.

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

1 2 3 { "merchantUserId": "test@mail.ru" }

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

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

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

1 { "sent": true }

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

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

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

1 GET /merchants/{merchantId}/status

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

Параметр

Тип

Описание

Параметр

Тип

Описание

merchantId

string, обязательный

Уникальный идентификатор мерчанта. Присваивается после
регистрации.

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

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

Значение

Описание

Значение

Описание

VERIFY

Необходимо подтвердить учетную запись кодом из СМС.

NEW

Мерчант создан, ожидается проверка на стороне SWiP.

ACTIVE

Мерчант проверен и активирован, можно принимать оплату.


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

1 { "status": ACTIVE }


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

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

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

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

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

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

1 POST /auth

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

Параметр

Тип

Описание

Параметр

Тип

Описание

password

string, обязательный

Пароль, необходимый для входа в маркетинговый движок.

username

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}

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

Параметр

Тип

Описание

Параметр

Тип

Описание

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}

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

Параметр

Тип

Описание

Параметр

Тип

Описание

personId

string, обязательный

Уникальный идентификатор юридического лица в системе SWiP.

bankDetailId

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

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

Параметр

Тип

Описание

Параметр

Тип

Описание

name

string, обязательный

Название торговой точки.

bankAccount

UUID, обязательный

Идентификатор банковского счета, к которому привязан магазин в системе SWiP.

address

string, необязательный

Адрес торговой точки.

phone

string, необязательный

Номер телефона торговой точки.

description

string, необязательный

Описание деятельности торговой точки.

latitude

string, необязательный

Координаты широты месторасположения торговой точки.

longitude

string, необязательный

Координаты долготы месторасположения торговой точки.

monFri

string, необязательный

Рабочие часы с ПН по ПТ.

satSun

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}

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

Параметр

Тип

Описание

Параметр

Тип

Описание

id

string, обязательный

Уникальный идентификатор торговой точки в системе SWiP.

name

string, обязательный

Название торговой точки.

bankAccount

UUID, обязательный

Идентификатор банковского счета, к которому привязан магазин в системе SWiP.

address

string, необязательный

Адрес торговой точки.

description

string, необязательный

Описание деятельности торговой точки.

latitude

double, необязательный

Координаты широты месторасположения торговой точки.

longitude

double, необязательный

Координаты долготы месторасположения торговой точки.

phone

string, необязательный

Номер телефона торговой точки.

monFri

string, необязательный

Рабочие часы с ПН по ПТ.

satSun

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}

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

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

Параметр

Тип

Описание

Параметр

Тип

Описание

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", } ]