Перейти к содержанию

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"
}
Back to top