Идемпотентность — свойство операции, при котором её повтор с теми же параметрами даёт тот же результат, а не вторую операцию. Для платежей это вопрос денег буквально: если связь оборвалась после отправки счёта, а ассистент повторил запрос, покупатель не должен получить два счёта, а продавец — два возврата.
Зачем это ассистенту
Человек, не дождавшись ответа, обычно проверяет результат глазами. Программа-ассистент в той же ситуации повторяет вызов — это её штатное поведение при таймауте. Поэтому создающие операции должны быть устроены так, чтобы повтор был безопасен: повторный вызов возвращает прежний результат, а не создаёт дубль.
Как это сделано в платёжном сервере
Многие платёжные API принимают вместе с запросом ключ идемпотентности. Если его нет, роль якоря может играть номер документа: в MCP-сервере Инвойсбокс номер заказа выводится детерминированно из даты и отпечатка ключа операции. После обрыва связи сервер ищет по этому номеру уже созданный документ — идемпотентность получается без отдельной поддержки на стороне API.
У операции четыре состояния: выполняется, выполнена, упала, неизвестно. «Неизвестно» — полноправный исход: сервер не угадывает результат платёжной операции ни в одну сторону. Если проверка не удалась, он показывает ситуацию человеку и останавливается. Если поиск вернул два документа с одним номером, сервер тоже не выбирает сам, а показывает кандидатов.
Интересные факты
- Схема держится на соглашении, которого API не проверяет: уникальность внешнего номера по умолчанию не гарантирована, поэтому ключ идемпотентности на уровне API записан как пожелание к следующей версии контракта.
- У отмены и отгрузки собственного номера нет, и идемпотентность по ключу там недостижима: восстановление опирается на наблюдаемые признаки — отмена перечитывает статус заказа, отгрузка ищется по номеру документа или по совпадению суммы и времени в окне минуты. Совпадение суммы и минуты названо эвристикой прямо в ответе.
- Идемпотентность вошла в общий набор механик агентных платежей у крупных игроков: повтор «заверши оплату» после таймаута не должен списать деньги второй раз.
- Собственный отказ по размеру ответа сервер считает детерминированным и не повторяет: повтор скачал бы то же тело и потратил те же деньги на трафик.
Коротко
- Идемпотентность — повтор даёт тот же результат, а не второй платёж.
- Ассистент повторяет вызовы при таймауте, поэтому создающие операции обязаны быть безопасны к повтору.
- Якорь — ключ идемпотентности или детерминированный номер документа.
- «Неизвестно» — честный исход: сервер показывает человеку, а не угадывает.
Полезно
AI-инвойсинг: счета через ассистента — подробнее →