Quickstart для владельцев проектов¶

Цель: за полчаса настроить сквозной приём данных от одного поставщика и принять первую валидную поставку. Пример ниже — FIBU import (немецкая Hausverwaltung, бухгалтерия). Та же структура подходит для любого домена.

Страница нарочно идёт по верхам — каждый шаг ссылается на подробное how-to. Если сначала хочется освоить терминологию, читайте Концепции.

Что нужно¶

Org Admin пригласил вас в организацию с ролью Project Owner или выше.
Вы знаете, в каком виде хотите получить данные на выходе — какие колонки ожидает целевая система.
Один пример файла хотя бы от одного поставщика, чтобы можно было сквозно проверить на реальном входе.

Ссылки на консоль ниже подразумевают, что вы залогинены в свой инстанс Expecto. API-ссылки подразумевают, что $EXPECTO_BASE_URL и $EXPECTO_API_KEY установлены — как в Quickstart для разработчиков.

Шаг 1 — Создать Project¶

Project объединяет всё под один кейс приёма: entity, контракты, трансформеры, бизнес-правила, экспорт, поставщиков.

В консоли: Projects → Create Project. Имя — например FIBU 2026, плюс короткое описание. Оставьте по умолчанию Approval Mode (Dual Approval) и Session Creation (Both), если нет осознанной причины менять.

Диалог Create Project с заполненными именем и описанием

Новый проект сразу появляется в списке:

Список проектов с созданным проектом FIBU 2026

Или через API:

curl -sS -X POST \
  -H "X-API-Key: $EXPECTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "FIBU 2026", "description": "Ежемесячный приём бухгалтерии"}' \
  "$EXPECTO_BASE_URL/api/projects" | jq .

Сохраните возвращённый id как PROJECT_ID.

Шаг 2 — Определить целевой Entity¶

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

В консоли: Entities → Add Entity. Назовите его Buchung и дайте короткое описание.

Диалог Create Entity

Откройте entity и опишите колонки (например, konto text, betrag decimal, buchungstext text, belegdatum date). Добавьте хотя бы одно правило валидации, чтобы пайплайн отсекал явно битые строки.

Страница entity со схемой и правилами

Пример правила в expression language (что вы вводите в редактор):

len(konto) == 6 and matches(konto, '^[0-9]+$')

Сообщение:

{"en": "Konto must be 6 digits", "de": "Konto muss 6 Ziffern sein", "ru": "Konto должен быть 6-значным"}

Платформа сама компилирует это в DuckDB-запрос для поиска нарушений; см. Язык выражений (Скоро.) для полного списка операторов и встроенных функций.

То же через API. Правила вложены в свою entity, поэтому id entity идёт в пути (экспортируй его как ENTITY_ID из созданной entity). Поле expression — уже скомпилированный DuckDB SELECT, возвращающий нарушающие строки:

curl -sS -X POST \
  -H "X-API-Key: $EXPECTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "konto_6_digits",
    "level": "error",
    "expression": "SELECT * FROM data WHERE LENGTH(TRIM(konto)) != 6 OR konto !~ '\''^[0-9]+$'\''",
    "message": {"ru": "Konto должен быть 6-значным"}
  }' \
  "$EXPECTO_BASE_URL/api/entities/$ENTITY_ID/rules" | jq .

Шаг 3 — Написать DataContract¶

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

В консоли: откройте вкладку Data Contracts проекта и нажмите New Data Contract. Название — например Hausverwaltung X — FIBU v1, задайте supplier id.

Диалог New Data Contract

Откройте контракт и добавьте Sources — по одной на роль файла. Для FIBU обычно две:

buchungsdatei (CSV, разделитель ;, немецкая кодировка) с колонками Konto, Betrag, Buchungstext, Belegdatum.
saldendatei (CSV) с Konto, Saldo.

На странице контракта есть вкладки Sources, Revisions и Transformers; текущая ревизия сначала в статусе draft, пока вы её не активируете.

Страница контракта с вкладками Sources, Revisions, Transformers

Для каждой source прикрепите Frictionless Table Schema с именами колонок и типами, чтобы структурные ошибки ловились ещё до трансформации.

Или через API:

curl -sS -X POST \
  -H "X-API-Key: $EXPECTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hausverwaltung X — FIBU v1",
    "supplier_id": "hv-x",
    "project_id": "'"$PROJECT_ID"'"
  }' \
  "$EXPECTO_BASE_URL/api/data-contracts" | jq .

Сохраните id как CONTRACT_ID. Эндпоинты sources под контрактом (/api/data-contracts/{id}/sources) позволяют завести каждую роль файла.

До активации контракт находится в draft. Активация фиксирует его как Revision 1 и запускает compatibility-проверку относительно всех трансформеров, ссылающихся на него.

Шаг 4 — Собрать Transformer¶

Transformer мапит sources контракта на entity. Каждая колонка entity получает один mapping-выражение — DuckDB-выражение, ссылающееся на поле source, с возможностью почистить значение (TRIM, LPAD, type cast, dictionary lookup).

В консоли: из Project'а — Transformers → New transformer. Выберите Entity (Buchung) и DataContract revision. Затем по каждой source role введите mapping'и для каждой целевой колонки:

Целевая колонка (Entity)	Mapping (DuckDB-выражение по source)
`konto`	`LPAD(TRIM("Konto"), 6, '0')`
`betrag`	`CAST(REPLACE("Betrag", ',', '.') AS DECIMAL(18,4))`
`buchungstext`	`TRIM("Buchungstext")`
`belegdatum`	`STRPTIME("Belegdatum", '%d.%m.%Y')`

Активируйте трансформер, когда его mapping'и покрывают все обязательные колонки entity.

Через API трансформеры вложены в свой DataContract. Mapping'и идут в mappings_per_role, ключ — source role:

curl -sS -X POST \
  -H "X-API-Key: $EXPECTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Buchung из Hausverwaltung X v1",
    "data_contract_id": "'"$CONTRACT_ID"'",
    "data_contract_revision": 1,
    "entity_id": "'"$ENTITY_ID"'",
    "mappings_per_role": {
      "buchungsdatei": { "...": "объект RoleMapping" }
    }
  }' \
  "$EXPECTO_BASE_URL/api/data-contracts/$CONTRACT_ID/transformers"

Шаг 5 — Настроить экспортный формат¶

На уровне Project'а выставьте output_format под ожидания целевой системы. Встроенные: sap_v46 (SAP Interface V4.6), zip_csv (CSV per-entity внутри zip), excel_workbook. Это и есть то, что будет генериться при approve session.

В консоли: на вкладке Overview проекта найдите Output Format и нажмите Configure. Выберите тип формата и опции (разделитель, кодировка, строка заголовка для CSV-форматов).

Диалог настройки Output Format

Шаг 6 — Пригласить Data Provider¶

Пока вы не выдали поставщику доступ, никто не может присылать данные.

В консоли: откройте вкладку Providers проекта и пригласите поставщика. Выберите (или создайте) организацию-поставщика, затем grant'ните доступ к этому Project'у и к этому конкретному контракту. Поставщик получит письмо с приглашением и при логине увидит специализированный submission view.

Вкладка Providers проекта

Шаг 7 — Разобрать первую сессию¶

Когда поставщик загружает файлы, на вкладке Sessions проекта появляется Session — с отслеживанием по health и стадии пайплайна. Пайплайн прогоняет parse → transform → check автоматически (или по триггеру — зависит от настроек Project'а).

Вкладка Sessions проекта с колонками health и stage

Откройте session и посмотрите:

status и health — на какой стадии и есть ли блокеры?
Tab Violations — построчный список отвергнутых строк по каждому правилу.
Preview — трансформированные строки entity в том виде, в каком они уйдут в целевую систему.

Если всё ок — Confirm и затем Approve. Approve формирует экспортный пакет в выбранном формате.

Если что-то не так:

Оставьте комментарий в session, поставщик увидит.
Reject и попросите перезалить.
Поправьте mapping в Transformer'е (создаёт новую revision) и перезапустите пайплайн против тех же файлов.

Куда двигаться дальше¶

Если хотите…	Идите сюда
Безопасно править правила валидации	Использовать golden sessions для безопасной правки правил — Скоро.
Добавить reconciliation между файлами	Настроить reconciliation — Скоро.
Собрать transformer с dictionary lookups	Собрать Transformer — Скоро.
Управлять несколькими revisions контракта	Активировать revision контракта — Скоро.
Разобраться в доменной модели полностью	Концепции