Zum Hauptinhalt springen

Zernio Profiles — externalId = Cockpit centerId

Was​

Beim Verknüpfen eines Zernio-Inbox-Kanals mit einem Center setzt das Cockpit PUT /v1/profiles/{profileId} mit externalId = Cockpit-centerId (UUID), sofern das Profil noch kein anderes externalId trägt.

Zernio-Webhooks liefern daraufhin profiles[] mit { id, externalId }. Ads-Sync- und Review-Events nutzen diese IDs vor der bisherigen Zuordnung über zernioAccountId / Kampagnen-Heuristik (rückwärtskompatibel, wenn profiles fehlt oder externalId null ist).

Warum​

  • Multi-Tenant-Routing ohne zusätzliche Lookup-Tabelle (siehe Zernio Multi-Tenant)
  • Präzisere Ads-Sync-Benachrichtigungen, wenn mehrere Center dasselbe Werbe-Account teilen

Wer ist betroffen​

IT/Betrieb (Backfill, Env), Entwickler (Webhook-Handler), später Redaktion indirekt über korrekte Center-Zuordnung bei Vendor-Events.

Wo​

KomponentePfad
Profile-Clientapps/dashboard/src/lib/integration/zernio-profiles-client.ts
Webhook-Routingapps/dashboard/src/lib/integration/zernio-webhook-tenant-routing.ts
Inbox-Link + Syncmap-zernio-inbox-to-center-social.ts, social-zernio-account-link.ts
Ads-Webhookzernio-webhook-handler.ts
Backfill (optional)apps/dashboard/scripts/backfill-zernio-profile-external-ids.ts

Env: ZERNIO_API_KEY (unverändert).

So testen​

  1. Center mit Outstand-Kanal: Social → Auto-Link Zernio oder manuelle Inbox-Zuordnung.
  2. In Zernio (oder GET /v1/profiles?externalId=<centerId>): Profil zeigt externalId = Center-UUID.
  3. pnpm exec tsx --tsconfig apps/dashboard/tsconfig.json --test apps/dashboard/src/lib/integration/zernio-webhook-tenant-routing.test.ts
  4. Webhook-Test aus Zernio; Payload mit profiles[].externalId → Ads-Sync nur für dieses Center (wenn Mapping existiert oder Schnittmenge).

Backfill (bestehende Verknüpfungen)​

cd apps/dashboard
pnpm exec tsx scripts/backfill-zernio-profile-external-ids.ts # Dry-Run
pnpm exec tsx scripts/backfill-zernio-profile-external-ids.ts --apply # Schreibt nur leere/konforme Profile

Überschreibt kein fremdes externalId — Konflikte werden geloggt (409 profile_external_id_conflict).

Grenzen​

  • Portfolio-Werbekonto: Ein gemeinsames Meta-Ads-Profil kann nicht pro Center ein eigenes externalId tragen; Ads-Events ohne passendes profiles.externalId fallen auf die bisherige center_ads_accounts-Heuristik zurück.
  • Epic 2 (Meta Ad Review UI) baut darauf auf, ist aber separat.

Siehe auch: Social-Vendor-Webhooks · Social unter Cockpit.

Nutzungsstatistik: Seitenaufrufe werden anonymisiert erfasst. Im Umami-Dashboard nach diesem Pfad filtern: /developer-guide/social-zernio-profiles-external-id