Wie lässt sich BigCommerce zur Bestellsynchronisierung mit Salesforce CRM integrieren?

Wenn Sie einen auf BigCommerce basierenden Online-Shop und ein Vertriebsteam haben, das mit Salesforce arbeitet, ist die Wahrscheinlichkeit groß, dass die beiden Systeme nicht miteinander kommunizieren. Bestellungen werden im Shop aufgegeben, und niemand auf der CRM-Seite sieht sie, es sei denn, jemand kopiert die Daten manuell hinüber. Diese Lücke führt zu versäumten Nachfassaktionen, unübersichtlichen Berichten und einem Vertriebsteam, das den tatsächlichen Aktivitäten der Kunden immer einen Schritt hinterherhinkt.

In diesem Blogbeitrag wird erklärt, wie Sie diese Verbindung tatsächlich von Anfang bis Ende herstellen können, sodass eine neue Bestellung in BigCommerce automatisch in Salesforce angezeigt wird – mit echten Daten, auf deren Grundlage Ihr Team handeln kann.

Was hier tatsächlich passiert

Bevor Sie Code schreiben, ist es hilfreich, den Ablauf in einfachen Worten darzustellen:

1. Ein Kunde gibt eine Bestellung bei BigCommerce auf.
2. BigCommerce löst einen Webhook aus, der Ihrer Middleware mitteilt: „Es ist gerade eine Bestellung eingegangen.“
3. Ihre Middleware ruft die vollständigen Bestelldetails über die API von BigCommerce ab.
4. Sie wandelt diese Daten in ein Format um, das Salesforce versteht.
5. Sie überträgt diese Daten mithilfe der Salesforce-REST-API an Salesforce.

Das ist im Großen und Ganzen der Ablauf. Im Folgenden geht es lediglich darum, diese fünf Schritte korrekt umzusetzen.

Schritt 1: Einrichten eines API-Kontos in BigCommerce

Bevor Ihre Middleware Bestelldaten abrufen kann, müssen Sie auf der BigCommerce-Seite einen API-Zugang einrichten. Dazu müssen Sie Folgendes tun:

• Erstellen Sie ein API-Konto. Gehen Sie in Ihrem BigCommerce-Kontrollpanel zu „Einstellungen“, dann zu „API-Konten“ und erstellen Sie ein neues API-Konto für diese Integration.
• Wählen Sie die richtigen Berechtigungsbereiche aus. Gewähren Sie dem Konto mindestens Lesezugriff auf „Bestellungen“. Wenn Sie auch Kundendaten (Name, E-Mail-Adresse, Rechnungsdaten) benötigen, fügen Sie zusätzlich Lesezugriff auf „Kunden“ hinzu.
• Speichern Sie Ihre Anmeldedaten. Bei der Erstellung des Kontos erhalten Sie drei Angaben: eine Client-ID, ein Client-Secret und ein Zugriffstoken. Speichern Sie diese an einem sicheren Ort, beispielsweise in Umgebungsvariablen, und nicht direkt in Ihrem Code.
• Verwenden Sie das Zugriffstoken für API-Aufrufe. Dieses Token übermitteln Sie im „X-Auth-Token“-Header bei jeder Anfrage, die Ihre Middleware an BigCommerce sendet.

Das war es auch schon von dieser Seite. Die API-Konten von BigCommerce lassen sich einfacher einrichten als die von Salesforce, da kein separater OAuth-Ablauf konfiguriert werden muss. Das von Ihnen generierte Token ist sofort einsatzbereit.

Schritt 2: Authentifizierung in Salesforce einrichten

Hier gehen die meisten Integrationen schief, wenn man sie überstürzt. Verwenden Sie für eine Server-zu-Server-Integration wie diese keine Anmeldeabläufe mit Benutzernamen und Passwort. Nutzen Sie stattdessen den OAuth 2.0-Ablauf „Client Credentials“, der mit einer externen Client-App in Salesforce verknüpft ist. Salesforce hat sich bei dieser Art der Server-zu-Server-Authentifizierung von der älteren „Connected App“-Konfiguration verabschiedet. Es lohnt sich daher, auf dem aktuellen Ansatz aufzubauen, anstatt auf dem, der ausläuft. So richten Sie dies ein:

1. Erstellen Sie in der Salesforce-Konfiguration eine neue externe Client-App.
2. Aktivieren Sie die OAuth-Einstellungen und wählen Sie für Ihre Integration den Geltungsbereich „Benutzerdaten über APIs verwalten (api)“ aus.
3. Legen Sie die Callback-URL fest. Diese hängt davon ab, welche Organisation Sie einrichten:
   • Produktions-/Entwicklerorganisation: https://login.salesforce.com/services/oauth2/success
   • Sandbox-Organisation: https://test.salesforce.com/services/oauth2/success
4. Aktivieren Sie unter „Flow-Aktivierung“ den „Client-Anmeldeinformationen“-Flow und speichern Sie ihn.
5. Aktivieren Sie nun auf der Registerkarte „Richtlinien“ den „Client Credentials“-Flow und wählen Sie einen „Run as“-Benutzer aus (den Benutzer, der auf die API zugreifen wird).
6. Generieren Sie anschließend auf der Registerkarte „Einstellungen“ den Consumer-Schlüssel und das Consumer-Geheimnis. Diese fungieren wie Ihre Client-ID und Ihr Client-Geheimnis für Salesforce.

In Ihrer Middleware benötigen Sie die Client-ID und das Client-Geheimnis, um das access_token zu erhalten. Dieses access_token verwenden Sie für die Salesforce-REST-API.

async function getSalesforceToken() {
  const response = await fetch(
    'https://your-instance.salesforce.com/services/oauth2/token',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        grant_type: 'client_credentials',
        client_id: process.env.SF_CLIENT_ID,
        client_secret: process.env.SF_CLIENT_SECRET,
      }),
    }
  );

  const data = await response.json();
  return data.access_token;
}

Eines sollten Sie schon frühzeitig wissen: Wenn bei Ihren API-Aufrufen jemals der Fehler „INVALID_SESSION_ID“ auftritt, liegt die Ursache fast immer entweder in einem abgelaufenen Token, einer Nichtübereinstimmung des Gültigkeitsbereichs in der externen Client-App oder einer IP-Beschränkung, die Ihren Server blockiert. Überprüfen Sie diese drei Punkte in dieser Reihenfolge, bevor Sie davon ausgehen, dass etwas anderes nicht stimmt.

Schritt 3: Richten Sie einen Webhook in BigCommerce ein

Anstatt BigCommerce alle paar Minuten abzufragen, ob bereits neue Bestellungen vorliegen, lassen Sie sich von BigCommerce benachrichtigen, sobald etwas passiert. Dafür sind Webhooks da. Dieser Schritt findet vollständig auf der BigCommerce-Seite statt – Sie teilen BigCommerce lediglich mit, wohin eine Benachrichtigung gesendet werden soll.

Registrieren Sie einen Webhook für das Ereignis „store/order/created“ und verweisen Sie dabei auf einen Endpunkt in Ihrer Middleware:

async function registerWebhook() {
  await fetch('https://api.bigcommerce.com/stores/{store_hash}/v3/hooks', {
    method: 'POST',
    headers: {
      'X-Auth-Token': process.env.BC_ACCESS_TOKEN,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      scope: 'store/order/created',
      destination: 'https://your-middleware.com/webhooks/bigcommerce/order',
      is_active: true,
    }),
  });
}

BigCommerce ruft nun jedes Mal diese URL auf, wenn eine neue Bestellung eingeht. Die Webhook-Nutzlast selbst ist sehr klein – meist handelt es sich lediglich um eine Bestell-ID –, daher besteht die Aufgabe Ihres Endpunkts darin, diese ID zu erfassen und die vollständige Bestellung abzurufen.

Schritt 4: Die vollständigen Bestelldetails aus BigCommerce abrufen

Der Webhook teilt dir mit, dass eine Bestellung vorliegt. Er liefert dir jedoch nicht alle Details. Noch immer auf der BigCommerce-Seite benötigst du einen Folgeaufruf, um die tatsächlichen Bestelldaten abzurufen:

async function getOrderDetails(orderId) {
  const response = await fetch(
    `https://api.bigcommerce.com/stores/{store_hash}/v2/orders/${orderId}`,
    {
      headers: {
        'X-Auth-Token': process.env.BC_ACCESS_TOKEN,
        Accept: 'application/json',
      },
    }
  );
  return response.json();
}

async function getOrderLineItems(orderId) {
  const response = await fetch(
    `https://api.bigcommerce.com/stores/{store_hash}/v2/orders/${orderId}/products`,
    {
      headers: {
        'X-Auth-Token': process.env.BC_ACCESS_TOKEN,
        Accept: 'application/json',
      },
    }
  );
  return response.json();
}

In der Regel benötigst du beide Aufrufe: einen für den Bestellkopf (Kunde, Summen, Status) und einen für die Einzelposten (was tatsächlich gekauft wurde).

Schritt 5: Salesforce vorbereiten und die Daten zuordnen

Dies ist eher eine geschäftliche als eine technische Entscheidung, die Sie gründlich durchdenken sollten, bevor Sie mit dem Programmieren beginnen. Dazu gehören auch einige Einrichtungsschritte in Salesforce selbst, nicht nur in Ihrer Middleware.

Salesforce-Seite

Stellen Sie sicher, dass jedes Produkt, das Sie auf BigCommerce verkaufen, einen entsprechenden „Product2“-Datensatz und einen „PricebookEntry“ in Salesforce hat. Stellen Sie außerdem sicher, dass Sie eine Möglichkeit haben, für jeden Kunden das richtige Konto zu ermitteln – in der Regel durch Abgleich anhand der E-Mail-Adresse.

Middleware (Zuordnung der Daten)

Ein sauberer Ansatz besteht darin, jede BigCommerce-Bestellung dem Standard-Objekt „Order“ in Salesforce zuzuordnen, wobei jedes gekaufte Produkt zu einem „OrderItem“ wird. Auf diese Weise bleibt die Struktur mit der nativen Vorstellung von Bestellungen in Salesforce im Einklang, anstatt ein Pipeline-Objekt für etwas umzufunktionieren, das eigentlich keine Verkaufschance mehr ist, sondern bereits eine abgeschlossene Transaktion darstellt.

Ein Punkt, den es zu beachten gilt: Ein Salesforce-Auftrag muss mit einem Konto und einer Preisliste verknüpft sein, bevor er aktiviert werden kann. Ihre Middleware benötigt also eine Möglichkeit, das richtige Konto zu ermitteln (in der Regel durch Abgleich der E-Mail-Adresse des Kunden mit einem bestehenden Konto oder Kontakt) sowie eine Preisliste für die Preisberechnung.

function mapOrderToSalesforceOrder(order, accountId, pricebookId) {
  return {
    AccountId: accountId,
    Pricebook2Id: pricebookId,
    Status: 'Draft',
    EffectiveDate: order.date_created,
    Description: `Synced from BigCommerce order #${order.id}`,
  };
}

function mapLineItems(lineItems, salesforceOrderId, pricebookEntryMap) {
  return lineItems.map((item) => ({
    OrderId: salesforceOrderId,
    PricebookEntryId: pricebookEntryMap[item.sku],
    Quantity: item.quantity,
    UnitPrice: parseFloat(item.price_inc_tax),
  }));
}

Besonders hervorzuheben ist die „pricebookEntryMap“. Salesforce-Auftragspositionen akzeptieren keinen freitextlichen Produktnamen und Preis, wie dies bei Opportunity-Einzelposten möglich ist. Sie benötigen eine „PricebookEntryId“, was bedeutet, dass für jedes Produkt, das Sie auf BigCommerce verkaufen, bereits ein passendes „Product2“ und ein „PricebookEntry“ in Salesforce eingerichtet sein müssen. Wenn sich Ihr Katalog häufig ändert, lohnt es sich, einen kleinen Synchronisierungsjob zu erstellen, der die Salesforce-Produkte und Preislisteneinträge mit BigCommerce auf dem neuesten Stand hält, damit dieser Zuordnungsschritt bei neuen SKUs nicht fehlschlägt.

Schritt 6: Daten in Salesforce übertragen

Mit dem Token aus Schritt 2 und den zugeordneten Daten aus Schritt 5 erfolgt die eigentliche Übertragung auf der Salesforce-Seite über einen einfachen REST-Aufruf:

async function createSalesforceOrder(token, orderData) {
  const response = await fetch(
    'https://your-instance.salesforce.com/services/data/v60.0/sobjects/Order',
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${token}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(orderData),
    }
  );
  return response.json();
}

Sobald der Auftrag angelegt ist, erhalten Sie dessen Salesforce-ID, die Sie dann zum Anlegen der einzelnen Auftragspositionen verwenden, um diese mit dem entsprechenden Datensatz zu verknüpfen. Aufträge werden standardmäßig im Status „Entwurf“ angelegt. Nachdem die Einzelposten hinzugefügt wurden, sollten Sie daher in der Regel den Status des Auftrags aktualisieren (beispielsweise auf „Aktiviert“), damit er sich wie ein abgeschlossener Datensatz verhält und nicht im Entwurfsstatus verbleibt.

Alles zusammenfassen

Der gesamte Ablauf sieht nach der Einrichtung wie folgt aus:

app.post('/webhooks/bigcommerce/order', async (req, res) => {
  res.status(200).send('OK'); // acknowledge fast, process after

  const orderId = req.body.data.id;
  const order = await getOrderDetails(orderId);
  const lineItems = await getOrderLineItems(orderId);

  const token = await getSalesforceToken();
  const accountId = await resolveAccount(token, order.billing_address.email);
  const pricebookId = process.env.SF_DEFAULT_PRICEBOOK_ID;

  const orderData = mapOrderToSalesforceOrder(order, accountId, pricebookId);
  const salesforceOrder = await createSalesforceOrder(token, orderData);

  const pricebookEntryMap = await getPricebookEntryMap(token, pricebookId);
  const lineItemData = mapLineItems(lineItems, salesforceOrder.id, pricebookEntryMap);
  for (const item of lineItemData) {
    await createOrderItem(token, item);
  }

  await activateOrder(token, salesforceOrder.id);
});

Beachten Sie, dass die Antwort sofort zurückgesendet wird, noch bevor die eigentliche Verarbeitung stattfindet. Webhook-Anbieter, darunter auch BigCommerce, erwarten eine schnelle Antwort und können einen erneuten Versuch unternehmen oder den Webhook als fehlgeschlagen markieren, wenn Sie zu lange brauchen. Führen Sie die eigentliche Arbeit erst durch, nachdem Sie den Empfang bestätigt haben.

Ein paar praktische Tipps

Protokollieren Sie alles, zumindest am Anfang. Wenn eine Bestellung nicht in Salesforce erscheint, möchten Sie genau wissen, welcher Schritt fehlgeschlagen ist: Wurde der Webhook nie ausgelöst, ist der BigCommerce-Abruf fehlgeschlagen, ist das Token abgelaufen oder wurde der Salesforce-Aufruf selbst abgelehnt? Gute Protokolle verwandeln eine verwirrende Fehlersuche in eine fünfminütige Korrektur.

Gehen Sie bei Wiederholungsversuchen geschickt vor. Webhooks können gelegentlich mehrmals für dasselbe Ereignis ausgelöst werden. Bevor Sie einen neuen Auftrag anlegen, prüfen Sie, ob für diese Auftrags-ID bereits einer existiert, und nutzen Sie dazu ein externes ID-Feld im Auftrag, um diesen nachzuverfolgen.

Verwenden Sie Postman während der Entwicklung. Bevor Sie irgendetwas in den Live-Code integrieren, testen Sie jeden API-Aufruf zunächst manuell: Rufen Sie eine Bestellung aus BigCommerce ab, holen Sie sich ein Token von Salesforce und erstellen Sie eine Testbestellung. So lassen sich fehlerhafte Bereiche oder fehlerhafte Payloads viel leichter erkennen, bevor sie sich tief in Ihrem Integrationscode verbergen.

Achten Sie auf Ihre Ratenbegrenzungen. Beide Plattformen haben API-Ratenbegrenzungen. Wenn Sie ein hohes Auftragsvolumen synchronisieren, führen Sie Ihre Salesforce-Schreibvorgänge über die Composite-API im Batch-Verfahren durch, anstatt für jeden Datensatz eine einzelne Anfrage zu senden.

Fazit

Die Anbindung von BigCommerce und Salesforce ist nicht kompliziert, sobald Sie den Vorgang in folgende Schritte unterteilen: Authentifizierung bei BigCommerce, Authentifizierung bei Salesforce, Abfangen des Webhooks, Abrufen der vollständigen Bestellung, Zuordnung der Daten und Übermittlung. Der kniffligste Teil ist in der Regel nicht der Code, sondern die Entscheidung, wie Ihre Bestelldaten so auf die Salesforce-Objekte abgebildet werden sollen, dass dies tatsächlich zur Arbeitsweise Ihres Vertriebsteams passt. Stellen Sie zunächst den grundlegenden Ablauf sicher und fügen Sie dann, sobald Sie wissen, dass die Synchronisierung korrekt funktioniert, die Wiederholungsbehandlung, die Protokollierung und die rate-limit-freundliche Stapelverarbeitung hinzu.

Bitte kontaktieren Sie uns unter wargis@bay20.com/manish@bay20.com oder rufen Sie uns unter +91-9582784309 oder +91-8800519180 an, wenn Sie Unterstützung im Zusammenhang mit BigCommerce benötigen. Sie können auch unsere Website besuchen, um sich über unsere Dienstleistungen zu informieren.