Pass-Links zurück ins ERP

Etiketten, Lieferscheine und Servicewerkzeuge in Ihrem ERP brauchen den Link zum Pass jeder Batterie. In diesem Ablauf folgt die Middleware mit einem Schlüssel mit Scope read dem Änderungsfeed von BatteryPass, liest Einheit und Pass und schreibt GS1 Digital Link und Passstatus an den Seriennummernsatz im ERP. In BatteryPass wird nichts geschrieben.

sequenceDiagram
  participant MW as Middleware
  participant BP as BatteryPass-API
  participant ERP
  loop alle paar Minuten
    MW->>BP: listChanges mit gespeichertem Cursor und Passtypen (Scope read)
    BP-->>MW: Änderungen, älteste zuerst, next_cursor
    MW->>BP: getBattery (Scope read)
    MW->>BP: getPassport (Scope read)
    MW->>BP: getPassportQr, wenn ein Etikett nötig ist (Scope read)
    MW->>ERP: Digital Link und Status am Seriennummernsatz speichern
    MW->>MW: next_cursor speichern, nachdem das ERP angenommen hat
  end

Der ÄnderungsfeedLink zum Abschnitt kopieren

GET /api/v1/changes liefert die Änderungen Ihrer Organisation, älteste zuerst. Jede Änderung nennt nur, was geschah und welche Entität betroffen ist; den aktuellen Stand lesen Sie an der Entität.

{
  "items": [
    {
      "id": "0192f6d2-3c4e-7a5b-8c9d-0e1f2a3b4c5d",
      "occurred_at": "2026-10-24T09:12:40Z",
      "entity_type": "battery",
      "entity_id": "0192a3f0-5b7c-7d21-8e4f-6a2b9c1d3e5f",
      "action": "passport.published"
    }
  ],
  "next_cursor": "eyJ4IjoxODQ0MiwiaSI6IjAxOTJmNmQyLTNjNGUtN2E1Yi04YzlkLTBlMWYyYTNiNGM1ZCJ9"
}

Drei Regeln machen das Abfragen verlässlich:

• next_cursor ist gesetzt, sobald die Seite Einträge hat, auch auf der letzten Seite. Speichern Sie ihn und senden Sie ihn beim nächsten Mal. Eine leere Seite hat next_cursor: null: Behalten Sie den gesendeten Cursor.
• Eine Änderung erscheint erst, wenn jede ältere Transaktion beendet ist. Ein Cursor springt deshalb nie über eine Änderung, die spät festgeschrieben wurde. Eine Änderung kann einige Sekunden nach dem Ereignis erscheinen.
• Speichern Sie den Cursor erst, nachdem das ERP die Änderungen der Seite angenommen hat. Nach einem Absturz sehen Sie dieselben Änderungen erneut (mindestens einmal); denselben Link und Status zweimal zu schreiben, schadet nicht.

Abfragen und zurückschreibenLink zum Abschnitt kopieren

curl -sS "$BATTERYPASS_URL/api/v1/changes?types=passport.published,passport.republished,passport.withdrawn&limit=100&cursor=$CURSOR" \
  -H "Authorization: Bearer $BATTERYPASS_READ_KEY"

curl -sS "$BATTERYPASS_URL/api/v1/batteries/0192a3f0-5b7c-7d21-8e4f-6a2b9c1d3e5f/passport" \
  -H "Authorization: Bearer $BATTERYPASS_READ_KEY" | jq '{status, passport_id, gs1_digital_link, version: .current_version.version_no}'

curl -sS -o etikett.svg "$BATTERYPASS_URL/api/v1/batteries/0192a3f0-5b7c-7d21-8e4f-6a2b9c1d3e5f/passport/qr?format=svg" \
  -H "Authorization: Bearer $BATTERYPASS_READ_KEY"

Der Pass trägt, was das ERP braucht: serial_number und gtin, um den Satz zu finden, gs1_digital_link für das Etikett ({resolver}/01/{gtin}/21/{serial}), status (published, update_needed, withdrawn, …), passport_id und current_version.version_no. Ein Etikettendrucker holt den QR-Code mit getPassportQr (format=png mit size oder format=svg); er enthält denselben Digital Link. getBattery ergänzt Modell, Modellversion und Daten, wenn Ihr ERP-Satz sie braucht.

Der erste Lauf ohne Cursor geht durch Ihre gesamte Geschichte; filtern Sie mit types und lassen Sie ihn einmal laufen, bevor Sie ihn einplanen. Wie der Digital Link aufgelöst wird, beschreibt Digital Link auflösen.

Was ins ERP gehörtLink zum Abschnitt kopieren

Nur Digital Link, Passstatus und Versionsnummer. Passinhalte bleiben in BatteryPass: Die öffentliche Seite und das öffentliche JSON hinter dem Digital Link sind immer aktuell, und eingeschränkte Daten dürfen nicht in Systeme mit größerem Leserkreis kopiert werden.

FehlerbehandlungLink zum Abschnitt kopieren