Einheiten aus der Fertigung

Wenn die Fertigung fertige Batterien zurückmeldet, sollen ihre Seriennummern zu Einheiten in BatteryPass werden, ohne dass jemand sie abtippt. In diesem Ablauf stellt die Middleware mit einem Schlüssel mit Scope import einen Tabellenimport bereit. Das Übernehmen des Imports und das Freigeben seiner Werte bleiben bei Mitgliedern Ihrer Organisation im Portal: Ein Schlüssel kann die Daten vorbereiten, deklarierte Daten gelangen aber nur durch die Entscheidung einer Person in BatteryPass (und, wo Ihre Organisation es eingeschaltet hat, im Vier-Augen-Prinzip).

sequenceDiagram
  participant ERP
  participant MW as Middleware
  participant BP as BatteryPass-API
  participant M as Mitglied im Portal
  ERP->>ERP: Wareneingang buchen, Outbox-Zeile schreiben
  MW->>ERP: Outbox-Zeilen lesen (Seriennummer, GTIN, Datum)
  MW->>BP: createImport mit Datei und Preset (Scope import)
  BP-->>MW: 201 Import, Status uploaded
  MW->>BP: validateImport (Scope import)
  BP-->>MW: 202 Prüfauftrag
  loop alle paar Sekunden
    MW->>BP: getImport (Scope import)
  end
  BP-->>MW: Status validated, Zusammenfassung
  MW->>ERP: Zeilen als erledigt markieren, Zusammenfassung melden
  M->>BP: Prüfbericht lesen, Import übernehmen
  M->>BP: importierte Werte freigeben
  M->>BP: Pässe veröffentlichen

VorbereitungLink zum Abschnitt kopieren

• Eine Inhaberin oder ein Inhaber legt unter Einstellungen → API-Schlüssel einen Schlüssel nur mit dem Scope import an, zum Beispiel MES Linie 2 Importe. Er kann weder Ihre Pässe lesen noch Zustandsdaten melden noch etwas übernehmen.
• Die Batteriemodelle gibt es in BatteryPass mit GTIN oder Modellkennung, und eine Modellversion deckt die Herstelldaten ab, die Sie senden. Der Import findet das Modell jeder Zeile über GTIN, Modellkennung oder Produktname.
• Wählen Sie eine Importvorlage (Preset), die zu dem passt, was Ihre Middleware schreibt. Die Vorlage generic-csv nimmt die Spalten GTIN, Seriennummer, Herstelldatum, Produktionsstätte (Name oder GLN), Modellversion und Batteriestatus, auf Deutsch oder Englisch. ERP-spezifische Vorlagen (SAP, Business Central, Odoo, NetSuite) stehen auf der jeweiligen ERP-Seite.

1. Datei schreibenLink zum Abschnitt kopieren

Die Middleware sammelt die Seriennummern einer Charge aus ihrer Outbox und schreibt eine CSV-Datei (UTF-8, getrennt durch ;, ,, Tabulator oder |) oder eine XLSX-Datei mit den Spaltennamen der Vorlage. Höchstens 10 MB, 10 000 Zeilen und 200 Spalten je Datei. Spalten, die die Vorlage nicht kennt, bleiben ohne Zuordnung; zusätzliche Spalten schaden also nicht.

GTIN;Seriennummer;Herstelldatum;Produktionsstätte
04012345000023;SV2027-000901;2026-10-23;Werk Landshut
04012345000023;SV2027-000902;2026-10-23;Werk Landshut

2. Mit der Vorlage hochladenLink zum Abschnitt kopieren

createImport nimmt die Datei als multipart/form-data im Feld file und die Vorlage im Feld preset. Die Antwort ist der Import mit der Zuordnung aus der Vorlage:

curl -sS -X POST "$BATTERYPASS_URL/api/v1/imports" \
  -H "Authorization: Bearer $BATTERYPASS_IMPORT_KEY" \
  -F "file=@charge-2026-10-24.csv;type=text/csv" \
  -F "preset=generic-csv"

{
  "id": "0192f3c1-7a2b-7c3d-8e4f-5a6b7c8d9e0f",
  "status": "uploaded",
  "filename": "charge-2026-10-24.csv",
  "format": "csv",
  "row_count": 2,
  "headers": ["GTIN", "Seriennummer", "Herstelldatum", "Produktionsstätte"],
  "mapping": [
    { "column": 0, "header": "GTIN", "target": "identification.gtin" },
    { "column": 1, "header": "Seriennummer", "target": "identification.serial_number" },
    { "column": 2, "header": "Herstelldatum", "target": "identification.manufacturing_date" },
    { "column": 3, "header": "Produktionsstätte", "target": "identification.manufacturing_place" }
  ],
  "options": {},
  "preset": "generic-csv",
  "created_by_api_key": { "id": "0192f0aa-1b2c-7d3e-8f40-5a6b7c8d9e01", "name": "MES Linie 2 Importe" },
  "created_at": "2026-10-24T06:05:11Z",
  "updated_at": "2026-10-24T06:05:11Z",
  "row_version": 1
}

Der Import nennt den Schlüssel in created_by_api_key; Mitglieder sehen ihn in der Importliste des Portals als von diesem Schlüssel bereitgestellt.

3. Optional: Optionen setzenLink zum Abschnitt kopieren

Hat die Datei keine Modell- oder keine Produktionsstätten-Spalte, setzen Sie den Wert für alle Zeilen mit updateImportMapping. Die Operation ersetzt die Zuordnung; senden Sie also die Vorlage erneut (oder ein vollständiges mapping, nie beides) und If-Match mit der row_version des Imports:

curl -sS -X PUT "$BATTERYPASS_URL/api/v1/imports/0192f3c1-7a2b-7c3d-8e4f-5a6b7c8d9e0f/mapping" \
  -H "Authorization: Bearer $BATTERYPASS_IMPORT_KEY" \
  -H 'If-Match: "1"' \
  -H "Content-Type: application/json" \
  -d '{"preset": "generic-csv", "options": {"facility_id": "0192f09e-4a5b-7c6d-9e8f-0a1b2c3d4e5f"}}'

Wurde der Import inzwischen geändert, lautet die Antwort 409 conflict: Lesen Sie ihn mit getImport neu und wiederholen Sie mit der neuen row_version.

4. Prüfen lassen und wartenLink zum Abschnitt kopieren

validateImport startet einen Auftrag, der jede Zeile mit den Prüfregeln des Portals prüft und Seriennummern findet, die sich in der Datei wiederholen oder schon existieren. Fragen Sie getImport ab, bis status den Wert validated hat (oder failed, wenn die Datei nicht gelesen werden konnte):

curl -sS -X POST "$BATTERYPASS_URL/api/v1/imports/0192f3c1-7a2b-7c3d-8e4f-5a6b7c8d9e0f/validate" \
  -H "Authorization: Bearer $BATTERYPASS_IMPORT_KEY"

curl -sS "$BATTERYPASS_URL/api/v1/imports/0192f3c1-7a2b-7c3d-8e4f-5a6b7c8d9e0f" \
  -H "Authorization: Bearer $BATTERYPASS_IMPORT_KEY" | jq '{status, summary}'

{
  "status": "validated",
  "summary": { "rows": 2, "valid": 2, "warnings": 0, "errors": 0, "duplicates": 0, "created": 0, "approved": 0, "not_approved": 0 }
}

Markieren Sie die Outbox-Zeilen als erledigt, sobald der Import geprüft ist, und senden Sie die Zusammenfassung an die Fertigung. Zeilen mit Fehlern oder Duplikaten werden nicht importiert; Mitglieder sehen jede mit Zeile, Spalte und Grund im Portal.

5. Mitglieder übernehmen, geben frei und veröffentlichenLink zum Abschnitt kopieren

Ab hier geschieht die Arbeit im Portal, nie mit einem Schlüssel:

1. Eine Bearbeiterin oder ein Bearbeiter öffnet den Import, liest den Prüfbericht und übernimmt ihn. Die Einheiten entstehen als Entwürfe, ihre Werte tragen die Quelle import.
2. Eine Prüferin oder ein Prüfer gibt die importierten Werte in einem Schritt frei. Werte mit einer fehlschlagenden Prüfung, ohne geforderten Nachweis oder mit einer Importwarnung bleiben zur Einzelprüfung offen; mit eingeschaltetem Vier-Augen-Prinzip auch Werte, die die prüfende Person selbst erfasst hat.
3. Eine Prüferin oder ein Prüfer veröffentlicht die Pässe, sobald keine Pflichtangabe mehr fehlt.

Der Änderungsfeed meldet import.committed, battery.created, import.approved und später passport.published; das ERP erfährt so von jedem Schritt, ohne die Menschen zu fragen.

FehlerbehandlungLink zum Abschnitt kopieren

Der Status failed bedeutet, dass die Datei bei der Prüfung nicht gelesen werden konnte: Laden Sie eine korrigierte Datei als neuen Import hoch.