Интеграция API из Турции для России и СНГ

Источник данных, направление обмена и ответственность за приём

Интеграция API нужна не только для установления связи между двумя приложениями: важно определить, данные какой системы считать верными. Название товара может задаваться в каталоге, доступный остаток — в ERP, а статус доставки — в системе перевозчика. Эти источники обновляют одни и те же данные в разное время. Если до настройки двустороннего обмена не зафиксировать основной источник для каждого поля, направление передачи и допустимую задержку, расхождений может стать больше.

На начальном этапе мы составляем схему потоков данных. Получение заказа, его подтверждение, отгрузка и выставление счёта-фактуры — отдельные события. Какие звенья этой цепочки меняет отмена или частичный возврат? Как принимающая система обрабатывает корректировку, внесённую в исходную систему? Автоматизация не устраняет ситуации, требующие решения человека, но может направлять их в доступную сотрудникам очередь проверки.

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

Сопоставление каталогов и заказов на маркетплейсах

При подключении маркетплейса мы изучаем доступ продавца к API площадки, права учётной записи и действующие ограничения использования. Само название Trendyol, Hepsiburada, N11, Amazon или Pazarama не означает, что можно передавать любые данные. Категории и обязательные характеристики могут различаться между площадками. Создание единой карточки товара не должно опираться на предположение, что все площадки одинаково интерпретируют её данные.

Сопоставление каталога и остатков

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

Заказы и статусы площадки

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

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

Этикетка отправления и статус доставки — разные этапы

Создание записи об отправлении и передача посылки перевозчику — разные события. Создание этикетки не означает, что заказ доставлен. Количество мест, вес, объёмный вес (desi), адрес и тип услуги используются для формирования запроса на создание отправления. Чтобы повторная обработка заказа не создавала второе отправление, сохраняются внешний идентификатор записи и результат создания.

У перевозчиков, таких как Yurtici Kargo, Aras Kargo, MNG Kargo, PTT Kargo и Surat Kargo, условия доступа зависят от конкретной учётной записи и договора. Перед началом работ изучаются документация сервисов и разрешения. Мы не предполагаем, что все компании предоставляют одинаковые статусы доставки или операции возврата. Статусы перевозчика сопоставляются со статусами заказов компании; неизвестные коды не трактуются автоматически как «доставлено».

• Все номера отслеживания многоместного заказа сохраняются вместе.
• Отмена этикетки и повторная печать учитываются как разные операции.
• Возвратное отправление связывается с первоначальной отгрузкой.
• Ошибки в адресах направляются на проверку ответственным сотрудникам.

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

Сверка документов ERP и учётных записей контрагентов

При подключении ERP сначала изучаются официальный интерфейс бухгалтерской программы и права его использования. Разные версии и модули продуктов Logo, Netsis, Nebim, DIA, AkinSoft или Uyumsoft могут предоставлять разные возможности доступа. Наличие названия программы в списке не означает, что любой запланированный обмен технически осуществим. Для систем на локальном сервере может потребоваться безопасный промежуточный сервис.

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

Когда ERP подтверждает создание записи, идентификатор документа сохраняется. Потребует ли последующая корректировка нового документа, изменения существующего или сторнирующей записи? Это решение принимается с учётом методов, поддерживаемых программой. Прямая запись в базу данных без согласования с разработчиком системы не рассматривается как допустимый упрощённый путь. Когда специфические операции компании выполняются в ПО, разработанном специально для неё, ведение официальных учётных записей может оставаться в системе, определённой как их основной источник.

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

От отправки e-Fatura до принятия документа

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

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

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

Надёжная проверка результата платежа

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

Для банковского виртуального POS и платёжных сервисов, таких как iyzico и PayTR, обязательны учётная запись продавца, договор и право использования. Доступность международных решений, таких как Stripe и PayPal, отдельно проверяется для страны регистрации компании и типа её учётной записи; мы не утверждаем, что они доступны любой компании в Турции. Возможности оплаты в рассрочку, подписок и возвратов включаются в проект с учётом фактических условий провайдера.

Вместо хранения данных банковских карт рассматриваются поддерживаемые провайдером платёжные формы на его стороне или методы с токенизацией. Определяется связь между результатом 3D Secure и окончательным подтверждением заказа. При превышении времени ожидания, прежде чем предлагать пользователю оплатить повторно, необходимо выяснить статус первой попытки. Частичный возврат, несколько возвратов и неуспешный возврат могут отображаться в панели управления операциями отдельно.

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

Обработка ошибок при обмене через API, webhook и XML

REST API, webhook и файловый обмен отличаются механизмами доставки данных. Ответ API сообщает сведения об операции; webhook может задержаться или поступить повторно; XML-файл отражает состояние только на момент его создания. Метод выбирается с учётом частоты изменения данных и возможностей другой стороны. Вместо слова «мгновенно» определяются измеримый интервал передачи и допустимая задержка.

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

При передаче XML проверяются полнота файла, кодировка, формат даты и сопоставление товаров. Пустой или обрезанный файл не считается автоматическим основанием для обнуления всех остатков. Правила удаления данных и массовых изменений определяются отдельно. Для внутренних систем без документации рассматривается разработка API на заказ; право доступа и определение ответственности за данные остаются обязательными условиями.