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

Справочные таблицы, стоящие за каждой страницей интеграций: какие переменные {{ … }} существуют и где, как они рендерятся и что означают поля статусов и ошибок в отчётах сбора и логах доставок.

Плейсхолдеры

Плейсхолдер — это {{ name }} (пробелы внутри скобок допустимы). Имена проверяются при сохранении источника или привязки, поэтому опечатка или переменная, которой нет в этой области, — это 422 с именем в сообщении, а не сюрприз во время выполнения.

Поля envelope — только исходящие привязки

Значения берутся из события, вызвавшего доставку. Используются без пространства имён: {{ session_id }}.

Плейсхолдер	Значение	Пусто на
event_type	например session.checked	—
session_id	UUID сессии	—
organization_id	UUID организации	—
project_id	UUID проекта	—
data_provider_id	UUID поставщика данных	Сессиях без поставщика
data_contract_id	UUID контракта данных	—
period	Период поставки, например 2026-08	—
status	Текущая стадия пайплайна, например checked	—
verdict	passed / warnings / failed — результат автоматических проверок	Событиях до результата проверок (created, uploaded, parsed, transformed)
phase	technical (session.parsed, session.failed на parse), context (session.failed на context_fetch / context_validation), content (session.transformed, session.checked, session.failed на transform / validation_gating / validate / check)	Любом другом событии
parse_error_count	Находки парсинга с severity error по всем файлам (нечитаемый файл считается за одну)	Любом событии, кроме session.parsed и session.failed на parse
parse_warning_count	Находки парсинга с severity warning	Любом событии, кроме session.parsed и session.failed на parse
health	Состояние на дашборде: created, in_progress, blocked, attention, ready, completed	—
run_id	UUID прогона пайплайна	Любом событии не прогона: его несут session.parsed, session.transformed, session.checked и session.failed
occurred_at	Метка времени события в ISO 8601	—
stage	Упавшая стадия: context_validation, context_fetch, parse, transform, validation_gating, validate, check	Любом событии, кроме session.failed
reason	Короткий код сбоя (context_invalid, context_fetch_failed, context_fetch_timeout, parse_error, blocking_violations, …)	Любом событии, кроме session.failed
message	Человекочитаемое пояснение, например какой источник контекста упал и почему; null, если стадия вместо этого оставила находки	Любом событии, кроме session.failed

Детали экспорта (data.export.*) из маппинга недоступны.

context.* — привязки и источники контекста

{{ context.<name> }} для каждого скаляра, объявленного в контекстной схеме проекта (таблицы в _tables недоступны). Значение — то, что контекст сессии содержит на момент доставки или сбора.

• В привязке объявленный скаляр, который сессия так и не задала, рендерится как null — необязательное поле остаётся пустым, запись в required_fields падает с именем поля. Имя, не объявленное в схеме, отклоняется при сохранении.
• В источнике контекста упомянутый скаляр должен уже быть в контексте сессии к началу сбора — передан вызывающей стороной при создании сессии. Значения, произведённые другими источниками того же сбора, недоступны как плейсхолдеры.

session.* — привязки и источники контекста

Три разрешённых атрибута сессии, рендерятся строками:

Плейсхолдер	Значение
session.id	UUID сессии
session.period	Строка периода
session.data_provider_id	UUID поставщика данных или null

Правила рендеринга

• Строка, которая целиком является одним плейсхолдером, заменяется сырым значением — числа остаются числами, null остаётся null.
• Плейсхолдер, встроенный в более длинную строку (FIBU {{ period }}), рендерится как текст.
• Когда цель — SQL (источники PostgreSQL), плейсхолдеры биндятся как параметры; когда JSON (BuiltAPI, Salesforce) — подставляются в JSON-структуру. Никогда — в URL или идентификаторы.
• value_maps (привязки) применяются после рендеринга и до проверки required_fields: запасное значение "*" может заполнить обязательное поле.

Отчёт о сборе контекста

Хранится на сессии как context_fetch_report; показывается на странице сессии и возвращается эндпоинтом повторного сбора.

status	Значение
pending	Сбор в очереди или выполняется. Пайплайн ждёт.
completed	Все источники отработали; контекст объединён и заново провалидирован.
failed	Хотя бы один источник упал. Пайплайн заблокирован до успешного повтора.

По каждому источнику: name, status (ok / error), rows, error_kind, message, overwrote_caller_value.

Ошибки сбора контекста

error_kind	Когда возникает
connection_error	Система недоступна, тайм-аут или ответ 5xx; тайм-аут подключения PostgreSQL.
auth_error	Токен, пароль или учётные данные отклонены; учётные данные не заданы.
query_error	Запрос некорректен или нарушает лимит (плохой id entity, не-SELECT SQL, слишком много строк, тайм-аут оператора, скаляр с несколькими колонками, нет workspace_id).
empty_result	Обязательная цель не получила ни строк, ни значения.

Лог доставок

Доставки исходящих привязок делят таблицу с доставками вебхуков (GET /api/webhook-deliveries?connection_id=…); доставки привязок несут connection_id, project_id и binding_name вместо endpoint_id.

status	Значение
pending	Ждёт следующей попытки; next_retry_at говорит когда.
in_progress	Попытка выполняется.
succeeded	Запись создана; last_response_excerpt содержит id записи во внешней системе.
failed	Dead-letter: попытки исчерпаны или постоянная ошибка.

last_error несёт <kind>: <message>:

Kind	Повтор?	Типичное сообщение
connection_error	да, с backoff	Salesforce returned 503, Token endpoint unreachable: ConnectTimeout
delivery_rejected	нет	Salesforce rejected the record (HTTP 400), Required mapping field(s) resolved to an empty value: …, Query placeholder 'run_id' has no value in this session
auth_error	нет	Token endpoint rejected the credentials (HTTP 400), Salesforce rejected a freshly issued token (HTTP 401)

Сбои до запуска адаптера сохраняются без префикса kind:

last_error	Значение
connection_missing	Подключение удалено или принадлежит другой организации.
connection_inactive	Подключение деактивировано.
binding_missing	Привязка удалена из проекта (или переименована).
binding_inactive	Привязка деактивирована — вручную или автоотключением.
adapter_missing / adapter_not_outbound	У типа подключения нет outbound-адаптера (не должно случаться с провалидированной привязкой).
credential_decrypt_failed	Сохранённый секрет не удалось расшифровать — ротируйте учётные данные.

Расписание повторов

Общее с webhook-эндпоинтами: базовая задержка 30 с, экспоненциальный backoff с потолком 1 ч, jitter на попытку, 6 попыток, затем dead-letter. После 10 dead-letter подряд привязка автоматически отключается; успех сбрасывает счётчик. Вызовы адаптеров обрываются по тайм-ауту 15 с (Salesforce, BuiltAPI).