Profile über die API abrufen

Lies Profildaten von bluebarry über die Data API aus und synchronisiere sie in deine eigenen Systeme wie ein Data Warehouse, ein CRM oder ein individuelles Dashboard. bluebarry führt die vielen Touchpoints einer kaufenden Person (eine anonyme Sitzung im Produktquiz, ein späterer identifizierter Besuch, ein zweites Gerät) zu einer einzelnen Identität zusammen. Diese Anleitung zeigt dir, wie du dich authentifizierst, diese Identitäten abrufst und nur Änderungen seit deinem letzten Durchlauf lädst, ohne Datensätze zu verpassen oder zu duplizieren.

Bevor du startest

Du benötigst einen API-Schlüssel. Erstelle einen im Studio unter „Integrations“ und dort unter „API keys“, und kopiere den Schlüsselwert. Ein API-Schlüssel gilt für einen einzelnen Workspace und kann jedes Profil in diesem Workspace lesen. Behandle ihn daher vertraulich und rufe die API nur von einem sicheren Server auf, niemals aus Storefront- oder Browser-Code.

Production   https://data.bluebarry.ai/data
Staging      https://staging.data.bluebarry.ai/data

Authentifizierung

Sende deinen Schlüssel im Authorization-Header. Verwende nur den reinen Schlüsselwert. Füge kein Bearer-Präfix hinzu, da ein Bearer-Token an eine andere Anmeldemethode weitergeleitet und deine Anfrage mit HTTP 401 abgelehnt wird.

curl "https://data.bluebarry.ai/data/Identities?\$top=5" \
  -H "Authorization: bb_your_api_key_here"

Identities oder Profiles

Es gibt zwei verwandte Collections. Nutze Identities, es sei denn, du hast einen konkreten Grund dagegen.

• Identities gibt eine Zeile pro kaufender Person zurück, zusammengeführt aus allen Touchpoints. Jede Zeile besitzt eine feste id, die du speichern und für Upserts nutzen kannst, sowie die aufgelöste E-Mail-Adresse, Telefonnummer, den Namen, Antworten aus dem Produktquiz und personalisierte Produktempfehlungen. Das ist der richtige Endpunkt, um Personen in ein anderes System zu synchronisieren.
• Profiles gibt die rohen, nicht zusammengeführten Zeilen zurück (eine pro Sitzung und Person). Nutze dies nur, wenn du gezielt Details zu einzelnen Sitzungen benötigst. Dieselbe Person kann in mehreren Profiles-Zeilen auftauchen.

Struktur einer Identity

Ein gültiger Schlüssel liefert HTTP 200 mit einem JSON-Envelope zurück. Die Identitäten befinden sich im value-Array. Feldnamen nutzen camelCase. Die Antworten aus dem Produktquiz unter properties und die Produktauswahl unter recommendations werden direkt inline zurückgegeben.

{
  "@odata.context": "https://data.bluebarry.ai/data/$metadata#Identities",
  "value": [
    {
      "id": "0193b8a1-7e2c-7a10-9f4d-2b6f3c8e1a55",
      "email": "[email protected]",
      "phoneNumber": null,
      "firstName": "Alice",
      "lastName": "A",
      "userId": "34d33fe3-e88e-47cd-8b70-d0f978b5bd2a",
      "createdDate": "2026-06-01T10:00:00Z",
      "updatedDate": "2026-06-14T09:12:00Z",
      "memberCount": 3,
      "consentAccepted": true,
      "mergedIntoId": null,
      "properties": [
        { "name": "skill_level", "value": "beginner" }
      ],
      "recommendations": [
        {
          "position": 1,
          "title": "Starter Rope",
          "url": "https://shop.example/rope",
          "quizName": "Climbing Quiz",
          "price": 49.99
        }
      ]
    }
  ]
}

• id ist stabil. Speichere sie und nutze sie für Upserts. Sie ändert sich nicht, wenn neue Sitzungen oder Geräte derselben Person zugeordnet werden.
• memberCount gibt an, wie viele rohe Touchpoints in dieser Identität zusammengeführt wurden.
• mergedIntoId ist normalerweise null. Siehe Zusammenführungen verarbeiten weiter unten.

Felder auswählen, filtern und sortieren

Der Endpunkt akzeptiert die standardmäßigen OData-Abfrageoptionen. Kodiere die Werte für URLs, sodass ein Leerzeichen zu %20 und ein Plus zu %2B wird.

• $select gibt nur die angegebenen Felder zurück, zum Beispiel $select=id,email,updatedDate.
• $filter grenzt die Zeilen ein, zum Beispiel nach updatedDate oder einer E-Mail-Adresse.
• $orderby sortiert die Zeilen. Setze dies bei der Paginierung immer, da die Reihenfolge sonst nicht garantiert ist.
• $count=true fügt ein Feld @odata.count mit der Gesamtzahl hinzu.

Bei Zeitstempeln schließt gt den Grenzwert aus und ge schließt ihn ein. Verwende einen ISO-8601-UTC-Wert wie 2026-06-01T10:10:00Z.

Durch große Ergebnismengen paginieren

Eine einzelne Anfrage gibt maximal 5000 Zeilen zurück. Setze $top, um eine kleinere Seitengröße (1 bis 5000) zu wählen, und $skip, um zur nächsten Seite zu springen, immer in Kombination mit einem stabilen $orderby. Ein Wert für $top außerhalb des Bereichs von 1 bis 5000 liefert HTTP 400. Wenn du $top weglässt und das Ergebnis mehr als 5000 Zeilen umfasst, enthält die Antwort eine @odata.nextLink-URL. Folge dieser URL so lange, bis sie nicht mehr vorhanden ist.

Nur Änderungen synchronisieren, ohne Datensätze zu verpassen

Jede Identität hat ein updatedDate, das aktualisiert wird, sobald die kaufende Person aktiv ist. Um inkrementell zu synchronisieren, merke dir das neueste verarbeitete updatedDate und frage beim nächsten Durchlauf die Identitäten ab, die sich seitdem geändert haben. Führe für jeden Eintrag einen Upsert in dein System anhand der id durch.

Wichtig zu wissen: updatedDate wird gesetzt, wenn ein Event der kaufenden Person erzeugt wird. Die Änderung wird jedoch erst kurz danach geschrieben, und diese Schreibvorgänge treffen nicht garantiert in der Reihenfolge der Zeitstempel ein. Eine Änderung mit einem früheren updatedDate kann also erst sichtbar werden, nachdem du diesen Zeitpunkt bereits ausgelesen hast. Wenn du streng nach Werten filterst, die größer als dein letzter Zeitstempel sind, könntest du Änderungen verpassen. Vermeide das durch ein kleines Überlappungsfenster: Starte jeden Durchlauf kurz vor deinem letzten Zeitstempel (zum Beispiel eine Stunde davor) und lies den überlappenden Zeitraum erneut ein. Da du den Upsert über die id machst, ist das erneute Lesen bereits vorhandener Zeilen unproblematisch.

// cursor ist das neueste updatedDate, das du vollständig verarbeitet hast.
let cursor = loadCursor() ?? "1970-01-01T00:00:00Z";
const OVERLAP_MS = 60 * 60 * 1000; // Sicherheitsfenster von 1 Stunde

async function sync() {
  const from = new Date(Date.parse(cursor) - OVERLAP_MS).toISOString();
  let newest = cursor;
  let skip = 0;

  while (true) {
    const url = new URL("https://data.bluebarry.ai/data/Identities");
    url.searchParams.set("$filter", `updatedDate ge ${from}`);
    url.searchParams.set("$orderby", "updatedDate asc,id asc");
    url.searchParams.set("$top", "1000");
    url.searchParams.set("$skip", String(skip));

    const res = await fetch(url, {
      headers: { Authorization: process.env.BLUEBARRY_API_KEY },
    });
    const { value } = await res.json();
    if (value.length === 0) break;

    for (const identity of value) {
      if (identity.mergedIntoId) {
        // Diese Identität wurde zusammengeführt; führe deine lokale Kopie mit mergedIntoId zusammen.
        redirect(identity.id, identity.mergedIntoId);
      } else {
        upsertById(identity.id, identity); // Idempotent: Erneutes Lesen ist unproblematisch
      }
      if (identity.updatedDate > newest) newest = identity.updatedDate;
    }
    skip += value.length;
  }

  saveCursor(newest); // Erst nach vollständigem Erfolg des Durchlaufs weitersetzen
}

Setze und speichere den Cursor erst, wenn ein Durchlauf erfolgreich abgeschlossen ist. Schlägt ein Durchlauf mittendrin fehl, startet der nächste Durchlauf beim alten Cursor und das Überlappungsfenster deckt alles dazwischen ab.

Zusammenführungen verarbeiten

Gelegentlich stellt sich heraus, dass zwei Identitäten zur selben kaufenden Person gehören. Zum Beispiel hinterlässt ein anonymer Gast später eine E-Mail-Adresse, die bereits bei einer anderen Identität hinterlegt war. In diesem Fall behält bluebarry eine bestehende Identität bei und markiert die andere mit einer mergedIntoId, die auf die verbleibende Identität verweist. Die archivierte Identität erscheint weiterhin im Änderungsfeed, sodass deine Synchronisierung die lokale Kopie der alten id mit der verbleibenden Identität zusammenführen kann. Filtere mit mergedIntoId eq null, wenn du nur aktive Identitäten abrufen möchtest.

Limits und Best Practices

• Frage maximal 5000 Zeilen pro Aufruf ab und paginiere durch den Rest.
• Nutze $select, um nur die benötigten Felder abzurufen. Das hält die Antworten schlank und schnell.
• Identitäten enthalten personenbezogene Daten wie E-Mail-Adresse, Telefonnummer und Name. Speichere und verarbeite sie im Einklang mit deinen Datenschutzpflichten und beachte das Flag consentAccepted.
• Bewahre deinen API-Schlüssel auf dem Server auf. Sollte ein Schlüssel offengelegt werden, lösche ihn im Studio und erstelle einen neuen.