Almaz API¶
Almaz API используется для интеграции внешних систем с сервисом «Алмаз-Онлайн».
Через API можно выполнять авторизацию, получать список доступных платёжных шлюзов, проверять баланс, создавать документы, прикреплять сканы, выполнять оплату и получать статус платежа.
Авторизация¶
Для работы с API необходимо выполнить авторизацию.
Полученный токен используется в остальных методах API.
Важно
Авторизация доступна пользователю, у которого есть право доступа к API.
Базовый адрес¶
https://api.almaz-online.ru
Основные методы API¶
| Метод | Назначение |
|---|---|
POST /api/Auth/Login |
Авторизация пользователя по email и паролю |
POST /api/Auth/Login2FA |
Подтверждение авторизации через 2FA |
POST /api/Auth/RefreshToken |
Обновление Access Token |
POST /api/Auth/RevokeToken |
Удаление Refresh Token |
POST /api/Gateway/GetBalance |
Получение баланса шлюза |
POST /api/Gateway/GetGateList |
Получение списка доступных шлюзов |
POST /api/Document/Create |
Создание документа |
POST /api/Attachment/GetTypeList |
Получение типов сканов |
POST /api/Attachment/Create |
Добавление скана |
POST /api/Payments/Create |
Создание оплаты |
POST /api/payments/SBPConfirm |
Подтверждение или отмена платежа по СБП |
POST /api/Payments/GetStatus |
Получение статуса оплаты |
GET /api/payment/GetLimits |
Получение лимитов |
POST /api/payment/ChangeLimit |
Изменение лимита |
POST /api/payment/AddLimit |
Добавление лимита |
Токен авторизации¶
Методы API, требующие авторизации, вызываются с заголовком:
Authorization: Bearer <token>
где <token> — токен, полученный после успешной авторизации.
Авторизация¶
1. Авторизация пользователя¶
POST /api/Auth/Login
Метод используется для авторизации пользователя по email и паролю.
POST https://api.almaz-online.ru/api/Auth/Login
Content-Type: application/json
Тело запроса¶
{
"Email": "string",
"Password": "string"
}
Пример curl-запроса¶
curl --location 'https://api.almaz-online.ru/api/Auth/Login' \
--header 'Content-Type: application/json' \
--data '{
"Email": "string",
"Password": "string"
}'
Успешный ответ¶
HTTP 200 OK
{
"tokenExpiresAt": "string",
"refreshTokenExpiresAt": "string",
"code": 0,
"codeTitle": "string",
"description": "string",
"requestId": "string"
}
Ошибка¶
HTTP 400 Bad Request
Bad Request Uncorrect Email or Password
Описание полей запроса¶
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
Email |
string |
Да | Email пользователя |
Password |
string |
Да | Пароль пользователя |
2. Подтверждение авторизации через 2FA¶
POST /api/Auth/Login2FA
Метод используется для подтверждения входа через двухфакторную аутентификацию.
Код может быть получен по SMS или из приложения-аутентификатора, если используется OTP.
POST https://api.almaz-online.ru/api/Auth/Login2FA
Content-Type: application/json
Тело запроса¶
{
"Email": "string",
"Password": "string",
"code": "string"
}
Пример curl-запроса¶
curl --location 'https://api.almaz-online.ru/api/Auth/Login2FA' \
--header 'Content-Type: application/json' \
--data '{
"Email": "string",
"Password": "string",
"code": "string"
}'
Успешный ответ¶
HTTP 200 OK
{
"token": "string",
"tokenExpiresAt": "string",
"refreshToken": "string",
"refreshTokenExpiresAt": "string",
"code": 0,
"codeTitle": "string",
"description": "string",
"requestId": "string"
}
Ошибка¶
HTTP 400 Bad Request
Bad Request Uncorrect Email or Code
Описание полей запроса¶
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
Email |
string |
Да | Email пользователя |
Password |
string |
Да | Пароль пользователя |
code |
string |
Да | Код подтверждения 2FA |
3. Обновление токена¶
POST /api/Auth/RefreshToken
Метод используется для обновления Access Token с помощью Refresh Token.
POST https://api.almaz-online.ru/api/Auth/RefreshToken
Authorization: Bearer <token>
Content-Type: application/json
Тело запроса¶
{
"RefreshToken": "string"
}
Пример curl-запроса¶
curl --location 'https://api.almaz-online.ru/api/Auth/RefreshToken' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"RefreshToken": "string"
}'
Успешный ответ¶
{
"token": "string",
"tokenExpiresAt": "string",
"refreshToken": "string",
"refreshTokenExpiresAt": "string",
"code": 0,
"codeTitle": "string",
"description": "string",
"requestId": "string"
}
4. Удаление Refresh Token¶
POST /api/Auth/RevokeToken
Метод используется для удаления Refresh Token.
POST https://api.almaz-online.ru/api/Auth/RevokeToken
Authorization: Bearer <token>
Content-Type: application/json
Тело запроса¶
{
"UserId": "string"
}
Пример curl-запроса¶
curl --location 'https://api.almaz-online.ru/api/Auth/RevokeToken' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"UserId": "string"
}'
Успешный ответ¶
{
"code": 0,
"codeTitle": "string",
"requestId": "string"
}
Платёжные шлюзы¶
5. Получение баланса шлюза¶
POST /api/Gateway/GetBalance
Метод используется для получения баланса платёжного шлюза.
POST https://api.almaz-online.ru/api/Gateway/GetBalance
Authorization: Bearer <token>
Content-Type: application/json
Тело запроса¶
{
"gatewayId": "e879bcad-7af1-4452-b028-abad8ba3a17c"
}
Пример curl-запроса¶
curl --location 'https://api.almaz-online.ru/api/Gateway/GetBalance' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"gatewayId": "e879bcad-7af1-4452-b028-abad8ba3a17c"
}'
Успешный ответ¶
{
"balance": 0,
"isHidden": false,
"code": 0,
"codeTitle": "Ok",
"requestId": "0HNLGQGFGJ3JV:00000001"
}
6. Получение списка шлюзов¶
POST /api/Gateway/GetGateList
Метод используется для получения списка доступных платёжных шлюзов.
Полученный id шлюза используется в методах получения баланса и оплаты.
POST https://api.almaz-online.ru/api/Gateway/GetGateList
Authorization: Bearer <token>
Content-Type: application/json
Тело запроса¶
{}
Пример curl-запроса¶
curl --location 'https://api.almaz-online.ru/api/Gateway/GetGateList' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{}'
Успешный ответ¶
{
"gatewayList": [
{
"id": "151b38af-d9db-4551-b4c0-b77a08de7a4b",
"name": "РСХБ",
"displayName": "РСХБ",
"gatewayName": "РСХБ",
"gatewayNameSys": "RshbPayoutService",
"isSbpActive": false,
"isHidden": true
},
{
"id": "28bb0eff-d44c-4301-9d26-ad1bfb910f68",
"name": "Vtb",
"displayName": "VTB",
"gatewayName": "ВТБ",
"gatewayNameSys": "VtbPayoutService",
"isSbpActive": false,
"isHidden": false
}
],
"code": 0,
"codeTitle": "Ok",
"requestId": "0HNHJ6RCQ569U:00000001"
}
Документы и сканы¶
7. Создание документа¶
POST /api/Document/Create
Метод используется для создания платёжного документа.
Полученный documentId используется для добавления сканов, оплаты и проверки статуса оплаты.
Ключ идемпотентности
Для предотвращения дублирования документов можно передавать в заголовке Idempotency-Key значение в формате UUID.
POST https://api.almaz-online.ru/api/Document/Create
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: db6de35f-b0d6-4d68-a994-d8222f17dea7
Тело запроса¶
{
"Person": {
"LastName": "string",
"FirstName": "string",
"MiddleName": "string",
"IsResident": "string",
"Phone": "string",
"Passport": {
"Serial": "string",
"Number": "string",
"DateIssue": "2019-08-24",
"RegName": "string",
"RegCode": "string",
"Birthday": "2019-08-24",
"BirthPlace": "2019-08-24",
"BirthCountry": "string",
"RegAddress": "string",
"PostalAddress": "string"
}
},
"Document": {
"Number": "string",
"Date": "2019-08-24",
"Sum": "string"
}
}
Пример curl-запроса¶
curl --location 'https://api.almaz-online.ru/api/Document/Create' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: db6de35f-b0d6-4d68-a994-d8222f17dea7' \
--data '{
"Person": {
"LastName": "string",
"FirstName": "string",
"MiddleName": "string",
"IsResident": "string",
"Phone": "string",
"Passport": {
"Serial": "string",
"Number": "string",
"DateIssue": "2019-08-24",
"RegName": "string",
"RegCode": "string",
"Birthday": "2019-08-24",
"BirthPlace": "2019-08-24",
"BirthCountry": "string",
"RegAddress": "string",
"PostalAddress": "string"
}
},
"Document": {
"Number": "string",
"Date": "2019-08-24",
"Sum": "string"
}
}'
Успешный ответ¶
{
"documentId": "69154ed6-5e95-4960-9d04-08685b96eb02",
"code": 0,
"codeTitle": "Ok",
"requestId": "0HNHJ6RCQ569R:00000001"
}
8. Получение списка типов сканов¶
POST /api/Attachment/GetTypeList
Метод используется для получения списка типов сканов.
Полученный id типа скана используется при загрузке вложений.
POST https://api.almaz-online.ru/api/Attachment/GetTypeList
Authorization: Bearer <token>
Пример curl-запроса¶
curl --location --request POST 'https://api.almaz-online.ru/api/Attachment/GetTypeList' \
--header 'Authorization: Bearer <token>'
Успешный ответ¶
{
"attachTypesList": [
{
"id": "string",
"name": "string"
}
],
"code": 0,
"codeTitle": "string",
"requestId": "string"
}
9. Добавление скана¶
POST /api/Attachment/Create
Метод используется для добавления скана к документу.
Запрос отправляется в формате multipart/form-data.
POST https://api.almaz-online.ru/api/Attachment/Create
Authorization: Bearer <token>
Content-Type: multipart/form-data
Поля формы¶
| Поле | Описание |
|---|---|
File |
Файл скана |
request |
Данные DocumentId, TypeId |
Пример curl-запроса¶
curl --location 'https://api.almaz-online.ru/api/Attachment/Create' \
--header 'Authorization: Bearer <token>' \
--form 'File=@"/path/to/file"' \
--form 'request="DocumentId, TypeId"'
Успешный ответ¶
OK
Оплата¶
10. Создание оплаты¶
POST /api/Payments/Create
Метод используется для оплаты созданного документа.
POST https://api.almaz-online.ru/api/Payments/Create
Authorization: Bearer <token>
Content-Type: application/json
Тело запроса¶
{
"DocumentId": "898a2182-7164-4cc9-b9cf-8f84afe980ce",
"GatewayId": "2388b642-943c-4d74-9af7-35ee23218bc3",
"BankCard": {
"Number": "string",
"Holder": "string"
}
}
Пример curl-запроса¶
curl --location 'https://api.almaz-online.ru/api/Payments/Create' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"DocumentId": "898a2182-7164-4cc9-b9cf-8f84afe980ce",
"GatewayId": "2388b642-943c-4d74-9af7-35ee23218bc3",
"BankCard": {
"Number": "string",
"Holder": "string"
}
}'
Успешный ответ¶
{
"documentId": "69154ed6-5e95-4960-9d04-08685b96eb02",
"status": "Init",
"code": 0,
"codeTitle": "Ok",
"description": "",
"requestId": "0HNHJ6RCQ56A4:00000001"
}
11. Подтверждение или отмена платежа по СБП¶
POST /api/payments/SBPConfirm
Метод используется для подтверждения или отмены платежа по СБП.
Значение WasConfirmed |
Описание |
|---|---|
true |
Подтверждение платежа |
false |
Отмена платежа |
POST https://api.almaz-online.ru/api/payments/SBPConfirm
Authorization: Bearer <token>
Content-Type: application/json
Тело запроса¶
{
"docActId": "3daebb6e-078c-4d81-a628-47bacba7bf6c",
"WasConfirmed": true
}
Пример curl-запроса¶
curl --location 'https://api.almaz-online.ru/api/payments/SBPConfirm' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"docActId": "3daebb6e-078c-4d81-a628-47bacba7bf6c",
"WasConfirmed": true
}'
Успешный ответ¶
{
"documentId": "69154ed6-5e95-4960-9d04-08685b96eb02",
"status": "Init",
"code": 0,
"codeTitle": "Ok",
"description": "",
"requestId": "0HNHJ6RCQ56A4:00000001"
}
12. Получение статуса оплаты¶
POST /api/Payments/GetStatus
Метод используется для получения статуса оплаты по документу.
POST https://api.almaz-online.ru/api/Payments/GetStatus
Authorization: Bearer <token>
Content-Type: application/json
Тело запроса¶
{
"documentId": "string"
}
Пример curl-запроса¶
curl --location 'https://api.almaz-online.ru/api/Payments/GetStatus' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"documentId": "string"
}'
Успешный ответ¶
{
"gatewayId": "38b883d2-2c92-4e08-bcef-2a5f8c8c30f4",
"sum": 1,
"state": 1,
"documentId": "e268f539-e698-42c0-9cf0-91e701cf2f29",
"status": "Successful",
"code": 0,
"codeTitle": "Ok",
"requestId": "0HNHJ6RCQ56A8:00000001"
}
Статусы оплаты¶
| Статус | Описание |
|---|---|
init |
Создан. Платёжный документ создан |
successful |
Оплачен. Платёжный документ успешно оплачен |
canceled |
Отмена. Оплата отменена пользователем при подтверждении платежа по СБП |
error |
Отказ. Банк отказал в проведении платежа |
process |
В процессе. Обработка на стороне системы Алмаз |
processing |
В обработке. Ожидается ответ от банка |
awaitingConfirmation |
Ожидание. Требуется подтверждение пользователем выплаты по СБП |
Лимиты¶
13. Получение лимитов¶
GET /api/payment/GetLimits
Метод используется для получения списка доступных шлюзов и лимитов.
GET https://api.almaz-online.ru/api/payment/GetLimits
Authorization: Bearer <token>
Пример curl-запроса¶
curl --location 'https://api.almaz-online.ru/api/payment/GetLimits' \
--header 'Authorization: Bearer <token>'
Успешный ответ¶
{
"availableCompanyGateways": [
{
"settingId": "100ac584-c716-4abe-a005-6d19a6fb0722",
"companyId": "96a6a627-e263-41fd-ab9f-82231581a379",
"name": "ФИНСТАР",
"gatewayLimits": [
{
"id": "0a044021-715f-4fe0-bf2a-d385e2c34da6",
"limit": 10,
"spentLimit": 4,
"limitSettingType": 1,
"gatewayTimeLimit": 8,
"isActive": true
}
]
}
],
"code": 0,
"codeTitle": "Ok",
"requestId": "0HN17U8JKL100:00000002"
}
14. Изменение лимита¶
POST /api/payment/ChangeLimit
Метод используется для изменения существующего лимита.
Значения LimitSettingType¶
| Значение | Описание |
|---|---|
1 |
Постоянный лимит |
2 |
Одноразовый лимит |
Значения GatewayTimeLimit¶
| Значение | Описание |
|---|---|
0 |
Один день |
7 |
Неделя |
8 |
Месяц |
POST https://api.almaz-online.ru/api/payment/ChangeLimit
Authorization: Bearer <token>
Content-Type: application/json
Тело запроса¶
{
"name": "LimitNameHere",
"comment": "LimitCommentHere",
"limit": 140,
"limitSettingType": 2,
"gatewayTimeLimit": 0,
"isActive": false,
"id": "971f03fe-2b5e-4ef9-9350-98d4865b74b1"
}
Пример curl-запроса¶
curl --location 'https://api.almaz-online.ru/api/payment/ChangeLimit' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"name": "LimitNameHere",
"comment": "LimitCommentHere",
"limit": 140,
"limitSettingType": 2,
"gatewayTimeLimit": 0,
"isActive": false,
"id": "c9a83d21-8b47-4072-bef2-6c5619317e76"
}'
Успешный ответ¶
{
"id": "0a044021-715f-4fe0-bf2a-d385e2c34da6",
"settingId": "100ac584-c716-4abe-a005-6d19a6fb0722",
"companyId": "96a6a627-e263-41fd-ab9f-82231581a379",
"name": "Name",
"comment": "Comment",
"limit": 140,
"spentLimit": 0,
"limitSettingType": 1,
"gatewayTimeLimit": 8,
"isActive": false,
"code": 0,
"codeTitle": "Ok",
"requestId": "0HN17U8JKL100:00000007"
}
15. Добавление лимита¶
POST /api/payment/AddLimit
Метод используется для добавления нового лимита.
Значения LimitSettingType¶
| Значение | Описание |
|---|---|
1 |
Постоянный лимит |
2 |
Одноразовый лимит |
Значения GatewayTimeLimit¶
| Значение | Описание |
|---|---|
0 |
Один день |
7 |
Неделя |
8 |
Месяц |
POST https://api.almaz-online.ru/api/payment/AddLimit
Authorization: Bearer <token>
Content-Type: application/json
Тело запроса¶
{
"name": "LimitName",
"comment": "LimitComment",
"limit": 20,
"limitSettingType": 1,
"gatewayTimeLimit": 7,
"settingId": "c92b9737-da32-4b9f-9c6d-536ae3b7f207",
"companyId": "d4f7970d-41c8-462e-bc63-39e92853db29"
}
Пример curl-запроса¶
curl --location 'https://api.almaz-online.ru/api/payment/AddLimit' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"name": "LimitName",
"comment": "LimitComment",
"limit": 20,
"limitSettingType": 1,
"gatewayTimeLimit": 7,
"settingId": "c92b9737-da32-4b9f-9c6d-536ae3b7f207",
"companyId": "d4f7970d-41c8-462e-bc63-39e92853db29"
}'
Пример ответа с ошибкой¶
{
"code": 6,
"codeTitle": "ValidationError",
"description": "Лимит не найден",
"requestId": "0HN17U8JKL100:00000003"
}