Ключ идемпотентности¶
Назначение¶
Ключ идемпотентности — это уникальное значение, которое создаётся на стороне клиента и отправляется на сервер вместе с запросом.
В системе «Алмаз-Онлайн» ключ идемпотентности используется для предотвращения дублирования документов.
Ключ идемпотентности передаётся в HTTP-заголовке Idempotency-Key в методе создания документа:
api/Document/Create
Тип данных ключа:
UUID
Принцип работы¶
При отправке запроса на создание документа сервер проверяет уникальность значения Idempotency-Key.
| Условие | Результат |
|---|---|
Idempotency-Key уникальный |
Документ будет создан |
Idempotency-Key уже использовался ранее |
Новый документ не будет создан |
Важно
Для каждого нового документа необходимо создавать новый уникальный Idempotency-Key.
Пример заголовков запроса¶
Idempotency-Key: db6de35f-b0d6-4d68-a994-d8222f17dea7
Content-Type: application/json
Authorization: Bearer ...
Пример запроса¶
{
"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": "string",
"BirthCountry": "string",
"RegAddress": "string",
"PostalAddress": "string"
}
},
"Document": {
"Number": "string",
"Date": "2019-08-24",
"Sum": "string"
}
}
Примечание
В примере значение Idempotency-Key указано только для демонстрации. При каждом новом создании документа необходимо использовать новый UUID.
Повторная отправка с тем же ключом¶
Если запрос с таким Idempotency-Key уже был успешно обработан ранее, новый документ не создаётся.
В этом случае сервер вернёт информацию о том, что документ уже был создан.
Пример ответа:
{
"documentId": "dd85219b-3542-407f-a965-774179766453",
"code": 2,
"codeTitle": "ServerError",
"description": "Документ уже создан",
"requestId": "0HN54K7OE2535:00000001"
}
Поле documentId содержит идентификатор ранее созданного документа.
Рекомендация
Если клиент повторно отправил запрос с тем же Idempotency-Key, не нужно создавать новый документ. Используйте documentId из ответа или проверьте статус платежа по ключу идемпотентности.
Проверка статуса платежа по Idempotency-Key¶
Для проверки статуса платежа по ключу идемпотентности используется метод:
api/Payments/GetStatusByIK
Тело запроса¶
{
"IdempotencyKey": "uuid"
}
Пример:
{
"IdempotencyKey": "db6de35f-b0d6-4d68-a994-d8222f17dea7"
}
Успешный ответ¶
Если документ с указанным IdempotencyKey найден, сервер вернёт информацию о платеже.
{
"gatewayId": "uuid",
"sum": 1000,
"state": 1,
"documentId": "string",
"status": "string",
"code": 0,
"codeTitle": "Ok",
"requestId": "0HN67BRHAPBP6:00000001"
}
Описание полей ответа¶
| Поле | Описание |
|---|---|
gatewayId |
Идентификатор платёжного шлюза |
sum |
Сумма платежа |
state |
Числовое состояние платежа |
documentId |
Идентификатор платёжного документа |
status |
Статус платежа |
code |
Код ответа системы |
codeTitle |
Текстовое обозначение кода ответа |
requestId |
Идентификатор запроса |
Ответ, если платёж не найден¶
Если документ с указанным IdempotencyKey не найден, сервер вернёт ответ:
{
"sum": 0,
"state": 0,
"code": 4,
"codeTitle": "NotFound",
"description": "Платеж не найден",
"requestId": "0HN67BRHAPBP8:00000001"
}
Краткая схема работы¶
- Клиент формирует новый UUID.
- UUID передаётся в заголовке
Idempotency-Key. - Клиент отправляет запрос на создание документа через
api/Document/Create. - Сервер проверяет уникальность ключа.
- Если ключ уникальный — документ создаётся.
- Если ключ уже использовался — новый документ не создаётся.
- При необходимости клиент проверяет статус платежа через
api/Payments/GetStatusByIK.
Возможные проблемы¶
| Проблема | Возможная причина | Что сделать |
|---|---|---|
| Документ не создаётся | Idempotency-Key уже использовался ранее |
Сформировать новый UUID для нового документа |
| Сервер вернул сообщение «Документ уже создан» | Повторная отправка запроса с тем же ключом | Использовать documentId из ответа или проверить статус платежа |
| Платёж не найден | Документ с таким ключом не создавался | Проверить корректность переданного IdempotencyKey |
| Документы могут дублироваться | Клиент не передаёт Idempotency-Key |
Передавать уникальный UUID при каждом создании документа |
| Один ключ используется для разных документов | Ошибка на стороне клиента | Генерировать новый UUID для каждой новой операции |
Важно
Не используйте один и тот же Idempotency-Key для разных документов. Один ключ должен соответствовать одной операции создания документа.