HelpYa für Entwickler

HelpYa Kassen-API

Mit drei Aufrufen bekommt jede Kasse einen digitalen Pager: Bestellung anlegen, QR-Code auf den Bon drucken, bei „fertig“ Bescheid geben. HelpYa benachrichtigt den Gast auf seinem Handy – ohne App, ohne Telefonnummer – und meldet Ihrer Kasse per Webhook zurück, ob der Alarm angekommen ist.

Maschinenlesbar: OpenAPI 3.1 · Fragen: kontakt@helpya.com

1. Schlüssel holen

Der Betrieb meldet sich unter helpya.com/login an und erzeugt unter „Kassenanbindung“ einen Kassen-Schlüssel (beginnt mit hy_). Er gilt für genau diesen Betrieb. Zum Entwickeln genügt ein eigener Betrieb im kostenlosen Gratis-Tarif – schreiben Sie uns, wir richten ihn ein.

curl https://helpya.com/api/v1/betrieb \
  -H "Authorization: Bearer hy_…"

2. Bestellung anlegen

Am besten direkt beim Bezahlen. Geben Sie Ihre Bon- oder Bestellnummer als referenz mit – dann ist der Aufruf wiederholbar (gleiche Referenz → gleiche Bestellung, keine doppelte Nummer) und Sie können später über Ihre eigene Nummer zugreifen.

curl -X POST https://helpya.com/api/v1/bestellungen \
  -H "Authorization: Bearer hy_…" \
  -H "Content-Type: application/json" \
  -d '{"referenz": "B-4711"}'

Antwort (gekürzt):

{
  "nummer": "042",
  "referenz": "B-4711",
  "status": "offen",
  "url": "https://helpya.com/b/…",
  "qr_svg": "https://helpya.com/qr/….svg"
}

Drucken Sie nummer und einen QR-Code von url auf den Bon. Der Gast scannt ihn und aktiviert den Alarm. Ohne QR-Drucker: Der Gast holt sich seine Nummer am HelpYa-Aufkleber, die Nummer erscheint trotzdem in Ihrer Kasse (Webhook bestellung.angelegt).

3. Fertig melden

curl -X POST https://helpya.com/api/v1/bestellungen/B-4711/fertig \
  -H "Authorization: Bearer hy_…"

Alle Aufrufe

Aufruf	Zweck
`GET /betrieb`	Schlüssel prüfen
`POST /bestellungen`	anlegen (`referenz`, optional `nummer`, `ohne_handy`)
`GET /bestellungen?status=offen`	Bestellungen von heute
`GET /bestellungen/{referenz}`	eine Bestellung (auch über die heutige Nummer)
`POST /bestellungen/{referenz}/fertig`	Gast alarmieren
`POST /bestellungen/{referenz}/erneut`	noch einmal alarmieren
`POST /bestellungen/{referenz}/vorab`	Vorab-Bescheid, Rumpf `{"minuten": 10}`
`POST /bestellungen/{referenz}/abgeholt`	abschließen
`POST /bestellungen/{referenz}/storno`	offene Bestellung löschen

Basis-Adresse: https://helpya.com/api/v1 · Fehler kommen als JSON {"fehler": "…", "code": 404} · 409 = Aktion im aktuellen Zustand nicht möglich · höchstens 600 Aufrufe pro Minute und Betrieb.

Felder einer Bestellung

status: offen → fertig → abgeholt (oder storniert)
gast_verbunden: der Gast hat seinen Link geöffnet
alarm_zugestellt: das Handy hat den letzten Alarm bestätigt
bitte_aufrufen: Alarm kam nicht an – zeigen Sie das an, das Personal ruft dann die Nummer aus
angelegt, fertig, abgeholt, bereit_um: ISO 8601, Zeitzone Europe/Berlin

Webhooks

Im Kundenbereich hinterlegt der Betrieb eine HTTPS-Adresse Ihrer Kasse. HelpYa schickt dorthin bei jedem Zustandswechsel einen POST:

{"ereignis": "bestellung.zugestellt", "zeit": 1790000000, "bestellung": { … wie oben … }}

Ereignisse: bestellung.angelegt, .vorab, .fertig, .zugestellt (Alarm kam an), .abgeholt, .storniert. Antworten Sie mit 2xx; sonst versuchen wir es nach 10 s und 60 s erneut. Die Reihenfolge der Zustellung ist nicht garantiert – maßgeblich ist der status im Rumpf (im Zweifel mit GET /bestellungen/{referenz} nachsehen).

Signatur prüfen: Header HelpYa-Signatur: t=<unix>,v1=<hex>. v1 ist HMAC-SHA256 mit Ihrem Webhook-Geheimnis (whsec_…) über <t>.<Rumpf>. Verwerfen Sie Aufrufe, deren t älter als 5 Minuten ist.

# Python
import hmac, hashlib, time
def echt(kopf, rumpf: bytes, geheimnis: str) -> bool:
    teile = dict(x.split("=", 1) for x in kopf.split(","))
    if abs(time.time() - int(teile["t"])) > 300:
        return False
    soll = hmac.new(geheimnis.encode(), f'{teile["t"]}.'.encode() + rumpf, hashlib.sha256).hexdigest()
    return hmac.compare_digest(soll, teile["v1"])

// Node.js
const crypto = require("crypto");
function echt(kopf, rumpf, geheimnis) {
  const t = Object.fromEntries(kopf.split(",").map((x) => x.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t.t)) > 300) return false;
  const soll = crypto.createHmac("sha256", geheimnis).update(`${t.t}.${rumpf}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(soll), Buffer.from(t.v1));
}

Datenschutz

Übergeben Sie keine Namen, Telefonnummern oder Bestellinhalte – HelpYa braucht nur Nummer und Referenz. Bestellungen werden 24 Stunden nach der Abholung anonymisiert; danach liefern die Aufrufe 404. HelpYa verarbeitet die Daten im Auftrag des Betriebs (Auftragsverarbeitungsvertrag).

Impressum · Datenschutz · AGB