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

Ключ идемпотентности

Назначение

Ключ идемпотентности — это уникальное значение, которое создаётся на стороне клиента и отправляется на сервер вместе с запросом.

В системе «Алмаз-Онлайн» ключ идемпотентности используется для предотвращения дублирования документов.

Ключ идемпотентности передаётся в 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"
}

Краткая схема работы

  1. Клиент формирует новый UUID.
  2. UUID передаётся в заголовке Idempotency-Key.
  3. Клиент отправляет запрос на создание документа через api/Document/Create.
  4. Сервер проверяет уникальность ключа.
  5. Если ключ уникальный — документ создаётся.
  6. Если ключ уже использовался — новый документ не создаётся.
  7. При необходимости клиент проверяет статус платежа через api/Payments/GetStatusByIK.

Возможные проблемы

Проблема Возможная причина Что сделать
Документ не создаётся Idempotency-Key уже использовался ранее Сформировать новый UUID для нового документа
Сервер вернул сообщение «Документ уже создан» Повторная отправка запроса с тем же ключом Использовать documentId из ответа или проверить статус платежа
Платёж не найден Документ с таким ключом не создавался Проверить корректность переданного IdempotencyKey
Документы могут дублироваться Клиент не передаёт Idempotency-Key Передавать уникальный UUID при каждом создании документа
Один ключ используется для разных документов Ошибка на стороне клиента Генерировать новый UUID для каждой новой операции

Важно

Не используйте один и тот же Idempotency-Key для разных документов. Один ключ должен соответствовать одной операции создания документа.

Back to top