ProfitBoost Custom Shipping Carrier Integration Guide

INHALTSVERZEICHNIS

Einführung
Integration Flow Diagram

1. Anforderungen

2. Initial Setup

3. Live Shipping Rates Implementation

4. Order Syncing & Fulfillment

5. Disconnect & Uninstallation

Einführung

Dieser Guide zeigt, wie du eine Custom Shipping Carrier Integration in ProfitBoost baust.

Damit kannst du:

• eigene Shipping Carrier anbinden

• Live Shipping Rates im Checkout anzeigen

• Fulfillment automatisieren

• Tracking in Orders synchronisieren

  

1. Anforderungen

Technisches Wissen

• Backend Development (Node.js / Python etc.)

• REST APIs

• Webhooks

• OAuth 2.0

Backend Service muss können:

• OAuth Callback von ProfitBoost verarbeiten

• Webhooks empfangen (Orders + Carrier)

• API Calls zu ProfitBoost + Carrier machen

• Frontend UI unterstützen

Datenbank speichert:

• OAuth Tokens (pro Location)

• Carrier API Credentials

• Order ↔ Carrier Mapping

Frontend:

• Carrier Setup UI

• Credential Input

• Settings Management

APIs:

• OAuth Redirect URI

• ProfitBoost Webhook Listener

• Carrier Credential API

• Carrier Webhook Listener

• Live Rates Endpoint

2. Initial Setup

Marketplace App erstellen

In ProfitBoost Marketplace App erstellen

App Settings

• App Type: Sub-Account

• Redirect URI: Backend OAuth Callback

• Webhook URL: Backend Webhook Endpoint

Required Scopes

• orders.readonly

• orders.write

• shipping.readonly

• shipping.write

Frontend UI (Custom Page)

• Carrier Credentials eingeben

• Integration verbinden

• Settings verwalten

User Context Handling

ProfitBoost sendet Location Context (encrypted payload)

const CryptoJS = require('crypto-js')
 
function decryptUserData(encryptedData, sharedSecret) {
  const bytes = CryptoJS.AES.decrypt(encryptedData, sharedSecret)
  return JSON.parse(bytes.toString(CryptoJS.enc.Utf8))
}

Frontend:

async function getUserContext() {
  return new Promise((resolve) => {
    window.addEventListener('message', (event) => {
      if (event.data.message === 'REQUEST_USER_DATA_RESPONSE') {
        resolve(event.data.payload)
      }
    })
 
    window.parent.postMessage({ message: 'REQUEST_USER_DATA' }, '*')
  })
}

Carrier Credentials Handling

• API Key speichern

• LocationId zuordnen

• Test Request zur Validierung

3. Live Shipping Rates Implementation

Carrier registrieren

{
  "altId": "LOCATION_ID",
  "altType": "location",
  "name": "Custom Carrier",
  "callbackUrl": "https://your-backend.com/rates"
}

Live Rates Flow

ProfitBoost sendet:

• origin

• destination

• items

• currency

Backend:

• Carrier API call

• Response transformieren

Response an ProfitBoost:

{
  "rates": [
    {
      "serviceName": "Standard Shipping",
      "amount": 12.99,
      "currency": "USD",
      "estimatedDays": 3
    }
  ]
}

Shipping Zones

• GET shipping-zone

• POST shipping-zones/{zoneId}/rates

Wichtig:

• isCarrierRate = true

• shippingCarrierId setzen

• amount = 0 (Live Rate)

4. Order Syncing & Fulfillment

Webhooks aktivieren

• OrderCreate

• OrderStatusUpdate

Order Flow

1. Order kommt rein

2. OrderDetails holen

3. Carrier Shipment erstellen

4. Mapping speichern

Carrier Tracking Update

Carrier sendet:

• trackingNumber

• status

Backend:

• Order Mapping finden

• Fulfillment in ProfitBoost erstellen

Fulfillment Payload

• trackingNumber

• trackingUrl

• carrierName

• notifyCustomer

5. Disconnect & Uninstallation

App Uninstall Webhook

Wenn User App entfernt:

• Carrier aus DB löschen

• Credentials löschen

• Mapping löschen

ProfitBoost API Call

DELETE /shipping-carrier/{id}