Ihr erster Import, von Ende zu Ende

Der Überblick bringt Sie zu einer gesunden Engine. Diese Seite ist der Rest der ersten zwei Stunden: eine Datei geht hinein, jemand prüft sie, und signierte Zeilen landen auf Ihrem Backend.

Sie schreiben keine Mapping-UI und deklarieren das Schema nicht im Host-Code. Das Schema ist ein veröffentlichter Katalog. Das Widget lädt ihn. Apply ist ein signierter Webhook — das ist der Standard.

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

1. Schlüssel aus Ihrem Konto

Sie brauchen zwei Werte, beide aus Ihrem Mildport-Konto:

Was	Wo	Wohin
Lizenzschlüssel	Lizenzen — einmal beim Ausstellen	license-key des Widgets
Öffentlicher Schlüssel	Self-Hosting (IMPORT_LICENSE_PUBLIC_KEY)	die Engine, bereits, wenn der Preflight des Überblicks durch ist

Prüfen Sie, ob die Engine den Schlüssel annimmt:

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

Eine gute Antwort ist "verified": true. Alles andere — siehe Deployment-Fehlerbehebung.

2. Katalog veröffentlichen, dann einbetten

Das Schema lebt im Katalog-Editor — /admin/catalogs auf Ihrer Engine, oder <mildport-catalog-editor> in Ihrem eigenen Admin. Felder aus einer OpenAPI-Spezifikation oder einem Beispiel-Record entwerfen, alles was Ihre API leer ablehnen würde als required markieren, und veröffentlichen. Geben Sie dem Katalog einen stabilen Schlüssel (crm, contacts, …).

Pinning dieses Schlüssels auf dem Widget. Schema-Änderungen danach sind ein Publish im Editor, kein Host-Release:

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

Ein veröffentlichter Katalog und kein catalog-key ist auch in Ordnung — das Widget übernimmt ihn selbst. Pinnen Sie den Schlüssel, wenn eine Seite immer in ein bestimmtes Schema importieren muss.

Schema zur Laufzeit pro Nutzer berechnet, oder mit der App versioniert? Das ist der Schema-als-Code-Weg. Überspringen Sie ihn, bis Sie einen Grund haben.

3. Apply-Webhook registrieren

Apply ist standardmäßig ein signiertes POST an Ihr Backend. Registrieren Sie die URL einmal; die Antwort trägt das Signatur-Geheimnis genau einmal — speichern Sie es.

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" }'

Erster Blick ohne Backend? el.applyMode = 'browser' und Zeilen aus onResults. Produktion ist der Webhook. Details: Events & Apply und die Webhook-Referenz.

4. Einen Import ausführen

Seite öffnen, CSV ablegen (oder eine unordentliche Tabelle, oder ein PDF mit einer Tabelle), vorgeschlagenes Mapping bestätigen, alles was das Review-Grid markiert korrigieren, Apply.

Das Widget spricht mit Ihrer Engine für Ingest und Mapping. Sie rufen Ingest nicht selbst auf, außer Sie bauen einen Headless-Flow ohne Widget.

5. Signatur prüfen, dann schreiben

Jede Zustellung ist HMAC-signiert. Prüfen Sie den Roh-Body bevor Sie ihm trauen, verwerfen Sie alte Zeitstempel, und deduplizieren Sie auf x-import-delivery-id — Retries sind normal.

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);
}

Der Body sind Zeilen in der Form Ihres Katalogs (contact.email, …) plus ein mapping. 2xx zurückgeben, wenn Sie sie persistiert haben. 4xx ist endgültig; 5xx wird wiederholt. Payload und Header: Apply-Webhooks.

6. Bestätigen, dass es geklappt hat

• Das Widget hat import-applied mit einem rowCount gefeuert.
• Ihr Handler hat eine deliveryId geloggt und so viele Zeilen geschrieben.
• Eine zweite Zustellung mit derselben ID ist auf Ihrer Seite ein No-Op.

Stecken geblieben? Deployment-Fehlerbehebung deckt Images ab, die nicht pullen, Lizenz-401, CORS, und ein Pod, der nie Ready wird.

Weiter: Konfiguration · Lizenzierung · Ziel-Kataloge