feat: promotional and purchase vouchers

src/BusProNet/ApiClient.php

@@ -12,6 +12,8 @@ use App\BusProNet\Model\BookingUpdate;
 use App\BusProNet\Model\CrmAttributes;
 use App\BusProNet\Model\Notification;
 use App\BusProNet\Model\PersonalData;
+use App\BusProNet\Model\PromoVoucher;
+use App\BusProNet\Model\PurchaseVoucher;
 use App\BusProNet\Model\Travel;
 use App\BusProNet\Traits\ApiClientTrait;
 use App\BusProNet\XmlParser\ApiResponseParser;
@@ -39,6 +41,8 @@ class ApiClient
     public const TYPE_PRODUCTS = 'PRODUKTE';
     public const TYPE_PRODUCT_DATA = 'PRODUKTDATEN';
     public const TYPE_AGENCIES = 'AGENTUREN';
+    public const TYPE_PURCHASE_VOUCHER = 'GUTSCHEINPRUEFUNGEINLOESUNG';
+    public const TYPE_PROMO_VOUCHER = 'AKTIONSGUTSCHEIN';
 
     private array $config;
 
@@ -409,6 +413,62 @@ class ApiClient
         return $this->sendRequest(static::TYPE_AGENCIES, $data);
     }
 
+    /**
+     * Validates a purchase voucher by redemption code.
+     *
+     * Purchase vouchers (Gutscheine) have a remaining balance that reduces with each redemption.
+     * They can be regular purchased vouchers or goodwill vouchers (Kulanz).
+     * Returns the voucher with remaining balance, or a Notification if not found or invalid.
+     *
+     * @param string $redemptionCode The voucher redemption code (einloesecode)
+     *
+     * @return Notification|PurchaseVoucher Notification on error, PurchaseVoucher on success
+     *
+     * @throws ApiClientException If the API request fails
+     */
+    public function validatePurchaseVoucher(string $redemptionCode): Notification|PurchaseVoucher
+    {
+        $data = [
+            'user' => $this->config['bpn_username'],
+            'key' => $this->createKey($this->config['bpn_username'], $this->config['bpn_password'], static::TYPE_PURCHASE_VOUCHER),
+            'satz' => ['@typ' => static::TYPE_PURCHASE_VOUCHER],
+            'einloesecode' => $redemptionCode,
+        ];
+
+        return $this->sendRequest(static::TYPE_PURCHASE_VOUCHER, $data);
+    }
+
+    /**
+     * Validates a promo voucher for a specific travel and participant price.
+     *
+     * Promo vouchers (Aktionsgutscheine) provide absolute discounts per person or per booking.
+     * Applicability is indicated by the pro_buchung_person field: "P" = per person, "B" = per booking.
+     *
+     * @param string $promoCode        The promo voucher code
+     * @param int    $travelId         The travel ID this voucher applies to
+     * @param float  $participantPrice Current participant price for validation
+     *
+     * @return Notification|PromoVoucher Notification on error, PromoVoucher on success
+     *
+     * @throws ApiClientException If the API request fails
+     */
+    public function validatePromoVoucher(string $promoCode, int $travelId, float $participantPrice): Notification|PromoVoucher
+    {
+        // Format price to German format (comma decimal separator)
+        $priceFormatted = number_format($participantPrice, 2, ',', '');
+
+        $data = [
+            'user' => $this->config['bpn_username'],
+            'key' => $this->createKey($this->config['bpn_username'], $this->config['bpn_password'], static::TYPE_PROMO_VOUCHER),
+            'satz' => ['@typ' => static::TYPE_PROMO_VOUCHER],
+            'aktionsgutschein' => $promoCode,
+            'idreise' => $travelId,
+            'preis' => $priceFormatted,
+        ];
+
+        return $this->sendRequest(static::TYPE_PROMO_VOUCHER, $data);
+    }
+
     /**
      * @throws ApiClientException
      */