Версии сценариев и повтор API: один запрос — один принятый запуск

Ответ пропал, а документ мог уже попасть в обработку

Интеграция отправила PDF, соединение оборвалось, ответ не пришёл. Самая опасная неопределённость здесь — не время ожидания, а неизвестность: принял сервер документ или нет. Если сразу создать новый запрос с новым идентификатором, одна спецификация может получить два запуска и два результата. Для этого случая в API DOKIVO предусмотрено неизменное намерение и восстановление по его ключу.

Вторая похожая проблема возникает при изменении настроек. Сотрудник обновил соответствие столбцов, а внешний workflow всё ещё использует прежний рецепт. Без версии трудно понять, почему два похожих документа дали разные книги. Поэтому сохранённые сценарии DOKIVO связывают запуск с конкретными правилами, а повтор — с конкретным входным набором.

Эти возможности приняты 28 октября на первом сценарии текстовых PDF спецификаций. В этой статье разбираем, как отличать повтор доставки от новой работы, зачем сервер возвращает 409 при подмене входа и что действительно подтвердили настоящие API-запросы.

Версия — снимок правил, по которым можно объяснить результат

В инструменте спецификаций вы настраиваете колонки, включение таблиц и проверки. После сохранения для API и n8n появляется определённая версия сценария. Она не становится «плавающим набором последних настроек»: изменение правил создаёт новую версию, а старые запуски сохраняют прежнюю привязку.

Представим учебный пример. В первой версии количество берётся из столбца «Кол-во», во второй добавлено другое соответствие заголовка. Сначала проверьте новую версию на образце, затем явно подключите её в интеграции. Уже импортированный n8n-шаблон не должен незаметно начать использовать другие правила посреди процесса закупки.

Версия не хранит старые документы или прежние цены. Это рецепт обработки. Для воспроизводимости результата нужны ещё входные файлы и запуск. Поэтому при разборе спорной строки полезно знать не только номер версии, но и какой комплект передали и какое замечание записано в итоговой книге.

Один ключ для одного намерения

В запросе запуска передаётся Idempotency-Key. Это не пароль доступа, а идентификатор конкретного намерения обработать определённый вход. Ключ создаётся один раз и сохраняется в вызывающей системе до отправки. При повторе используются тот же ключ, время requestCreatedAt, версия, параметры и файлы.

Сервер допускает 8–128 ASCII-символов из букв, цифр и ограниченного набора знаков. Для учебного примера ключ может выглядеть как order-482-spec-v1. Смысл имени выбирает ваша система; он не должен содержать секреты или полное содержимое документа. Авторизация выполняется отдельным API-ключом.

На стороне PostgreSQL уникальность относится к аккаунту и хешу ключа намерения. Она защищена транзакцией, поэтому два одновременно пришедших одинаковых запроса не должны решать вопрос простым чтением «пока записи нет». После принятия точный повтор возвращает тот же запуск, а не ещё одну копию конвертации.

Связь проверяется по входу. Одинакового имени файла недостаточно: сравниваются все байты переданных документов и параметры. Поменять цену в PDF, оставить прежнее имя и повторить тот же ключ — уже другой payload. Ответ idempotency_conflict с кодом 409 сообщает об этом различии явно.

Как восстановить прежний запуск после сетевой ошибки

Если POST был принят и вы получили runId, читайте его статус. Если ответа вообще нет, используйте GET /api/v1/runs/by-key с прежним Idempotency-Key. Такой запрос выясняет, было ли намерение уже принято, и не создаёт обработку. Новый ключ ради обхода неопределённости убрал бы защиту от дубликата.

Первый n8n-шаблон сохраняет намерение в данных выполнения и при потерянном ответе ищет запуск этим способом. После ограниченных безуспешных проверок есть отдельный исход «неизвестно», а не автоматическое молчаливое начало заново. Временная ошибка чтения статуса также повторяет GET, не отправку PDF.

При повторе всего родительского workflow из нового события нужно передать прежний dokivoIntent из журнала источника. Локально сохранённые данные одного выполнения n8n не становятся общей памятью всех будущих запусков. Если источник каждый раз создаёт новое намерение, API обоснованно рассматривает его как новую работу.

Проверили одинаковый runId, конфликт и поиск по ключу

В реальной приёмке API точная повторная отправка вернула тот же runId. Затем изменили байты документа при прежнем ключе и получили 409. Отдельно нашли созданный запуск через by-key. Так проверены три разных свойства: точный повтор, защита от подмены и восстановление после неизвестного сетевого исхода.

Два скачивания принятого API-результата дали одинаковые 13 755 байт XLSX, срок истечения остался прежним. В настоящем n8n два выполнения с одним намерением также получили один запуск и совпадающий результат; независимое скачивание через API подтвердило те же байты. Это разные контрольные книги, их размеры не следует смешивать.

API-ключ тестового доступа после приёмки отозвали и проверили отказ 401. Это относится к авторизации: ключ намерения сам по себе не даёт прав на результат. Чужой запуск недоступен как обычный ресурс другого аккаунта. Управление сценариями и получателями остаётся защищённым действием пользовательской сессии.

Эти проверки не обещают однократную запись в любой внешней системе. Один и тот же файл можно скачать повторно; получатель может повторно сохранить его. Если после DOKIVO следует CRM, объектное хранилище или база, их операция записи должна иметь собственную защиту, например устойчивый ключ на основе runId.

Как использовать это без скрытых повторных действий

1. Сохраните связь до POST. У источника уже должны быть собственный ID события и соответствующий dokivoIntent.
2. Не меняйте исходное намерение при retry. Новое время, другая версия, новый порядок файлов или исправленные байты — изменение входа, которое нужно разобрать явно.
3. Разделите неопределённость и доказанный отказ. Потерянный ответ не доказывает, что сервер ничего не принял. Используйте чтение by-key.
4. Отдельно принимайте изменения правил. Сохраните новую версию, проверьте образец и обновите внешнее подключение.
5. Доведите контроль до места записи. Совпадение runId на стороне DOKIVO не отменяет проверки результата в собственной системе.

История метаданных ключа хранится семь дней; новое намерение с временем создания старше суток не принимается. Это не срок хранения XLSX: готовый файл доступен пятнадцать минут. Разные окна защищают разные действия и не должны превращаться в общее обещание «всё можно повторить через неделю».

Точные маршруты и поля доступны в описании OpenAPI. Для первой проверки начните с учебного сценария на сайте и небольшого известного документа, чтобы спор о повторе не смешивался со спором о способе извлечения таблицы.

Частые вопросы