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

Обзор оставляет вас с живым движком. Эта страница — остальные первые два часа: файл входит, кто-то его проверяет, и подписанные строки приходят на ваш бэкенд.

Вы не пишете UI сопоставления и не объявляете схему в коде хоста. Схема — это опубликованный каталог. Виджет его загружает. Apply — подписанный вебхук; так по умолчанию.

  your page                         Mildport engine                    your backend
  ─────────                         ───────────────                    ────────────
  <mildport-import                  ingest → match → review
   catalog-key="crm">   ─────────►                          ─────────►  POST /apply
                                                                    HMAC-signed rows

1. Ключи из аккаунта

Нужны два значения, оба из вашего аккаунта Mildport:

Что	Где	Куда
Ключ лицензии	Лицензии — один раз при выпуске	license-key виджета
Публичный ключ	Self-hosting (IMPORT_LICENSE_PUBLIC_KEY)	движок, уже, если preflight обзора прошёл

Подтвердите, что движок принимает ключ:

curl -H "Authorization: Bearer $LICENSE" \
  https://imports.your-infra.example/api/import/v1/license/verify

Хороший ответ — "verified": true. Всё остальное — см. Устранение неполадок развёртывания.

2. Опубликовать каталог, затем встроить

Схема живёт в редакторе каталогов — /admin/catalogs на движке или <mildport-catalog-editor> в вашем админе. Набросайте поля из OpenAPI-спеки или примера записи, пометьте required те, что API отверг бы пустыми, и опубликуйте. Дайте каталогу стабильный ключ (crm, contacts, …).

Закрепите этот ключ на виджете. Дальнейшие изменения схемы — publish в редакторе, не релиз хоста:

<mildport-import
  api-base-url="https://imports.your-infra.example"
  license-key="SIGNED_TENANT_KEY"
  catalog-key="crm"
></mildport-import>

Один опубликованный каталог и без catalog-key тоже нормально — виджет возьмёт его сам. Закрепляйте ключ, когда страница всегда должна импортировать в конкретную схему.

Схема считается на пользователя в рантайме или версионируется с приложением? Это путь схема-как-код. Пропустите, пока нет причины.

3. Зарегистрировать apply-вебхук

Apply по умолчанию — подписанный POST на ваш бэкенд. Зарегистрируйте URL один раз; ответ несёт секрет подписи ровно один раз — сохраните его.

curl -X POST https://imports.your-infra.example/api/import/v1/webhooks \
  -H "Authorization: Bearer $LICENSE" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://api.your-app.example/mildport/apply" }'

Первый взгляд без бэкенда? el.applyMode = 'browser' и читайте строки из onResults. Продакшен — вебхук. Подробности: События и apply и справочник вебхуков.

4. Запустить импорт

Откройте страницу, бросьте CSV (или беспорядочную таблицу, или PDF с таблицей), подтвердите предложенное сопоставление, поправьте то, что пометит сетка проверки, и apply.

Виджет говорит с движком для ingest и сопоставления. Вы сами ingest не вызываете, если только не строите headless-поток без виджета.

5. Проверить подпись, затем писать

Каждая доставка подписана HMAC. Проверяйте сырое тело до того как доверять, отвергайте устаревшие метки времени и дедуплицируйте по x-import-delivery-id — повторы нормальны.

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(',').map(kv => kv.split('=')));
  const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
  const got = Buffer.from(parts.v1 ?? '', 'hex');
  const exp = Buffer.from(expected, 'hex');
  return got.length === exp.length && timingSafeEqual(got, exp);
}

Тело — строки в форме вашего каталога (contact.email, …) плюс mapping. Верните 2xx, когда сохранили их. 4xx окончателен; 5xx повторяется. Полезная нагрузка и заголовки: Apply-вебхуки.

6. Подтвердить, что сработало

• Виджет выстрелил import-applied с rowCount.
• Обработчик залогировал один deliveryId и записал столько строк.
• Вторая доставка с тем же id у вас — no-op.

Застряли? Устранение неполадок развёртывания закрывает образы, которые не pull-ятся, 401 лицензии, CORS и под, который никогда не становится Ready.

Дальше: Конфигурация · Лицензирование · Каталоги