Как передавать данные инспекции в ERP и бухгалтерию без двойных записей?

Короткий ответ: как предотвратить дублирование записей?

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

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

Почему возникает дублирование?

Короткий ответ: большинство дублей возникает не потому, что пользователь дважды нажал кнопку, а из-за неконтролируемого повтора в неопределённый момент, когда первый запрос завершился успешно, но его ответ был потерян.

Инспекционная система отправляет в ERP запрос на создание заказа. ERP создаёт запись, но соединение закрывается и интеграция не получает ответ. Если обработчик повторно отправит тот же запрос как новую операцию, может открыться второй заказ. Аналогичный риск наблюдается при доставке в очереди «как минимум один раз», параллельных обработчиках, ручном повторе после тайм-аута и пакетной синхронизации.

IETF RFC 9110 определяет идемпотентную операцию как операцию, при которой многократное применение одного и того же запроса оказывает то же целевое воздействие, что и одно применение. PUT обладает этим свойством; создание нового ресурса через POST требует дополнительной защиты. Технический проект не должен предполагать, что сеть доставляет сообщения ровно один раз.

Какой идентификатор должен быть владельцем записи?

Инспекционная работа, заказ ERP, бухгалтерская проводка и электронный документ — не один и тот же идентификатор. В начале цепочки должна быть неизменная UUID исходной работы ; идентификаторы, создаваемые другими системами, следует хранить отдельно как её соответствия.

OASIS UBL 2.4 Invoice определяет ссылочные поля между счётом, заказом и другими документами. Руководство портала e-Fatura GİB также указывает, что счета с одинаковыми UUID и номером счёта не могут быть загружены повторно. Практический вывод состоит не в замене исходного инспекционного идентификатора номером электронного документа, а в хранении идентификаторов раздельно в двусторонней таблице соответствий.

Как формировать ключ идемпотентности?

Ключ не должен заново генерироваться случайно при каждом повторе; он должен оставаться одинаковым во всех попытках одной бизнес-операции. Пример области определения можно вывести из канонического объединения следующих частей:

tenant + hedef_sistem + işlem_türü + kaynak_iş_uuid + kaynak_sürümü

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

Актуальная справка API Stripe документирует, что после сбоя соединения запрос create/update можно безопасно повторить с тем же ключом идемпотентности, а если ключ тот же, но параметры изменились, запрос отклоняется. Это поведение, характерное для конкретного провайдера, полезно и как образец контракта для внутреннего ERP-адаптера: если тот же ключ приходит с другим клиентом, суммой или налоговым сопоставлением, не перезаписывайте молча; направьте конфликт на анализ.

Почему контроля на уровне приложения недостаточно?

При подходе «сначала проверь наличие, затем вставь» два обработчика одновременно могут увидеть отсутствие записи. Уникальность должна принудительно обеспечиваться и в базе данных.

В таблице связей интеграции создайте составное ограничение уникальности по tenant_id + target_system + document_type + source_job_uuid . Актуальная документация PostgreSQL по INSERT поясняет, что при наличии ограничения уникальности оператор ON CONFLICT позволяет атомарно выполнить вставку или обновление при конкурирующих запросах. Если бизнес-правило запрещает обновление, при конфликте верните ID существующей целевой записи; при расхождении данных остановите обработку и создайте запись для разбора.

UNIQUE (tenant_id, target_system, document_type, source_job_uuid)

aynı anahtar + aynı payload özeti  -> mevcut sonucu döndür
aynı anahtar + farklı payload       -> çakışma, otomatik belge açma

Как организовать Outbox и обработку очереди?

Если отдельно переводить инспекционный отчёт в состояние «готов к выставлению счёта» и записывать сообщение для ERP, операция может завершиться лишь частично. Состояние бизнес-процесса и событие интеграции следует фиксировать в одной локальной транзакции.

1. Уполномоченный пользователь подтверждает версию отчёта и объём выставляемых услуг.
2. Приложение в одной транзакции обновляет бизнес-состояние и добавляет запись Outbox с UUID события.
3. Обработчик отправляет событие Outbox целевому адаптеру с неизменным ключом идемпотентности.
4. При успешном ответе ID объекта в ERP и сведения об ответе сохраняются в таблице связей.
5. Если подтверждение ACK потеряно, событие приходит повторно; потребитель распознаёт UUID события и бизнес-связь и возвращает существующий результат.
6. Постоянную ошибку данных не следует помещать в цикл повторных попыток: её направляют на разбор или в очередь необрабатываемых сообщений, dead-letter.

Руководство Microsoft по Transactional Outbox рекомендует сохранять бизнес-объект и событие в одной транзакции. Руководство Service Bus поясняет, что из-за потери ACK и повторной доставки потребитель должен обеспечивать идемпотентность по MessageId или бизнес-идентификатору. Обнаружение дубликатов у отправителя не заменяет проверку уникальности у получателя.

Как безопасно сопоставлять клиентов, услуги и налоги?

Предотвращение дублей не сводится к техническим повторным попыткам. Повторное создание клиента из-за другого написания названия или выставление одной услуги под разными кодами также приводит к дублированию операций.

• Клиент: сопоставляйте записи в пределах организации по проверенному турецкому налоговому или личному идентификатору VKN/TCKN либо по ключу справочника клиентов; одного названия недостаточно.
• Услуга: свяжите метод контроля с утверждённым справочником номенклатуры или услуг ERP; не создавайте отсутствующий код автоматически из произвольного текста.
• Налоги и валюта: используйте версионируемое сопоставление со справочниками целевой системы; при отсутствующем или недопустимом соответствии остановите формирование документа.
• Сумма: зафиксируйте рассчитанные строки, скидки и налоги вместе с хешем исходной версии; изменения после утверждения проводите через новую ревизию.
• Полномочия: разграничьте роли создания клиентов, изменения сопоставлений и формирования финансовых документов, сохраняя отдельные аудиторские следы.

При неоднозначном сопоставлении нельзя автоматически выбирать «ближайший результат». Передачу следует приостановить до завершения проверки человеком; для решения сохранить автора, время, прежнее и новое значение и обоснование.

Как отслеживать состояние передачи?

Единственное поле «успешно/неуспешно» скрывает неопределённость. Модель состояний должна показывать, какой этап допускает повторное выполнение.

Удаление записи об успешной передаче с последующей повторной отправкой не является способом исправления. Если финансовый документ уже создан, отмена, возврат или сторнирование должны иметь собственный идентификатор и маршрут согласования.

Какие проверки должна выполнять сверка?

Ежедневная сверка должна сопоставлять записи исходной и целевой систем по идентификаторам, а не только подсчитывать ошибки в журнале.

• Задания, готовые к выставлению счёта, но не связанные с целевой записью.
• Несколько целевых документов, связанных с одним UUID исходного задания.
• Документы, присутствующие в целевой системе, но отсутствующие в исходной таблице связей.
• Записи, в которых исходная версия не соответствует хешу переданных данных.
• Попытки, остающиеся в неопределённом состоянии дольше установленного срока.
• Отсутствующие согласования или подтверждения ручных сопоставлений, отмен и сторнирований.

По результатам сверки нельзя автоматически удалять или массово объединять записи. Уполномоченному пользователю следует показать подозрительные записи, их идентификаторы в обеих системах и предлагаемое безопасное действие.

Как провести пилот интеграции VizyonTech?

Vizyon Periyodik и аналогичные инспекционные процессы при подключении к ERP следует проверять прежде всего на сбои, а затем — в штатном режиме. Испытайте двойное нажатие для одного задания, создание записи в ERP без ответа, получение одного сообщения двумя обработчиками, повторное использование ключа с другими данными, ошибочное сопоставление клиента и ревизию отчёта.

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