Abonnenten gewinnen (QR-Code)

Ein Abonnement entsteht nicht über die API — es entsteht in der App, weil ein Mensch zustimmt. Dein Teil daran ist ein Link: er nennt die App, um die es geht, und optional eine eigene Kennung, an der du das Abonnement später wiedererkennst. Als QR-Code gedruckt ist dieser Link der ganze Anmeldeweg.

Der Link

usenotification://subscribe/{appId}
usenotification://subscribe/{appId}?state={eigeneKennung}

Ein fertiger Link sieht so aus:

usenotification://subscribe/66bcfadc12ab34cd56ef7890?state=auftrag-4711

Warum state der interessante Teil ist

Ohne ihn weißt du, dass jemand abonniert hat. Mit ihm weißt du, wer — in deinen Begriffen, nicht in unseren. Was du hineinschreibst, bekommst du unverändert zurück:

Damit wird aus einem QR-Code auf einem Auftragszettel eine Verbindung: Auftrag 4711 hat abonniert, also gehen die Statusmeldungen zu Auftrag 4711 an genau dieses Abonnement.

Zwei Regeln dazu:

• Nichts Geheimes hineinschreiben. Ein QR-Code ist öffentlich lesbar, und der Link landet im Klartext auf dem Gerät. Eine Auftragsnummer ist in Ordnung, ein Token nicht.
• Eindeutig halten, wenn du zuordnen willst. Derselbe state auf zwei Zetteln liefert zwei Abonnements, die du nicht mehr unterscheiden kannst.

Kein state ist auch eine Antwort: ein Aufsteller im Ladenlokal, ein Aufkleber am Regal, ein Plakat — dort abonniert man die App, nicht einen Vorgang.

Den QR-Code erzeugen

Der Code enthält den Link als Text, nichts weiter. Jede Bibliothek reicht; Fehlerkorrektur M und mindestens 2 cm Kantenlänge im Druck sind ein guter Ausgangspunkt.

Node

import QRCode from "qrcode";

const appId = "66bcfadc12ab34cd56ef7890";
const link = `usenotification://subscribe/${appId}?state=${encodeURIComponent("auftrag-4711")}`;

await QRCode.toFile("abo-4711.png", link, { errorCorrectionLevel: "M", margin: 2, width: 512 });

Python

import qrcode
from urllib.parse import quote

app_id = "66bcfadc12ab34cd56ef7890"
link = f"usenotification://subscribe/{app_id}?state={quote('auftrag-4711')}"

qrcode.make(link).save("abo-4711.png")

Shell

qrencode -o abo-4711.png -l M -s 8 \
  "usenotification://subscribe/66bcfadc12ab34cd56ef7890?state=auftrag-4711"

encodeURIComponent beziehungsweise quote ist keine Zierde: ein Leerzeichen oder ein & in deiner Kennung zerlegt sonst den Link.

Was beim Scannen passiert

1. Das Gerät öffnet den Link, die App fängt ihn ab.
2. Ist niemand angemeldet, landet der Nutzer auf der Anmeldung — und der Link ist danach verbraucht. Er muss den Code nach dem Anmelden erneut scannen. Rechne bei einem Aushang damit; ein Satz daneben („App installieren, anmelden, dann scannen") erspart die Rückfragen.
3. Ist er angemeldet, legt die App das Abonnement an und kehrt zur Übersicht zurück.
4. Derselbe Link innerhalb von 30 Sekunden erzeugt kein zweites Abonnement — die App erkennt die Wiederholung.

Ab diesem Moment steht das Abonnement in GET /v1/subscribers der Abonnenten-API, und du kannst mit der Nachrichten-API an es senden.

Prüfen, ob es angekommen ist

curl "https://subscribers.api.usenotification.artim-industries.com/v1/subscribers?app=66bcfadc12ab34cd56ef7890" \
  -H "Authorization: Bearer unapi_…"

{
  "data": [
    {
      "id": "66c0aa11…",
      "appId": "66bcfadc12ab34cd56ef7890",
      "createdAt": "2026-08-21T10:00:00",
      "sessionId": "auftrag-4711",
      "pushTokens": 2,
      "webhook": true
    }
  ],
  "total": 1
}

pushTokens: 0 heißt: abonniert, aber kein Gerät erreichbar — dann ist in der App die Push-Berechtigung nicht erteilt. Die Nachricht steht trotzdem im Verlauf.

Schneller als zu fragen ist zuhören: hinterlege in der App einen Webhook, dann meldet sich jedes neue Abonnement mit event: "subscription_created" samt sessionId von selbst bei dir.

Wenn nichts passiert