Что формируется автоматически
UBC Data Bridge формирует технический HTML-справочник точки API из сохранённых настроек. Он описывает фактический адрес, формат данных, поля, правила проверки, параметры, ответы и действующие лимиты. Автор потока и интегратор работают с единым контрактом при изменении схемы или способа выполнения.
Для приёма примеры учитывают формат тела или файлов, тестовые данные, обязательные поля и уникальные ключи. Для выдачи — сохранённые результаты или запуск по запросу, формат ответа, фильтры и страницы. Справочник показывает состояние точки: сохранение черновика не означает, что изменения уже действуют в Production.
1. Подготовьте контракт точки
- Назовите подключение и поток так, чтобы партнёр понимал набор данных, например «Остатки магазинов — тест».
- Завершите настройку адреса и формата. Для приёма введите небольшой правильный пример, обновите поля и проверьте типы, обязательность и ключи.
- Для выдачи подключите нужный результат, выберите режим и опишите параметры понятными словами. Уточните, какие обязательны.
- Сохраните настройки подключения и блока. Выполните просмотр и симуляцию, устраните ошибки и опубликуйте согласованную версию потока.
- После изменений откройте справочник снова. Сверьте адрес, состояние Production и пример ответа с тем, что должен использовать клиент.
2. Откройте справочник и предоставьте доступ
Используйте «Техническая документация» в свойствах API-блока или сохранённого подключения выдачи. «API → Документация» показывает доступные точки. Маршрут справочника блока — /api/flows/{flow}/blocks/{node}/api-docs; подключения выдачи — /api/connections/{connection}/api-docs; каталога — /api/api-docs. Добавьте префикс установки.
Для открытия справочника нужен вошедший пользователь Data Bridge. Доступ имеет редактор потока или пользователь с правом роли «API-документация», который видит поток. Один API-ключ HTML-справочник не открывает. Публичная выдача данных не делает справочник публичным. Предоставьте интегратору подходящую учётную запись, а ключ запросов передайте отдельно.
3. Настройте клиента по примерам
Начните с «Быстрого старта»: скопируйте адрес и настройте Postman или curl. Справочник включает примеры Python и пояснения аутентификации. Если соответствующие API-клиенты требуют HMAC, появляются инструкции подписи; следуйте настройкам своего ключа. «Копировать» рядом с адресом и кодом переносит пример без ручного переписывания.
Подставьте тестовые значения и свой ключ в защищённой локальной среде. Справочник не содержит секретов клиентов. Для JSON сохраняйте структуру и путь массива; для CSV — разделитель и заголовки; для файлов — способ передачи и имя. Не подменяйте формат запроса форматом тестовых данных: это независимые настройки.
4. Проверьте успех и ожидаемые отказы
Для приёма отправьте небольшой правильный запрос, дождитесь завершения доставки и сверьте результат получателя. Затем проверьте отсутствие обязательного поля, неправильный тип, повтор уникального ключа и повторную доставку с тем же Idempotency-Key. Отказ должен быть понятен клиенту, а повтор не должен создавать дополнительный запуск.
Для выдачи проверьте первую и следующую страницы, обязательный фильтр, пустой отбор и устаревшие данные. В режиме выполнения переходите по next с фиксированным run.id до завершения. Отдельно проверьте недействительный ключ, запрещённый поток и лимит частоты. Запишите HTTP-статус, код ошибки, доставку/запуск и ожидаемое число строк.
5. Поддерживайте рабочий контракт
Сопоставляйте неудачный запрос с «Настройки → API → Аудит запросов» или «Запросы API» в меню блока. Проверяйте метод, направление, статус, длительность и ответ. Сохранение тел зависит от настроек аудита: в них могут быть бизнес-данные, поэтому выбирайте нужный объём записи и хранения.
Таблица лимитов справочника показывает действующие значения: размер запроса, очередь, ожидание, размер страницы и другие настройки точки. После изменения лимитов откройте её снова. Входные данные доставки очищаются после завершения; история запусков и аудит имеют свои правила хранения. При изменении контракта партнёра используйте новую версию адреса и согласуйте переход, сохранив старую на время миграции.