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

Источники данных

Входящий REST-источник

Как создать входящий REST-источник, настроить эндпойнт, Basic или API-ключ, JSON-схему и безопасно передавать данные в маршрут печати.

Основной разделИсточники данных
Последняя проверка

Источник rest-inbound принимает HTTP POST от внешней системы, сохраняет полученное сообщение во внутренней очереди и передаёт записи в связанный маршрут печати. Автоматизация не опрашивает внешний сервер: инициатором всегда является интегрирующая система.

В статье описаны настройка эндпойнта, аутентификация, формат JSON, поля, ответы API и безопасный ввод в эксплуатацию. Общие действия каталога приведены в статье «Коннекторы и источники данных».

Важно. Успешный HTTP-ответ 202 Accepted означает, что запрос принят во внутреннюю очередь. Он не подтверждает завершение печати. Результат контролируется по requestId, runId, очереди печати и журналу.

Как проходит запрос

Последовательность обработки:

  1. Внешняя система отправляет POST с JSON.
  2. Автоматизация находит источник по имени из URL.
  3. Проверяются активность источника и маршрута, аутентификация и формат тела.
  4. Допустимые поля нормализуются, а запрос сохраняется вместе с идентификаторами requestId и runId.
  5. Для одного источника принятые запросы обрабатываются последовательно, в порядке поступления.
  6. Записи передаются в маршрут и далее в очередь печати.
  7. Итог отслеживается в интерфейсе Автоматизации, а не только по HTTP-ответу.

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

Что подготовить

До настройки согласуйте:

  • стабильное имя источника без пробелов, /, ? и #;
  • сетевое имя, протокол и порт сервера Автоматизации;
  • способ аутентификации;
  • плоскую структуру JSON и типы полей;
  • один объект или массив объектов в одном запросе;
  • шаблон, маршрут, принтер, формат печати и число копий;
  • способ хранения requestId и runId у отправителя;
  • правила повторной отправки после сетевой ошибки.

Для рабочего контура используйте HTTPS на уровне хоста или обратного прокси. Аутентификация защищает доступ, но сама по себе не шифрует HTTP-трафик.

Создать источник

  1. Откройте Источники данных.
  2. Нажмите Создать источник.
  3. Введите стабильное имя, например REST_Orders.
  4. В поле Тип источника выберите rest-inbound.

Имя становится частью адреса:

/api/connectors/inbound/{sourceName}

Например, для REST_Orders путь будет:

/api/connectors/inbound/REST_Orders

Полный адрес показывается в информационной строке формы. Если открыт localhost, интерфейс предупреждает: для удалённого вызова замените только localhost на DNS-имя или IP-адрес сервера. Протокол и порт должны соответствовать фактической публикации приложения.

После передачи адреса интеграторам не переименовывайте источник без согласованной миграции: старый URL перестанет находить его.

Выбрать аутентификацию

В поле Аутентификация доступны три режима.

  • Без аутентификации — Только JSON. Допустимо лишь в изолированном тестовом контуре с сетевым ограничением доступа.
  • Basic — Заголовок Authorization: Basic …. Используйте отдельные имя пользователя и пароль, передаваемые только по HTTPS.
  • API-ключ — Заголовок X-API-Key. Предпочтительный простой вариант для машинной интеграции при обязательном HTTPS.

Basic

При выборе Basic появляются поля Пользователь и Пароль.

Создайте отдельные учётные данные для конкретной интеграции. Не используйте пароль интерактивного пользователя приложения. Клиент формирует стандартный заголовок Authorization со схемой Basic.

API-ключ

При выборе API-ключ появляется защищённое поле X-API-Key.

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

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

Выбрать формат сообщения

Поле Формат входящего сообщения имеет два значения.

  • Один объект — Один плоский объект { ... }. Один набор с одной записью.
  • Массив объектов — Массив [ { ... }, { ... } ]. Один принятый запрос с несколькими записями.

Фактическое тело должно точно соответствовать выбранному режиму. Объект вместо массива или массив вместо объекта возвращает ошибку 400.

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

Пример одного объекта:

{
  "orderId": "ORD-1001",
  "productName": "Чай зелёный",
  "barcode": "4607001000029",
  "quantity": 2,
  "price": 289.50,
  "isReprint": false,
  "printedAt": "2026-09-11T10:30:00Z"
}

Для режима массива отправляется массив таких объектов. Не заворачивайте его в дополнительное свойство data, items или records.

Создать поля из JSON-образца

Поле JSON-образец всегда описывает один редактируемый объект, даже если в поле формата выбран Массив объектов. Образец нужен только для определения схемы и отдельно не сохраняется как рабочее сообщение.

  1. Вставьте один обезличенный плоский объект.
  2. Используйте значения, позволяющие правильно определить типы.
  3. Нажмите Обновить поля из образца.
  4. Убедитесь, что показано сообщение об успешном обновлении.
  5. Проверьте созданные карточки полей.

Типы определяются по JSON-значениям:

  • "text" — Текст
  • 10 — Целое число
  • 10.5 — Десятичное число
  • true или false — Логическое значение
  • null — Текст, пока тип не задан вручную или не выведен из другого значения

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

Если образец содержит несколько записей, целое и дробное число объединяются в десятичный тип, а несовместимые типы — в текст. Для документации интеграции всё равно используйте один канонический объект с однозначными значениями.

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

Настроить используемые поля

После применения образца все обнаруженные поля появляются в группе Поля.

  • Используемые поля принимаются из запроса и передаются в маршрут.
  • Неиспользуемые поля не передаются дальше.
  • Неизвестные свойства рабочего JSON отбрасываются и не появляются в наборе данных только потому, что отправитель их добавил.

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

Кнопка настройки на карточке открывает тип и значение по умолчанию.

Проверьте:

  • Имя — стабильное имя свойства JSON;
  • Тип данных — ожидаемый тип во всех сообщениях;
  • По умолчанию — безопасное значение для допустимого отсутствующего или пустого свойства.

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

После изменения состава или типа полей проверьте привязки всех связанных шаблонов. Переименование свойства — это изменение контракта интеграции.

Настроить отбор записей

После создания полей можно нажать Добавить условие, выбрать используемое поле и задать значение. Запись передаётся в маршрут, только если выполнены все условия.

Например, условие isReprint = false может отделять обычную печать от повторной. Убедитесь, что значение и тип совпадают: текст "false" и логическое значение false — разные данные.

Для режима массива условия применяются к каждому объекту отдельно. Если ни один объект не прошёл отбор, принятый запрос завершается без данных и маршрут не должен создавать задания.

Открыть пример для интегратора

После создания используемых полей нажмите Пример для интегратора.

Диалог содержит:

  • полный эндпойнт;
  • выбранный формат сообщения;
  • готовое тело запроса с нейтральными значениями;
  • команду cURL;
  • кнопки Скопировать JSON и Скопировать cURL.

Пример учитывает выбранную аутентификацию. Для Basic он содержит заполнители <user> и <password>, для API-ключа — <api-key>. Перед рабочим вызовом замените заполнители в защищённой конфигурации клиента, а не в документации или общем скрипте.

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

Сохранить и связать источник

Перед сохранением проверьте:

  • стабильное имя и сформированный URL;
  • способ аутентификации и наличие требуемого секрета;
  • режим Один объект или Массив объектов;
  • состав и типы используемых полей;
  • условия отбора;
  • сгенерированный пример интегратора.

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

Входящий REST не имеет расписания: запуск происходит при поступлении HTTP- запроса. Поэтому в каталоге команды ручного запуска и предпросмотра для него недоступны. Проверка выполняется контролируемым запросом от тестового клиента.

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

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

Сформировать запрос

Минимальный запрос всегда использует:

POST /api/connectors/inbound/REST_Orders HTTP/1.1
Content-Type: application/json

Для API-ключа добавьте:

X-API-Key: <api-key>

Для Basic добавьте стандартный заголовок:

Authorization: Basic <base64-user-colon-password>

Не формируйте Base64 как средство шифрования: это только кодирование. Basic должен передаваться по HTTPS.

Тело запроса должно быть UTF-8 JSON и соответствовать выбранному режиму. Отправляйте только необходимые поля и не включайте секреты, персональные данные или служебные объекты, которые не нужны печати.

Обработать HTTP-ответ

  • 202 Accepted — Запрос сохранён во внутренней очереди. Ответ содержит requestId и runId.. Сохранить оба идентификатора и отслеживать итог обработки.
  • 400 Bad Request — JSON не соответствует выбранному формату или содержит недопустимую структуру.. Не повторять без изменения; исправить тело и контракт.
  • 401 Unauthorized — Не переданы или не совпали Basic-данные либо X-API-Key.. Проверить выбранный режим и секрет; не записывать секрет в лог.
  • 404 Not Found — Источник с именем из URL не найден.. Проверить точное имя и путь, включая переименование источника.
  • 503 Service Unavailable — Источник/маршрут неактивен, конфигурация недопустима либо запрос не удалось сохранить.. Проверить активность и системный журнал; повторять только после установления причины.

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

Исключить дубли при повторной отправке

Повторный POST создаёт новый запрос. Встроенный HTTP-контракт не обещает автоматическое устранение дублей по содержимому или бизнес-идентификатору. Поэтому отправитель не должен повторять запрос только потому, что печать ещё не завершилась.

Рекомендуемый порядок:

  1. Присвойте операции уникальный бизнес-идентификатор, например orderId.
  2. После 202 сохраните requestId и runId вместе с ним.
  3. При разрыве соединения сначала выясните, был ли запрос принят.
  4. Проверьте очередь и журнал по времени, маршруту и идентификаторам.
  5. Повторяйте запрос только после подтверждения, что первая операция не была принята или безопасно завершена без печати.
  6. Для явной повторной печати создавайте новую контролируемую операцию и фиксируйте причину.

Если HTTP-клиент автоматически повторяет POST при тайм-ауте, отключите такой повтор либо реализуйте согласованный механизм идемпотентности в системе- отправителе. Один и тот же payload, отправленный дважды, может привести к двум наборам заданий.

Провести первый тест

Используйте тестовый маршрут и принтер.

  1. Оставьте источник и маршрут неактивными, пока проверяете форму и поля.
  2. Сохраните источник, маршрут и привязки шаблона.
  3. Проверьте пример для интегратора и адрес с компьютера отправителя.
  4. Активируйте маршрут и источник в согласованном порядке.
  5. Отправьте один тестовый объект с уникальным orderId.
  6. Убедитесь, что клиент получил 202, requestId и runId.
  7. Найдите созданное задание в Очередях печати.
  8. Сверьте фактическую этикетку и Журнал распечатки.
  9. Только после этого проверьте массив из двух различных объектов.
  10. Отдельно проверьте ошибочный JSON и неверный секрет — печать при этом не должна запускаться.

Для массива заранее рассчитайте ожидаемое число заданий и копий. Не используйте большой рабочий пакет как первый тест.

Изменить рабочий REST-контракт

Изменения имени, аутентификации, формата сообщения, полей и условий отбора влияют на внешнюю систему и связанные маршруты.

Перед изменением:

  1. остановите отправку новых запросов;
  2. дождитесь понятного результата уже принятых операций;
  3. сохраните перечень связанных маршрутов и шаблонов;
  4. согласуйте новую версию контракта с интегратором;
  5. подготовьте тестовый запрос и план возврата.

После изменения:

  1. заново сформируйте Пример для интегратора;
  2. обновите защищённую конфигурацию клиента;
  3. перепривяжите изменённые поля шаблона;
  4. проверьте один объект и массив, если они используются;
  5. проверьте 400, 401, 404 и неактивный маршрут;
  6. возобновите рабочую отправку только после полного теста.

Если редактор открыт только для чтения, источник занят другой сессией. Закройте форму, дождитесь завершения редактирования и откройте её снова.

Диагностика

  • Клиент не соединяется — DNS/IP, порт, протокол, сертификат HTTPS, сетевой экран и публикацию приложения.
  • Connector.RestPayloadInvalid / 400 — Корневой объект или массив по выбранному режиму, валидность JSON и отсутствие вложенных объектов/массивов.
  • Connector.RestUnauthorized / 401 — Режим аутентификации, имя Basic, пароль или заголовок X-API-Key. Не выводите секрет в лог.
  • 404 — Имя источника в URL, переименование и точный путь /api/connectors/inbound/{sourceName}.
  • Connector.RestSourceInactive / 503 — Активность входящего источника.
  • Connector.RestRouteInactive / 503 — Наличие и активность связанного маршрута.
  • Connector.RestInboxPersistenceFailed / 503 — Состояние хранилища приложения и системные события в момент запроса.
  • 202, но задания нет — Условия отбора, состав используемых полей, состояние маршрута и цикл по runId.
  • Часть полей пустая — Точные имена свойств, типы, null, исключённые поля и привязки шаблона.
  • Получена повторная этикетка — Повторные POST-запросы клиента, автоматическую retry-политику и уникальный бизнес-идентификатор.
  • Массив обрабатывается не полностью — Типы и структуру каждого элемента, условия отбора и состояние заданий по одному runId.
  • После перезапуска есть незавершённый запрос — Очередь, журнал и фактический результат печати; не отправляйте дубль до проверки восстановления.

Откройте Параметры → Системный журнал и найдите события по времени, requestId, runId и связанным идентификаторам. Безопасный сбор диагностики описан в статье «Параметры и системная диагностика».

При неизвестном физическом результате используйте порядок из статьи «Восстановление печати и устранение ошибок».

В поддержку можно передать:

  • версию приложения;
  • время запроса и часовой пояс;
  • обезличенный URL без секрета;
  • HTTP-статус и код ошибки;
  • requestId и runId, если они получены;
  • выбранные режимы аутентификации и сообщения;
  • обезличенную структуру JSON и шаги воспроизведения.

Не передавайте Basic-пароль, API-ключ, заголовок Authorization, рабочий JSON с персональными данными, лицензионные или закрытые ключи.

Контрольный список готовности

  • ☐ Используется стабильное имя источника и проверенный внешний URL.
  • ☐ Рабочий контур использует HTTPS.
  • ☐ Выбрана аутентификация Basic или API-ключ с отдельным секретом.
  • ☐ Режим «Один объект» или «Массив объектов» соответствует клиенту.
  • ☐ JSON плоский и содержит только необходимые поля.
  • ☐ Типы, null и значения по умолчанию проверены.
  • ☐ Условия отбора испытаны на подходящей и неподходящей записи.
  • ☐ Поля перепривязаны в шаблоне после изменения контракта.
  • ☐ Маршрут, принтер, формат и количество копий проверены.
  • ☐ Отправитель сохраняет requestId, runId и бизнес-идентификатор.
  • ☐ Автоматический повтор POST не создаёт неконтролируемые дубли.
  • ☐ Проверены ответы 202, 400, 401, 404 и 503.
  • ☐ Оператор знает, где контролировать очередь, журнал и системные события.

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