Diese API dient der Entwicklung eigener Scanner-Software zur gemeinsamen Erfassung von Gutscheinkarten über mehrere Geräte hinweg – etwa durch die Kopplung von Mobilgeräten und Desktop-Software während einer Tauschaktion.

Ihr könnt unsere API kostenfrei nutzen, wenn ihr eine eigene Scan-Software zur Guthabenabfrage für eure Tauschaktionen entwickelt und eure Geräte untereinander koppeln wollt. Wenn ihr Fragen habt, wendet euch per E-Mail an uns.

Wenn ihr einfach Gutscheine im Team scannen wollt und nichts selber programmieren, könnt ihr unsere fertige Scansoftware hier verwenden.

Basis-URL:
https://kartentausch-herzo.de/js/scannerAPI.php

📌 Anwendungsfall

Während einer Tauschaktion kann ein Team von Geräten (z. B. Handys + Laptops) eine gemeinsame Session starten:

• Ein Mastergerät startet die Session und erhält eine connectionID und deviceID.
• Diese connectionID ist 3 Stunden lang gültig und kann an weitere Geräte weitergegeben werden.
• Jedes Gerät erhält automatisch eine eindeutige Farbe für die visuelle Unterscheidung.

🔧 Parameter-Übersicht

• connectionID: Verbindungs-ID der Session [String]
• deviceID: ID des aktiven Geräts [String]
• addEntry oder updateEntry: Gutscheinnummer (Barcode oder QR-Code) [Integer]
• type: Supermarkt (z. B. Rewe, Aldi, Lidl, Edeka, dm ...) [String]
• value: Guthaben auf der Gutscheinkarte [Double]

🧪 Beispiele zur Nutzung

1. 🔄 Neue Tausch-Session starten (Mastergerät)

./scannerAPI.php?createConnection=true

Response:

{
  "success": true,
  "message": "Neue Verbindung erstellt.",
  "data": {
    "connectionID": "con1",
    "deviceID": "dev1"
  }
}

2. ➕ Weiteres Gerät in bestehende Session einloggen

./scannerAPI.php?connectionID=con1&addScanner=true

Response:

{
  "success": true,
  "message": "Neues Gerät hinzugefügt.",
  "data": {
    "deviceID": "dev2"
  }
}

3. 📋 Gespeicherte Gutscheine & Geräte abfragen

./scannerAPI.php?connectionID=con1&deviceID=dev2&onlyMyEntries=false

onlyMyEntries=true zeigt nur Einträge vom aktuellen Gerät.

4. 🆕 Gutscheinkarte scannen (z. B. am Handy)

Erfasst eine neue Gutscheinkarte ohne das Guthaben zu kennen – typischerweise auf einem Mobilgerät.

Zum Hinzufügen von Karten wird die DeviceID, die Kartennummer und der Name des Supermarkts benötigt!

./scannerAPI.php?connectionID=con1&deviceID=dev2&addEntry=954733298472&type=Rewe

5. ✏️ Guthaben oder Pin erfassen (z. B. am Laptop)

Ergänzt das zuvor gescannte Guthaben und/oder Pin zu einer zuvor gescannten Karte – z. B. am Laptop nach der Guthabenabfrage.

Gutscheine können in einem Request erstellt und mit Werten gefüllt werden, in dem beide Parameter addEntry und setEntry angegeben werden.

./scannerAPI.php?connectionID=con1&deviceID=dev1&setEntry=954733298472&value=25.00&pin=1234

📦 Rückgabeformat (Beispiel)

{
  "success": true,
  "message": "Eintrag aktualisiert.",
  "data": {
    "entries": {
      "954733298472": {
        "type": "Rewe",
        "timestamp": 1745005389,
        "value": "25.00",
        "pin": "1234",
        "device": "dev2"
      }
      "829265876454376654": {
        "type": "Kaufland",
        "timestamp": 1745005431,
        "value": "",
        "pin": "",
        "device": "dev1"
      }
    },
    "devices": {
      "dev1": {
        "os": "Ubuntu 41 x64",
        "browser": "Firefox 137.0",
        "ip": "12.34.56.78",
        "lastActive": 1745004351,
        "color": "#0E00CC"
      },
      "dev2": {
        "os": "Windows 10 x64",
        "browser": "Firefox 135.0",
        "ip": "98.76.53.32",
        "lastActive": 1745005389,
        "color": "#C500CC"
      }
    }
  }
}

⚙️ Technische Details

• Sessions (connectionID) verfallen nach 3 Stunden Inaktivität und werden gelöscht
• Geräte (deviceID), die mehrere Minuten inaktiv sind, werden automatisch entfernt und müssen sich neu verbinden
• Jedes Gerät erhält eine eindeutige Farbe (HEX), um in der UI unterscheidbar zu sein
• Die Daten werden verschlüsselt (SSL) übertragen und nach Beendigung der Session vom Server gelöscht

📲 Ideal für...

• Entwickler:innen eigener Scanner-Apps für Gutscheinkarten
• Kopplung von Laptop & Smartphone bei einer Tauschaktion
• Teamkoordination bei der Erfassung von Karten in Gruppen