partner library

Partner-API: alles, was ein Partner-Softwarehaus über die Kasseneck-Schnittstelle tut — Betriebe anlegen und bis zur laufenden Kasse begleiten, danach in ihrem Namen Belege signieren.

Einstieg ist PartnerApi. Sie steht bewusst neben KasseneckApi: der Partner-Schlüssel (pk_live_…) gehört auf einen Server, KasseneckApi braucht dagegen den api_key eines einzelnen Betriebs.

Was die Endpunkte tun, steht in der Referenz des Backends — docs/api/partner.md (ausführlich) und docs/api/partner.llms.txt (kompakt, für Werkzeuge und Sprachmodelle). Dieses Paket wiederholt sie nicht; hier steht die Benutzung.

Die Reihenfolge der Kette steht als Daten in kPartnerAblauf, die Fehlercodes samt Handlungssatz in partnerFehlerRat, die erlaubten Betriebsfelder in kBetriebFelder.

Der Zwilling in JavaScript ist @kreiseck/kasseneck-api/partner.

Classes

AblaufSchritt
Ein Schritt der Kette.
AvvStand
Stand des Auftragsverarbeitungsvertrags eines Betriebs.
Betrieb
BetriebListe
BetriebZeile
Eine Zeile der Betriebsliste.
BetriebZugangsdaten
Die beiden Geheimnisse, die eine App braucht, um im Namen des Betriebs Belege zu signieren.
FonLinkErgebnis
Kasse
KasseneckSecret
KassenFehler
KassenInbetriebnahme
KassenListe
KassenSchritt
KassenZugang
Eine Kasse samt ihrem Token. Der Token ist ein Geheimnis des Betriebs -- deshalb steht er als KasseneckSecret und nicht als String darin.
NeueKasse
NeuerBetrieb
Das Ergebnis von createPartnerCustomer.
NeuerWebhook
PartnerApi
PartnerApp
PartnerFeldFehler
Ein Feldfehler aus data.errors[] einer validation-Antwort.
PartnerInfo
PartnerSchluesselInfo
PartnerTransport
PartnerWebhook
PartnerWebhookEreignis
Die Huelle jeder Zustellung.
SignaturAntrag
Ein Signaturantrag.
SignaturAntragErgebnis
SignaturFehler
SignaturHistorieEintrag
SignaturKopf
Zeitstempel und Signaturanteile aus dem Kopf.
SignaturStand
WebhookEreignisErgebnis
Das Ergebnis von leseWebhookEreignis: entweder das Ereignis, oder genau ein Ablehnungsgrund.
WebhookEreignisKatalog
WebhookListe
WebhookPruefung
Das Ergebnis der Pruefung. Entweder ist sie durch -- dann steht der Zeitstempel fest --, oder sie nennt genau einen Grund.
WebhookTestErgebnis
WebhookZustellung

Enums

PartnerEnv
Umgebung, in der ein Partner-Schluessel bzw. ein Betrieb lebt.
WebhookAblehnung
Warum eine Zustellung abgelehnt wurde. Jeder Grund ist ein Nein.

Constants

kBetriebFelder → const List<String>
Jedes erlaubte Feld als Pfad. [] markiert eine Liste -- im Fehlerpfad des Servers steht dort der Index (contacts.0.name).
kPartnerAblauf → const List<AblaufSchritt>
Die Kette in ihrer Reihenfolge. Sie beschreibt den Live-Weg; mit einem pk_test_-Schluessel entfallen die FinanzOnline-Schritte, und die Signatur ist sofort bereit (AT100-Testkarte -- die damit erzeugten Belege sind keine gueltigen RKSV-Belege).
kPartnerBaseUrl → const String
Basis-Adresse der Partner-API.
kPartnerEnvs → const List<String>
Die beiden Umgebungen als Namen, in der Reihenfolge des Backends (partner-core.ENVS). Bewusst eine eigene Liste und nicht PartnerEnv.values: die Reihenfolge einer Aufzaehlung ist eine Schreibweise, die des Vertrags eine Zusage.
kPartnerFehlerCodes → const List<String>
Alle Codes, die die Schnittstelle kennt. Als Liste und nicht nur als Aufzaehlung, damit ein Aufrufer sie zur Laufzeit durchgehen kann (Katalogseite, Selbsttest der eigenen Fehlerbehandlung).
kPartnerPortalFehlerCodes → const List<String>
Die Codes, die nur im Partner-Portal entstehen -- beim Pflegen der App, der Schluessel, der Mitglieder und der Signaturkarten.
kPartnerWebhookEreignisse → const List<String>
Alle Ereignisse, die ein Webhook abonnieren und proben kann. Ein Endpunkt bekommt ausschliesslich die, die in seiner events-Liste stehen.
kScopeCredentials → const String
credentials:read gehoert nicht zum Standardsatz und wird keinem bestehenden Schluessel nachtraeglich hinzugefuegt: wer ihn hat, kann im Namen fremder Betriebe Belege signieren. Dafuer wird ein eigener Schluessel angelegt.
kSecretMaske → const String
Wie ein maskiertes Geheimnis in Text erscheint.
kWebhookEreignisKopf → const String
Der Kopf mit dem Ereignisnamen (dasselbe wie body.type).
kWebhookFrist → const Duration
So lange wartet Kasseneck auf eine 2xx-Antwort.
kWebhookLimit → const int
Hoechstzahl der Webhook-Endpunkte je Partner.
kWebhookMaxVersuche → const int
Erstversuch plus je eine Wiederholung pro Planeintrag.
kWebhookSignaturKopf → const String
Der Kopf, in dem die Signatur steht.
kWebhookToleranzSek → const int
Erlaubte Abweichung des Zeitstempels, in Sekunden (in beide Richtungen).
kWebhookUmschlagFelder → const List<String>
Die Felder des Umschlags, so wie er auf der Leitung liegt.
kWebhookWiederholungSek → const List<int>
Wartezeiten zwischen den Zustellversuchen, in Sekunden.
kWebhookZustellungKopf → const String
Der Kopf mit der Zustell-Kennung -- bei Wiederholungen dieselbe.

Functions

alsJaNein(Object? wert, [bool rueckfall = false]) → bool
alsListe(Object? wert) → List
alsMap(Object? wert) → Map<String, dynamic>
alsMapOderNull(Object? wert) → Map<String, dynamic>?
alsSecret(String label, Object? wert) → KasseneckSecret
Baut ein Geheimnis aus einem Antwortfeld; fehlt es, entsteht ein leeres.
alsText(Object? wert, [String rueckfall = '']) → String
alsTexte(Object? wert) → List<String>
alsTextOderNull(Object? wert) → String?
alsZahlOderNull(Object? wert) → int?
envAus(Object? wert) → PartnerEnv
envName(PartnerEnv env) → String
Der Name, unter dem die Umgebung ans Backend geht (env-Parameter).
fehlerDetails(Object? daten, List<String> geheimnisse) → Map<String, dynamic>
Siebt das data einer Fehlerantwort zu einer Form, die man gefahrlos an einem Fehler mitfuehren kann.
gleichZeitkonstant(List<int> a, List<int> b) → bool
Vergleich ohne frueh Abbrechen. Die Laengenpruefung davor verraet nur die Laenge des Hashs, und die ist bekannt (SHA-256, 32 Bytes); der Inhalt wird immer vollstaendig durchlaufen.
hexZuBytes(String hex) → List<int>?
Hex zu Bytes; null bei ungerader Laenge oder Nicht-Hex.
istPartnerFehler(Object? fehler, String code) → bool
Kurzform fuer catch (e) { if (istPartnerFehler(e, 'signature_missing')) ... }.
istPartnerFehlerCode(Object? wert) → bool
istPartnerPortalFehlerCode(Object? wert) → bool
istPartnerWebhookEreignis(Object? wert) → bool
leseSignaturKopf(String kopf) → SignaturKopf?
Zerlegt den Signaturkopf. null, wenn kein brauchbarer Zeitstempel oder gar kein v1=-Anteil darin steht.
leseWebhookEreignis({required List<String> secrets, required String? signaturKopf, required List<int> rumpf, int? jetztSek, int toleranzSek = kWebhookToleranzSek}) → WebhookEreignisErgebnis
Prueft die Signatur und liest das Ereignis -- in dieser Reihenfolge. Wer zuerst liest und dann prueft, hat den fremden Rumpf schon durch seinen Code laufen lassen.
naechsterSchritt(String status) → AblaufSchritt?
Der Schritt, an dem ein Betrieb mit diesem Status steht -- null fuer gesperrt und fuer jeden Status, den dieses Paket nicht kennt.
partnerFehlerCode(Object? fehler) → String?
Der Fehlercode eines gefangenen Fehlers -- null, wenn es keiner der unseren ist.
partnerFehlerRat(String code) → String?
Der Handlungssatz zu einem Code -- aus beiden Flaechen. null fuer einen Code, den dieses Paket nicht kennt; ein erfundener Satz waere schlimmer als keiner.
partnerFeldFehler(Object? fehler) → List<PartnerFeldFehler>
Die Feldfehler einer validation-Antwort; leer, wenn es keine sind.
partnerSchluesselEnv(String schluessel) → String?
Die Umgebung eines Partner-Schluessels, ohne Netzaufruf -- null, wenn es keiner ist. Nuetzlich fuer die Zusicherung "auf diesem Server laeuft nur pk_live_" beim Hochfahren.
partnerWartezeitSek(Object? fehler) → int?
Wie lange rate_limited noch gilt, in Sekunden. null, wenn der Fehler kein rate_limited ist oder das Backend keine Angabe macht.
pruefeWebhookSignatur({required List<String> secrets, required String? signaturKopf, required List<int> rumpf, int? jetztSek, int toleranzSek = kWebhookToleranzSek}) → WebhookPruefung
Prueft die Signatur einer eingehenden Zustellung.
pruefeWebhookSignaturText({required List<String> secrets, required String? signaturKopf, required String rumpf, int? jetztSek, int toleranzSek = kWebhookToleranzSek}) → WebhookPruefung
Bequemlichkeit fuer Empfaenger, die den Rumpf schon als Zeichenkette haben.
unbekannteBetriebsfelder(Object? betrieb) → List<String>
Die Feldpfade eines Betriebs, die kBetriebFelder nicht kennt -- dieselben Pfade, die der Server in data.errors[].field nennen wuerde. Leer heisst: aus dieser Sicht ist nichts ueberzaehlig.

Exceptions / Errors

KasseneckApiError
Fachlicher Fehler des Backends (PIN falsch, Kasse belegt, Geraet gesperrt ...).
KasseneckHttpError
Die Antwort war keine brauchbare Huelle {status, data} oder der HTTP-Weg scheiterte. Traegt bewusst nichts aus dem Rumpf: dort koennten Werte stehen, die wir gerade nicht ins Protokoll lassen wollen.
KasseneckValidationError
Der Aufrufer hat etwas nicht mitgegeben, oder die Antwort trug nicht, was der Aufruf zusagt. Die Meldung nennt immer nur das Feld, nie seinen Wert — sonst stuende ein Geraetegeheimnis im Protokoll.