feat: voucher purchase flow

docs/bpn-xml-api-reference.md

@@ -312,6 +312,67 @@ answers `<reise id status>` plus per-service `status` ("buchbar"), `frei`, `prei
 `ZAHLUNG` reports a credit-card authorisation after booking; the amount must equal the confirmed
 `anzahlung` or errors `1011`-`1018` follow.
 
+## Selling vouchers (Kaufgutschein)
+
+Used by the `/gutschein` flow, which replaces the BusProNet-hosted shop
+(`maske_gutschein.php`). `ApiClient::TYPE_VOUCHER_*`; not to be confused with
+`TYPE_PURCHASE_VOUCHER` (`GUTSCHEINPRUEFUNGEINLOESUNG`), which redeems a voucher in a booking.
+
+| Satz | Request | Response |
+|---|---|---|
+| `GUTSCHEINVORLAGEN` | — | `gutscheinminbetrag`, `gutscheinmaxbetrag` (**undocumented**, measured), then `<gutscheine><gutschein idgutscheinvorlage="3"><gutscheinart>K</gutscheinart><bezeichnung>Allgemein</bezeichnung><hinweis/>` |
+| `GUTSCHEINZAHLUNGSARTEN` | — | `<zahlungsarten><zahlungsart id="2" bezeichnung="Überweisung" art="UEBERW"/>` (measured; the attributes are echoed as `<zahlung>` below) |
+| `GUTSCHEINVORSCHAU` | `idgutscheinvorlage`, `kaeufer`, `empfaenger`, `kaufpreis`, `text` | `<gutscheinpdf>data:application/pdf;base64,…` (measured, about 430 KB) |
+| `ADRESSFELDERGUTSCHEIN` | — | which address fields to show and which are mandatory; not used, the flow fixes the live shop's fields |
+| `GUTSCHEINBUCHUNG` | see below | `buchung=erfolgt`, `idgutschein`, `gutscheinnummer`, `einloesecode`, `preis`, `rechnungsnummer`, `email` |
+| `GUTSCHEINDRUCK` | `idgutschein`, `einloesecode` | the voucher PDF; not used, BusPro mails the voucher itself once the payment has arrived |
+
+```xml
+<satz typ="GUTSCHEINBUCHUNG"/>
+<buchungsart>Anfrage|Buchung</buchungsart>
+<gutscheinart>K</gutscheinart>
+<idgutscheinvorlage>3</idgutscheinvorlage>
+<kaeufer>…</kaeufer>              <!-- "von", printed on the voucher -->
+<empfaenger>…</empfaenger>        <!-- "für", printed on the voucher -->
+<kaufpreis>25</kaufpreis>
+<text/>                           <!-- Zusatztext; the live shop sends it empty -->
+<rechnungsempfänger>
+  <name/><vorname/><anrede/><titel/><geschlecht/><geburtsdatum/>
+  <anschrift><strasse/><plz/><ort/><ortsteil/><land>D</land></anschrift>
+  <kommunikation><telefonprivat/><email/><telefonmobil/></kommunikation>
+</rechnungsempfänger>
+<zahlung idzahlungsart="2" bezeichnung="Überweisung" art="UEBERW"/>
+```
+
+`<preiszusaetze>` is documented but not sent; the total is the voucher value. `telefonmobil` is not
+in the vendor's example, its name is the one `BUCHUNG` uses, and the test system accepts it. The
+live shop also collects a business phone, whose element name is not documented anywhere, so the
+flow does not collect it.
+
+### Measured on the test system (2026-10-01)
+
+`buchungsart=Anfrage` is a full dry run: a valid request answers `<buchung>möglich</buchung>` and
+nothing else (no `idgutschein`, `gutscheinnummer`, `einloesecode`, `rechnungsnummer`), so nothing is
+issued. `idagentur` is not required (619/620 never fired).
+
+| Variant | Answer |
+|---|---|
+| Valid (control), 25 € | `möglich` |
+| `kaufpreis` 6000 | `608 Gutscheinbetrag darf nicht größer als 5.000,00 Euro sein` |
+| `kaufpreis` 5 | `607 Gutscheinbetrag darf nicht kleiner als 10,00 Euro sein` |
+| `kaufpreis` 5000 | `möglich` (bounds inclusive) |
+| `kaufpreis` 25,50 | `möglich` (cents accepted; the flow offers whole euros only) |
+| `empfaenger` missing | `605 Empfängername fehlt` |
+| `idgutscheinvorlage` 999 | `602 Gutscheine mit ID 999 nicht gefunden` (not 615 as documented) |
+| `email` empty | `650 Fehlende Adress Daten. Bitte folgende Eingabefelder prüfen: Mail-Adresse` |
+| `strasse` empty | `650 … Strasse` |
+| `anrede` Herr, `telefonmobil` set | `möglich` |
+
+Missing address data is a `650` and a hard rejection, as on `BUCHUNG`. The flow therefore treats
+every `HINWEIS` on this path as a rejection and sends it back to the step that owns it
+(`VoucherSaleRejectionMapper`). The design ids (3, 4, 5) match the thumbnail file names of the old
+shop, which suggests they are shared with production; confirm on the first production read.
+
 ## Error codes
 
 Returned as `<satz typ="HINWEIS"><nr>…</nr><text>…</text></satz>`. `#1#`/`#2#` are substituted at
@@ -320,7 +381,7 @@ runtime.
 > **`650` is not a success code.** Its documented text is a bare `#1#` — a generic message
 > carrier whose entire content is substituted. `Notification::isError()`
 > (`src/BusProNet/Model/Notification.php:33-36`) treats it as success, which happens to hold on
-> the `KUNDENKONTO` paths but not on `BUCHUNG`/`BUCHUNGAENDERUNG`, where the same code delivers
+> the `KUNDENKONTO` paths but not on `BUCHUNG`/`BUCHUNGAENDERUNG`/`GUTSCHEINBUCHUNG`, where the same code delivers
 > real rejections such as *"Es wurde nicht jedem Teilnehmer eine Pflichtleistung zugeordnet"*.
 > `BookingEditSubmitter.php:81` therefore reports some genuine failures as INFO.
 
@@ -359,8 +420,11 @@ zugelassen** · 983 Anfragebuchung nicht zugelassen · 984 Leistung nicht fürs
 995/996 Gutschein · 997/998 Buchung-ID · 1001 Reisedatum fehlerhaft · 1002 Buchungsdatum
 fehlerhaft · 1003 Status im Vorgang nicht korrekt · 1011-1018 Zahlungsabgleich
 
-**Vouchers** — 600-608 Gutscheine · 610/611 Buchungsart · 612-621 Gutscheinart / Stamm /
-Kapazität · 622 Einlösecode fehlt · 630-632 Aktionsgutschein
+**Vouchers** — 600-608 Gutscheine (602 Vorlage nicht gefunden, measured; 604 Käufername ·
+605 Empfängername · 606 Betrag fehlt · 607/608 Betrag kleiner/größer als #1# Euro) ·
+610/611 Buchungsart · 612/613 Gutscheinart · 614/615 Gutscheinstamm · 616 Kapazität nicht
+ausreichend · 617 Rechnungsempfänger fehlt · 618 Zahlungsart fehlt · 619/620 Agentur-ID ·
+621 Gutscheindaten fehlen · 622 Einlösecode fehlt · 630-632 Aktionsgutschein
 
 ## Applying this: the teamer placeholder booking