@kreiseck/kasseneck-api 1.35.0 → 1.36.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +31 -9
- package/dist/cjs/client/api.d.ts +15 -1
- package/dist/cjs/client/api.js +4 -0
- package/dist/cjs/client/aufrufe.d.ts +2 -2
- package/dist/cjs/client/aufrufe.js +10 -0
- package/dist/cjs/client/auth.d.ts +9 -3
- package/dist/cjs/client/auth.js +5 -4
- package/dist/cjs/client/ewp.d.ts +125 -0
- package/dist/cjs/client/ewp.js +95 -0
- package/dist/cjs/client/index.d.ts +1 -0
- package/dist/cjs/client/index.js +4 -1
- package/dist/cjs/client/list-deposit-types.d.ts +3 -0
- package/dist/cjs/client/list-deposit-types.js +3 -0
- package/dist/cjs/client/receipts.d.ts +3 -3
- package/dist/cjs/index.d.ts +1 -1
- package/dist/cjs/index.js +4 -2
- package/dist/cjs/invoice/index.d.ts +2 -2
- package/dist/cjs/invoice/index.js +2 -1
- package/dist/cjs/invoice/texte.d.ts +5 -0
- package/dist/cjs/invoice/texte.js +10 -0
- package/dist/cjs/invoice/typen.d.ts +34 -1
- package/dist/cjs/invoice/vertrag.d.ts +13 -4
- package/dist/cjs/invoice/vertrag.js +29 -6
- package/dist/cjs/payments/hobex-hps/connect-client.d.ts +43 -1
- package/dist/cjs/payments/hobex-hps/connect-client.js +51 -1
- package/dist/cjs/payments/hobex-hps/outcome.d.ts +4 -3
- package/dist/cjs/payments/hobex-hps/payments.d.ts +85 -35
- package/dist/cjs/payments/hobex-hps/payments.js +137 -53
- package/dist/cjs/receipt/layout.js +1 -1
- package/dist/cjs/stored/vokabular.d.ts +1 -1
- package/dist/cjs/stored/vokabular.js +1 -1
- package/dist/cjs/version.d.ts +1 -1
- package/dist/cjs/version.js +1 -1
- package/dist/esm/client/api.d.ts +15 -1
- package/dist/esm/client/api.js +4 -0
- package/dist/esm/client/aufrufe.d.ts +2 -2
- package/dist/esm/client/aufrufe.js +10 -0
- package/dist/esm/client/auth.d.ts +9 -3
- package/dist/esm/client/auth.js +5 -4
- package/dist/esm/client/ewp.d.ts +125 -0
- package/dist/esm/client/ewp.js +89 -0
- package/dist/esm/client/index.d.ts +1 -0
- package/dist/esm/client/index.js +1 -0
- package/dist/esm/client/list-deposit-types.d.ts +3 -0
- package/dist/esm/client/list-deposit-types.js +3 -0
- package/dist/esm/client/receipts.d.ts +3 -3
- package/dist/esm/index.d.ts +1 -1
- package/dist/esm/index.js +1 -1
- package/dist/esm/invoice/index.d.ts +2 -2
- package/dist/esm/invoice/index.js +1 -1
- package/dist/esm/invoice/texte.d.ts +5 -0
- package/dist/esm/invoice/texte.js +10 -0
- package/dist/esm/invoice/typen.d.ts +34 -1
- package/dist/esm/invoice/vertrag.d.ts +13 -4
- package/dist/esm/invoice/vertrag.js +28 -5
- package/dist/esm/payments/hobex-hps/connect-client.d.ts +43 -1
- package/dist/esm/payments/hobex-hps/connect-client.js +50 -1
- package/dist/esm/payments/hobex-hps/outcome.d.ts +4 -3
- package/dist/esm/payments/hobex-hps/payments.d.ts +85 -35
- package/dist/esm/payments/hobex-hps/payments.js +138 -54
- package/dist/esm/receipt/layout.js +1 -1
- package/dist/esm/stored/vokabular.d.ts +1 -1
- package/dist/esm/stored/vokabular.js +1 -1
- package/dist/esm/version.d.ts +1 -1
- package/dist/esm/version.js +1 -1
- package/fixtures/hobex-hps-cases.json +654 -0
- package/fixtures/hobex-hps-codes.json +1 -1
- package/fixtures/invoice-api-examples/issue-error-deposit.json +39 -0
- package/fixtures/invoice-api-examples/issue-invoice-deposit.json +55 -0
- package/fixtures/invoice-api.schema.json +65 -2
- package/fixtures/invoice-texts.json +11 -1
- package/fixtures/manifest.json +1 -1
- package/fixtures/pos-texts.json +1 -1
- package/fixtures/receipts/card-hobex-hps.json +1 -1
- package/fixtures/surface.json +13 -4
- package/fixtures/v3/antworten/belege.json +1 -1
- package/fixtures/v3/antworten/belegmail.json +1 -1
- package/fixtures/v3/antworten/berichte.json +1 -1
- package/fixtures/v3/antworten/kasse-belege.json +1 -1
- package/fixtures/v3/antworten/kasse.json +2 -2
- package/fixtures/v3/antworten/lager.json +1 -1
- package/fixtures/v3/antworten/rechnungen.json +1 -1
- package/fixtures/v3/antworten/storno.json +1 -1
- package/fixtures/v3/stored/belege.json +1 -1
- package/fixtures/v3/stored/kasse.json +2 -2
- package/fixtures/v3/stored/rechnungen.json +1 -1
- package/fixtures/v3/v3-vokabular.json +358 -5
- package/fixtures/v3/zahlbetrag-faelle.json +1 -1
- package/package.json +1 -1
|
@@ -79,6 +79,12 @@ export const INVOICE_ERROR_CODES = [
|
|
|
79
79
|
'reservation_not_active', // schon eingeloest oder freigegeben
|
|
80
80
|
// Seit 1.15.0 (Vertrag): die Rechnungsnummer ist schon vergeben (§ 11 Abs. 1 Z 3 lit. h UStG), nichts ausgestellt.
|
|
81
81
|
'invoice_number_taken',
|
|
82
|
+
// Seit 1.36.0 (Vertrag): Pfand an Positionen (`items[].deposit`), hinten angehaengt.
|
|
83
|
+
'deposit_not_enabled', // Pfand ist fuer dieses Konto nicht eingeschaltet
|
|
84
|
+
'deposit_type_not_found', // die Pfandart gibt es nicht (oder ist stillgelegt)
|
|
85
|
+
'deposit_set_by_server', // das Pfand zu einer Artikelposition leitet der Server selbst ab
|
|
86
|
+
'invalid_deposit_quantity', // die Pfandmenge passt nicht zur Menge der Position
|
|
87
|
+
'invalid_deposit', // sonstige Pfandangabe unzulaessig, `index` nennt die Position
|
|
82
88
|
];
|
|
83
89
|
/**
|
|
84
90
|
* Codes, die Anmeldung und Rand auf jedem Rechnungsaufruf erzeugen koennen,
|
|
@@ -447,9 +453,26 @@ export const ITEM_FIELDS = Object.freeze({
|
|
|
447
453
|
*/
|
|
448
454
|
articleId: id,
|
|
449
455
|
});
|
|
456
|
+
/**
|
|
457
|
+
* Pfandangabe an einer Position (seit 1.36.0, `deposit`): die Position ist eine
|
|
458
|
+
* Pfandzeile zu der Position `depositFor` (Index in `items`, 0 bis 499). Gleich
|
|
459
|
+
* dem Feld `DEPOSIT_FELD` des Backends. Zeile fuer Zeile Pfand sendet das
|
|
460
|
+
* Fremdsystem selbst; zu einer Position mit `articleId` leitet der Server das
|
|
461
|
+
* Pfand ab (`deposit_set_by_server`).
|
|
462
|
+
*/
|
|
463
|
+
export const DEPOSIT_ITEM_FIELD = Object.freeze({
|
|
464
|
+
type: 'object',
|
|
465
|
+
required: false,
|
|
466
|
+
fields: Object.freeze({
|
|
467
|
+
depositTypeId: { type: 'string', required: true, min: 1, max: 128 },
|
|
468
|
+
depositFor: { type: 'integer', required: true, min: 0, max: 499 },
|
|
469
|
+
gtin: { type: 'string', required: false, min: 8, max: 14, pattern: '^[0-9]{8,14}$' },
|
|
470
|
+
ownFilling: { type: 'boolean', required: false },
|
|
471
|
+
}),
|
|
472
|
+
});
|
|
450
473
|
/**
|
|
451
474
|
* Eine Rechnungsposition beim Ausstellen: die gemeinsamen Positionsfelder plus
|
|
452
|
-
* `reservationId` (seit 1.5.0). Die Reservierung aus der Lager-API
|
|
475
|
+
* `reservationId` (seit 1.5.0) und `deposit` (seit 1.36.0). Die Reservierung aus der Lager-API
|
|
453
476
|
* (`createReservation`) wird beim Ausstellen geprueft und beim Buchen der
|
|
454
477
|
* Rechnung eingeloest; die Position braucht dazu `articleId`. Unbekannt =
|
|
455
478
|
* `reservation_not_found`, schon eingeloest oder freigegeben =
|
|
@@ -459,7 +482,7 @@ export const ITEM_FIELDS = Object.freeze({
|
|
|
459
482
|
* `reservation_expired`. Weniger verkauft als reserviert gibt den Rest frei.
|
|
460
483
|
* Gutschriften kennen das Feld nicht (`validation`).
|
|
461
484
|
*/
|
|
462
|
-
export const INVOICE_ITEM_FIELDS = Object.freeze({ ...ITEM_FIELDS, reservationId: id });
|
|
485
|
+
export const INVOICE_ITEM_FIELDS = Object.freeze({ ...ITEM_FIELDS, reservationId: id, deposit: DEPOSIT_ITEM_FIELD });
|
|
463
486
|
/** Genau einer der beiden Preise je Position (§ 9.1). */
|
|
464
487
|
export const ITEM_PRICE_EXACTLY_ONE = Object.freeze([
|
|
465
488
|
Object.freeze(['unitPriceCents']),
|
|
@@ -478,11 +501,11 @@ const positionen = {
|
|
|
478
501
|
const returnDisposition = { type: 'enum', required: false, values: RETURN_DISPOSITIONS };
|
|
479
502
|
/**
|
|
480
503
|
* Eine Gutschriftsposition: die gemeinsamen Positionsfelder plus
|
|
481
|
-
* `returnDisposition` (wohin die zurueckgenommene Ware geht)
|
|
482
|
-
* `reservationId`. An einer Rechnungsposition weist der Server
|
|
504
|
+
* `returnDisposition` (wohin die zurueckgenommene Ware geht) und `deposit`
|
|
505
|
+
* (seit 1.36.0), ohne `reservationId`. An einer Rechnungsposition weist der Server
|
|
483
506
|
* `returnDisposition` als unbekannt ab.
|
|
484
507
|
*/
|
|
485
|
-
export const CREDIT_NOTE_ITEM_FIELDS = Object.freeze({ ...ITEM_FIELDS, returnDisposition });
|
|
508
|
+
export const CREDIT_NOTE_ITEM_FIELDS = Object.freeze({ ...ITEM_FIELDS, returnDisposition, deposit: DEPOSIT_ITEM_FIELD });
|
|
486
509
|
const gutschriftPositionen = {
|
|
487
510
|
type: 'list',
|
|
488
511
|
required: true,
|
|
@@ -23,9 +23,44 @@ export interface HpsConnectTarget {
|
|
|
23
23
|
host: string;
|
|
24
24
|
/** Vorgabe: `8080` (hobex-HPS-Standardport), siehe Connect. */
|
|
25
25
|
port?: number;
|
|
26
|
-
/**
|
|
26
|
+
/**
|
|
27
|
+
* Terminal-ID, gern so, wie sie am Geraet und auf dem Beleg steht (achtstellig
|
|
28
|
+
* mit fuehrender Null, `03600335`). Das HPS kennt sie nur OHNE fuehrende Null
|
|
29
|
+
* und weist jede andere Schreibweise mit `100108 "Invalid TID"` ab; dieser
|
|
30
|
+
* Client schreibt sie deshalb vor jedem Aufruf um, siehe [normalizeHpsTid].
|
|
31
|
+
*/
|
|
27
32
|
tid: string;
|
|
28
33
|
}
|
|
34
|
+
/**
|
|
35
|
+
* Die TID in der Form, die das hobex-HPS annimmt: Leerraum am Rand
|
|
36
|
+
* ([RAND_LEERRAUM]) und fuehrende Nullen fallen weg.
|
|
37
|
+
*
|
|
38
|
+
* Am 10.11.2026 gemessen (TID 3600335, HPS 1.14.4, Firmware 7.3.6): Diagnose
|
|
39
|
+
* und Zahlung mit `03600335` antworten sofort `100108 "Invalid TID"` (nichts
|
|
40
|
+
* belastet), mit `3600335` normal; `003600335`, `0360033` und `36003350` sind
|
|
41
|
+
* ebenfalls `Invalid TID`. Auf Beleg und Geraet steht die TID achtstellig mit
|
|
42
|
+
* fuehrender Null -- so wird sie auch eingetragen.
|
|
43
|
+
*
|
|
44
|
+
* Umgeschrieben wird NUR eine rein ziffrige TID mit mindestens einer Ziffer
|
|
45
|
+
* ungleich `0`. Alles andere geht UNVERAENDERT hinaus, auch die `0` der
|
|
46
|
+
* Erkennungsprobe von Connect und eine TID aus lauter Nullen: still etwas
|
|
47
|
+
* anderes daraus zu machen, hiesse ein anderes Terminal anzusprechen als das
|
|
48
|
+
* eingetragene. Bewusst kein Wurf: Connect weist eine nicht rein ziffrige TID
|
|
49
|
+
* selbst ab (`bad_request`, vor jedem Terminal-Kontakt, hier
|
|
50
|
+
* [HpsPreflightError]), und das HPS antwortet auf eine unbekannte mit
|
|
51
|
+
* `100108` -- in beiden Faellen geht kein Geld, und der Aufrufer bekommt den
|
|
52
|
+
* Grund auf dem Weg, den er fuer jede andere Abweisung auch auswertet.
|
|
53
|
+
*
|
|
54
|
+
* Kein Text (ein Aufrufer ohne Typpruefung uebergibt etwa eine Zahl) geht
|
|
55
|
+
* ebenso unveraendert hinaus: Connect weist ihn dann mit "Es fehlt die
|
|
56
|
+
* Terminal-ID" ab ([HpsPreflightError]), statt dass hier ein Wurf aus dem
|
|
57
|
+
* Zahlweg einen offenen Ausgang machte.
|
|
58
|
+
*
|
|
59
|
+
* Die einzige Stelle, an der die TID umgeschrieben wird: jeder Aufruf geht
|
|
60
|
+
* ueber `target`. Zwilling: `HpsClient` im Dart-Paket (`_normalizeTid`), Faelle
|
|
61
|
+
* in `fixtures/hobex-hps-cases.json`.
|
|
62
|
+
*/
|
|
63
|
+
export declare function normalizeHpsTid(tid: string): string;
|
|
29
64
|
export interface HpsConnectPaymentOptions extends HpsConnectTarget {
|
|
30
65
|
/** Kennung dieser Zahlung — MUSS vor diesem Aufruf feststehen, siehe `transaction-id.ts`. */
|
|
31
66
|
transactionId: string;
|
|
@@ -93,6 +128,13 @@ export interface HpsConnectClientOptions {
|
|
|
93
128
|
export interface HpsConnectClient {
|
|
94
129
|
payment(options: HpsConnectPaymentOptions): Promise<HpsTransactionResponse>;
|
|
95
130
|
status(options: HpsConnectTransactionOptions): Promise<HpsTransactionResponse>;
|
|
131
|
+
/**
|
|
132
|
+
* Abbruch eines laufenden Vorgangs. `responseCode '0'` heisst nur, dass das
|
|
133
|
+
* Terminal die Anfrage angenommen hat -- NICHT, dass der Vorgang abgebrochen
|
|
134
|
+
* ist: am 10.11.2026 endete eine Zahlung nach so einer Quittung genehmigt.
|
|
135
|
+
* Den Ausgang sagt die Antwort auf die Zahlung oder die Statusabfrage, siehe
|
|
136
|
+
* `payments.ts`.
|
|
137
|
+
*/
|
|
96
138
|
abort(options: HpsConnectTransactionOptions): Promise<HpsTransactionResponse>;
|
|
97
139
|
/** Gutschrift — ein Kartenfluss wie [payment], deshalb dieselbe lange Frist. */
|
|
98
140
|
refund(options: HpsConnectRefundOptions): Promise<HpsTransactionResponse>;
|
|
@@ -1,6 +1,55 @@
|
|
|
1
1
|
import { HpsConnectTerminalError, HpsConnectTransportError, HpsPreflightError, HpsTransactionIdError, PREFLIGHT_CONNECT_CODES, TERMINAL_UNREACHABLE_CONNECT_CODES, } from './errors.js';
|
|
2
2
|
import { isValidHpsTransactionId } from './transaction-id.js';
|
|
3
3
|
import { parseHpsTransactionResponse } from './transaction-response.js';
|
|
4
|
+
/** Nur eine rein ziffrige TID wird umgeschrieben. */
|
|
5
|
+
const NUR_ZIFFERN = /^[0-9]+$/;
|
|
6
|
+
const FUEHRENDE_NULLEN = /^0+/;
|
|
7
|
+
/**
|
|
8
|
+
* Leerraum am Rand, der wegfaellt: nur ASCII (Leerzeichen, Tab, Zeilenvorschub,
|
|
9
|
+
* Wagenruecklauf, vertikaler Tab, Seitenvorschub). Bewusst eine feste Liste
|
|
10
|
+
* statt `trim()`: JavaScript und Dart zaehlen Unicode-Leerraum verschieden
|
|
11
|
+
* (U+0085 trimmt Dart, JavaScript nicht), und die Zwillinge sollen dieselbe
|
|
12
|
+
* TID hinausschicken. Jedes andere Zeichen am Rand laesst die TID unveraendert.
|
|
13
|
+
*/
|
|
14
|
+
const RAND_LEERRAUM = /^[ \t\n\r\x0B\x0C]+|[ \t\n\r\x0B\x0C]+$/g;
|
|
15
|
+
/**
|
|
16
|
+
* Die TID in der Form, die das hobex-HPS annimmt: Leerraum am Rand
|
|
17
|
+
* ([RAND_LEERRAUM]) und fuehrende Nullen fallen weg.
|
|
18
|
+
*
|
|
19
|
+
* Am 10.11.2026 gemessen (TID 3600335, HPS 1.14.4, Firmware 7.3.6): Diagnose
|
|
20
|
+
* und Zahlung mit `03600335` antworten sofort `100108 "Invalid TID"` (nichts
|
|
21
|
+
* belastet), mit `3600335` normal; `003600335`, `0360033` und `36003350` sind
|
|
22
|
+
* ebenfalls `Invalid TID`. Auf Beleg und Geraet steht die TID achtstellig mit
|
|
23
|
+
* fuehrender Null -- so wird sie auch eingetragen.
|
|
24
|
+
*
|
|
25
|
+
* Umgeschrieben wird NUR eine rein ziffrige TID mit mindestens einer Ziffer
|
|
26
|
+
* ungleich `0`. Alles andere geht UNVERAENDERT hinaus, auch die `0` der
|
|
27
|
+
* Erkennungsprobe von Connect und eine TID aus lauter Nullen: still etwas
|
|
28
|
+
* anderes daraus zu machen, hiesse ein anderes Terminal anzusprechen als das
|
|
29
|
+
* eingetragene. Bewusst kein Wurf: Connect weist eine nicht rein ziffrige TID
|
|
30
|
+
* selbst ab (`bad_request`, vor jedem Terminal-Kontakt, hier
|
|
31
|
+
* [HpsPreflightError]), und das HPS antwortet auf eine unbekannte mit
|
|
32
|
+
* `100108` -- in beiden Faellen geht kein Geld, und der Aufrufer bekommt den
|
|
33
|
+
* Grund auf dem Weg, den er fuer jede andere Abweisung auch auswertet.
|
|
34
|
+
*
|
|
35
|
+
* Kein Text (ein Aufrufer ohne Typpruefung uebergibt etwa eine Zahl) geht
|
|
36
|
+
* ebenso unveraendert hinaus: Connect weist ihn dann mit "Es fehlt die
|
|
37
|
+
* Terminal-ID" ab ([HpsPreflightError]), statt dass hier ein Wurf aus dem
|
|
38
|
+
* Zahlweg einen offenen Ausgang machte.
|
|
39
|
+
*
|
|
40
|
+
* Die einzige Stelle, an der die TID umgeschrieben wird: jeder Aufruf geht
|
|
41
|
+
* ueber `target`. Zwilling: `HpsClient` im Dart-Paket (`_normalizeTid`), Faelle
|
|
42
|
+
* in `fixtures/hobex-hps-cases.json`.
|
|
43
|
+
*/
|
|
44
|
+
export function normalizeHpsTid(tid) {
|
|
45
|
+
if (typeof tid !== 'string')
|
|
46
|
+
return tid;
|
|
47
|
+
const ohneRand = tid.replace(RAND_LEERRAUM, '');
|
|
48
|
+
if (!NUR_ZIFFERN.test(ohneRand))
|
|
49
|
+
return tid;
|
|
50
|
+
const ohneNullen = ohneRand.replace(FUEHRENDE_NULLEN, '');
|
|
51
|
+
return ohneNullen === '' ? tid : ohneNullen;
|
|
52
|
+
}
|
|
4
53
|
const DEFAULT_BASE_URL = 'http://127.0.0.1:27182';
|
|
5
54
|
const DEFAULT_SHORT_TIMEOUT_MS = 30_000;
|
|
6
55
|
const DEFAULT_PAYMENT_TIMEOUT_MS = 4 * 60_000 + 30_000;
|
|
@@ -83,7 +132,7 @@ export function createHpsConnectClient(options) {
|
|
|
83
132
|
return value;
|
|
84
133
|
}
|
|
85
134
|
function target(t) {
|
|
86
|
-
return { host: t.host, port: t.port, tid: t.tid };
|
|
135
|
+
return { host: t.host, port: t.port, tid: normalizeHpsTid(t.tid) };
|
|
87
136
|
}
|
|
88
137
|
return {
|
|
89
138
|
async payment(o) {
|
|
@@ -40,9 +40,10 @@ export interface HpsPaymentResult {
|
|
|
40
40
|
* fuer den Bediener in `HPS_REASON_HINTS`.
|
|
41
41
|
*
|
|
42
42
|
* Gesetzt an der Stelle, die den Ausgang entschieden hat, nicht aus
|
|
43
|
-
* [response] abgeleitet: ein
|
|
44
|
-
*
|
|
45
|
-
* abgelehnt klaert, zaehlt der Code der
|
|
43
|
+
* [response] abgeleitet: ein quittiertes Storno nach einer Stoerung beim
|
|
44
|
+
* Host antwortet `'0'` und ist trotzdem `'voidedAfterHostFault'`, und wenn
|
|
45
|
+
* die Zwei-9027-Regel eine Zahlung als abgelehnt klaert, zaehlt der Code der
|
|
46
|
+
* ZAHLUNG, nicht das `9027` danach.
|
|
46
47
|
* Fehlt, wenn kein Code etwas erklaert (die Leitung riss ab, bevor das
|
|
47
48
|
* Terminal etwas sagte) und bei einer Aufhebung, die nicht gegriffen hat.
|
|
48
49
|
*/
|
|
@@ -15,49 +15,80 @@ import type { HpsPaymentResult } from './outcome.js';
|
|
|
15
15
|
*
|
|
16
16
|
* Regel, von der nicht abgewichen wird: `outcome: 'declined'` entsteht
|
|
17
17
|
* ausschliesslich aus einer POSITIVEN Aussage — einem GEMESSENEN Ergebniscode
|
|
18
|
-
* des Terminals ungleich `'0'` ([isConclusive])
|
|
19
|
-
*
|
|
20
|
-
* (
|
|
21
|
-
*
|
|
22
|
-
*
|
|
18
|
+
* des Terminals ungleich `'0'` ([isConclusive]) auf die Zahlung oder in der
|
|
19
|
+
* Statusabfrage, der Zwei-9027-Regel nach einer Antwort MIT Code
|
|
20
|
+
* ([ausGeschlossenerAntwort]), einem `9011` (aufgehoben) in der Statusabfrage
|
|
21
|
+
* nach einem nachgeschickten Storno, oder dem gemessenen "Terminal
|
|
22
|
+
* beschaeftigt"-Fall (HTTP 409 auf die ERZEUGENDE Anfrage, siehe
|
|
23
|
+
* `errors.ts`, `HpsConnectTerminalError.isTerminalBusy`). Ein
|
|
24
|
+
* Transportfehler, ein Zeitablauf, eine Wissensluecke, ein quittierter
|
|
25
|
+
* Abbruch und ein quittiertes Storno fuehren NIE dorthin: keines davon ist
|
|
23
26
|
* eine Aussage darueber, dass nichts belastet wurde. Genau diese
|
|
24
27
|
* Verwechslung hat am 24.08.2026 eine echte Belastung als unbelastet
|
|
25
28
|
* ausgewiesen und den Kunden ein zweites Mal belastet.
|
|
26
29
|
*
|
|
27
|
-
* ## Der Klaerweg
|
|
30
|
+
* ## Der Klaerweg
|
|
28
31
|
*
|
|
29
|
-
* Bleibt die Antwort auf eine Zahlung aus:
|
|
32
|
+
* Bleibt die Antwort auf eine Zahlung aus, oder sagt sie nichts:
|
|
30
33
|
*
|
|
31
|
-
* 1. [HpsConnectClient.abort] einmalig versuchen.
|
|
32
|
-
*
|
|
33
|
-
*
|
|
34
|
-
*
|
|
35
|
-
*
|
|
36
|
-
*
|
|
37
|
-
*
|
|
38
|
-
*
|
|
39
|
-
*
|
|
34
|
+
* 1. [HpsConnectClient.abort] einmalig versuchen. Die Absicht: ein
|
|
35
|
+
* Kartenfluss, der noch auf die Karte wartet, soll enden, damit nach der
|
|
36
|
+
* Klaerung keine spaet aufgelegte Karte mehr belastet wird. Eine Garantie
|
|
37
|
+
* ist das nicht -- ob der Abbruch greift, sagt seine Quittung nicht.
|
|
38
|
+
* 2. Die Antwort auf den Abbruch entscheidet NICHTS, auch `'0'` nicht (siehe
|
|
39
|
+
* "Ein quittierter Abbruch ist keine Aussage"). Sie steht nur im Nachweis.
|
|
40
|
+
* 3. Dann die Statusabfrage pollen: `'0'` -> `approved`, mit der Antwort des
|
|
41
|
+
* Status als Beleg; ein schluessiger Code (etwa `9011` aufgehoben) ->
|
|
42
|
+
* `declined`; `9027` ist KEIN Ergebnis, sondern ein Grund weiterzumachen
|
|
43
|
+
* -- ausser nach einer Antwort MIT Code auf die Zahlung, siehe
|
|
44
|
+
* [ausGeschlossenerAntwort].
|
|
45
|
+
* 4. Budget erschoepft -> `unresolved`.
|
|
40
46
|
*
|
|
41
|
-
* Der
|
|
42
|
-
*
|
|
43
|
-
*
|
|
44
|
-
* gedeckelt ([ABORT_BUDGET_DIVISOR]), sonst friesst ein haengender Abbruch
|
|
45
|
-
* die ganze Klaerung.
|
|
47
|
+
* Der Abbruchversuch ist auf einen Bruchteil des Klaerbudgets gedeckelt
|
|
48
|
+
* ([ABORT_BUDGET_DIVISOR]), sonst friesst ein haengender Abbruch die ganze
|
|
49
|
+
* Klaerung.
|
|
46
50
|
*
|
|
47
51
|
* Die Kennung ist in JEDEM Ergebnis gesetzt, auch bei `'unresolved'`.
|
|
48
52
|
*
|
|
53
|
+
* ## Ein quittierter Abbruch ist keine Aussage (10.11.2026)
|
|
54
|
+
*
|
|
55
|
+
* Bis 1.35.0 hiess `'0'` auf den Abbruch "der Vorgang war noch abbrechbar,
|
|
56
|
+
* es ist nichts belastet" -- geschlossen aus einer Messung vom 26.08.2026, bei
|
|
57
|
+
* der der Abbruch WAEHREND des Wartens auf die Karte kam und die Zahlung
|
|
58
|
+
* danach mit `100002` "Aborted" endete. Am 10.11.2026 widerlegt (TID 3600335,
|
|
59
|
+
* HPS 1.14.4, Firmware 7.3.6, Testsystem): Abbruch vier Sekunden nach dem
|
|
60
|
+
* Start einer Zahlung ueber 0,01 EUR, nach 0,18 s quittiert mit `'0'`
|
|
61
|
+
* "Authorized" -- und die laufende Zahlung endete trotzdem GENEHMIGT
|
|
62
|
+
* (kontaktlos), die Statusabfrage danach ebenso. `'0'`
|
|
63
|
+
* heisst also nur, dass das Terminal die Abbruch-Anfrage angenommen hat,
|
|
64
|
+
* nicht, dass die Zahlung abgebrochen ist. Als `declined` gelesen, haette die
|
|
65
|
+
* Kasse "nichts belastet, noch einmal versuchen" gemeldet: der Weg zur
|
|
66
|
+
* Doppelbelastung vom 24.08.2026.
|
|
67
|
+
*
|
|
68
|
+
* Auch ein `9027` kurz nach einem angenommenen Abbruch ist keine Aussage:
|
|
69
|
+
* solange eine Zahlung laeuft, antwortet die Statusabfrage `9027` (gemessen
|
|
70
|
+
* 26.08.2026), und dass sie nach einem angenommenen Abbruch weiterlaufen kann,
|
|
71
|
+
* zeigt die Messung oben. Wie lange danach noch eine Genehmigung kommen kann,
|
|
72
|
+
* ist ungemessen. Ohne Antwort mit Code auf die Zahlung endet ein Abbruch mit
|
|
73
|
+
* anhaltendem `9027` deshalb bei `unresolved`, nicht bei `declined`.
|
|
74
|
+
*
|
|
75
|
+
* Bricht die KASSE eine laufende Zahlung ab (eigener Aufruf von
|
|
76
|
+
* [HpsConnectClient.abort], waehrend [pay] noch auf die Antwort wartet),
|
|
77
|
+
* entscheidet die Antwort auf die Zahlung selbst -- `approved`, wenn sie
|
|
78
|
+
* genehmigt meldet, `declined` mit `100002`. [pay] liest die Quittung dieses
|
|
79
|
+
* fremden Abbruchs nicht.
|
|
80
|
+
*
|
|
49
81
|
* ## [refund] bekommt EXAKT denselben Klaerweg wie [pay]
|
|
50
82
|
*
|
|
51
|
-
* Abbruch eingeschlossen
|
|
52
|
-
*
|
|
53
|
-
*
|
|
54
|
-
*
|
|
55
|
-
*
|
|
56
|
-
*
|
|
57
|
-
*
|
|
58
|
-
*
|
|
59
|
-
*
|
|
60
|
-
* `9027` antwortet.
|
|
83
|
+
* Abbruch eingeschlossen. Die Kennung ist bei [refund] die des NEUEN Vorgangs
|
|
84
|
+
* (der Gutschrift selbst), eine Statusabfrage darauf liefert also genau deren
|
|
85
|
+
* Ausgang -- deshalb reicht dieselbe [resolve]-Funktion unveraendert. Am
|
|
86
|
+
* 26.08.2026 gemessen: `abort` auf eine LAUFENDE Gutschrift antwortet
|
|
87
|
+
* ebenfalls mit `responseCode '0'`, und die Gutschrift endete daraufhin mit
|
|
88
|
+
* `100002` "Aborted". Wie bei der Zahlung beweist die Quittung allein nichts:
|
|
89
|
+
* eine Gutschrift, die nach dem angenommenen Abbruch doch durchgeht, als
|
|
90
|
+
* `declined` zu melden, laedt zu einer zweiten Gutschrift ein. Bleibt die
|
|
91
|
+
* Statusabfrage danach bei `9027`, endet die Klaerung bei `unresolved`.
|
|
61
92
|
*
|
|
62
93
|
* ## [cancel] ist die Ausnahme, in beiden Richtungen
|
|
63
94
|
*
|
|
@@ -113,10 +144,29 @@ import type { HpsPaymentResult } from './outcome.js';
|
|
|
113
144
|
*
|
|
114
145
|
* Fuer einen Teil dieser Codes -- der Host hat nicht oder nicht brauchbar
|
|
115
146
|
* geantwortet, etwa `9908` -- gibt hobex vor, ein Storno nachzuschicken
|
|
116
|
-
* (`sendReversal`). [pay] tut das genau einmal, mit Kennung
|
|
117
|
-
*
|
|
118
|
-
*
|
|
119
|
-
*
|
|
147
|
+
* (`sendReversal`). [pay] tut das genau einmal, mit der Kennung der Zahlung
|
|
148
|
+
* und dem Betrag, den das Terminal belastet: Betrag UND Trinkgeld (wie die
|
|
149
|
+
* Rueckbuchung der Web-Kasse). Danach laeuft immer die Statusabfrage:
|
|
150
|
+
*
|
|
151
|
+
* - `9011` (aufgehoben) -> `declined`, die einzige Stelle, an der nach einem
|
|
152
|
+
* Storno ein Ausgang feststeht: mit `'voidedAfterHostFault'`, wenn das
|
|
153
|
+
* Storno gewirkt haben kann, sonst mit `'canceled'` -- dann hat etwas
|
|
154
|
+
* anderes die Zahlung aufgehoben.
|
|
155
|
+
* - Ist das Storno nicht sicher abgewiesen ([StornoAusgang]: quittiert mit
|
|
156
|
+
* `'0'`, abgerissen, ohne Code, mit einem unbekannten oder einem
|
|
157
|
+
* Storniert-Code wie `8009`), ist auch `'0'` in der Statusabfrage keine
|
|
158
|
+
* Aussage: das Storno kann noch unterwegs sein, oder es hat nicht
|
|
159
|
+
* gegriffen. Sie zaehlt dann wie `9027` als "nichts Neues", und nach zwei
|
|
160
|
+
* solchen Antworten endet die Klaerung als `unresolved`.
|
|
161
|
+
* - Nur wenn das Storno nach einer ausdruecklichen Positivliste NICHT
|
|
162
|
+
* ausgefuehrt wurde (nicht gesendet, nicht angenommen, abgewiesen -- siehe
|
|
163
|
+
* [stornoAbgewiesen]), ist `'0'` in der Statusabfrage `approved`. Gemessen
|
|
164
|
+
* ist davon nur `9002` auf eine unbekannte Kennung (27.08.2026); die
|
|
165
|
+
* uebrigen Eintraege stuetzen sich auf die Codeliste von hobex und TECS.
|
|
166
|
+
*
|
|
167
|
+
* Die Quittung `'0'` auf das Storno allein beweist nichts -- dieselbe Lehre
|
|
168
|
+
* wie beim Abbruch (10.11.2026). Am Geraet ungemessen sind das Storno nach
|
|
169
|
+
* einer Host-Stoerung und der Stornobetrag mit Trinkgeld, siehe
|
|
120
170
|
* Dart-Zwilling. [refund] schickt kein Storno nach (TECS: `9031`), [cancel]
|
|
121
171
|
* ist selbst eines.
|
|
122
172
|
*/
|