# Anforderungsdokument: Baloise/Vmax eVB-API Integration

**Datum:** 16.02.2026
**Von:** KKZ Universum - Technische Entwicklung
**An:** Baloise / Vmax Technischer Support
**Betreff:** Fehlende Informationen fuer die Integration der eVB-API (SOAP Webservice)

---

## 1. Ausgangslage

Wir integrieren die Vmax eVB-API in unser System zur automatisierten Ausstellung von elektronischen Versicherungsbestaetigungen (eVB-Nummern) fuer Kurzzeitkennzeichen.

Uns liegt die WSDL-Datei vor:
- **Dateiname:** `wserviceextevb.wsdl`
- **Service:** `VMXevbService`
- **Prod-Endpoint:** `https://wservice-shop.evb24.com/wservice_extevb_api.php`
- **Test-Endpoint:** `https://wservice-shop-test.vmax-kvs.de/` (aus targetNamespace)
- **Protokoll:** SOAP/RPC mit `soap:body use="encoded"`

Die WSDL definiert 13 Operationen. Fuer unsere initiale Integration benoetigen wir primaer diese vier:

| Operation | Unser Anwendungsfall |
|-----------|----------------------|
| `orderEVB` | eVB-Nummer bestellen |
| `queryEVB` | eVB-Status abfragen |
| `cancelCards` | Stornierung |
| `queryGDVStatus` | Verbindungstest / GDV-Status |

Zusaetzlich waeren fuer die Konfiguration relevant:
- `queryProducts` - Verfuegbare Produkte abfragen
- `queryKTyp` - Kennzeichentypen abfragen
- `queryVRs` - Versicherer abfragen

---

## 2. Was die WSDL nicht enthaelt

Die WSDL definiert die Methodensignaturen (Operationsnamen und Parametertypen), liefert aber keine Informationen ueber die **Response-Formate**, **Parameter-Semantik** und das **Error-Handling**. Alle Response-Parts sind als `xs:string` deklariert, ohne weitere Strukturierung.

Wir benoetigen daher die im Folgenden aufgefuehrten Informationen.

---

## 3. Benoetigte Informationen

### 3.1 Response-Formate

Fuer jede der folgenden Operationen benoetigen wir ein **Beispiel der Antwort** (Success-Case und Error-Case):

#### `orderEVB` → `orderEVBResult`
- In welchem Format wird die Antwort zurueckgegeben? (XML, JSON, Pipe-delimited, etc.)
- Wie ist die eVB-Nummer in der Antwort enthalten?
- Welche weiteren Felder enthaelt die Antwort? (Vertragsnummer, Gueltigkeitszeitraum, etc.)

**Beispiel-Request und -Response erbeten.**

#### `queryEVB` → `queryEVBResult`
- Format der Statusantwort?
- Welche Status-Werte sind moeglich? (aktiv, storniert, abgelaufen, etc.)

**Beispiel-Request und -Response erbeten.**

#### `cancelCards` → `cancelCardsResult`
- Format der Stornierungsbestaetigung?
- Welche Fehlerfaelle gibt es? (bereits storniert, abgelaufen, etc.)

**Beispiel-Request und -Response erbeten.**

#### `queryGDVStatus` → `GDVStatus`
- Welche Werte sind moeglich? (z.B. "OK", Error-Codes?)
- Eignet sich diese Operation als Connectivity-Test?

**Beispiel-Request und -Response erbeten.**

#### `queryProducts` → `Products`
- Format der Produktliste?
- Welche Felder hat ein Produkt? (ID, Name, Typ, etc.)

**Beispiel-Response erbeten.**

---

### 3.2 Parameter-Semantik

Die WSDL definiert Parameter nur mit Typ `xs:string` oder `xs:int`. Wir benoetigen Klaerung zu folgenden Parametern:

#### `vndata` (Versicherungsnehmerdaten)
- In welchem Format muessen die Daten uebergeben werden?
  - XML-Fragment?
  - Semikolon-separierter String?
  - Pipe-delimited?
  - JSON?
- Welche Felder sind enthalten? (Name, Vorname, Adresse, Geburtsdatum, etc.)
- Welche Felder sind Pflicht, welche optional?
- **Beispiel eines gueltigen `vndata`-Wertes erbeten.**

#### `abrufbis` / `vstbis` (Datums-/Zeitangaben)
- Welches Datumsformat wird erwartet?
  - `YYYY-MM-DD`?
  - `DD.MM.YYYY`?
  - Unix-Timestamp?
- Sind Uhrzeiten enthalten?

#### `prodid` (Produkt-ID)
- Welche Produkt-IDs existieren?
- Gibt es ein Mapping: Produkt-ID ↔ Versicherungstyp (z.B. Kurzzeitkennzeichen, Zollkennzeichen)?
- Koennen die verfuegbaren IDs ueber `queryProducts` abgefragt werden?

#### `ktyp` (Kennzeichentyp)
- Welche Werte sind gueltig?
- Koennen die Typen ueber `queryKTyp` abgefragt werden?

#### `gendk`, `druckvndk`, `druckvnivk`, `drucknurivk` (xs:int)
- Was bedeuten diese Flags?
- Welche Werte sind gueltig? (0/1? Andere?)
- Welche Kombinationen sind sinnvoll fuer digitale eVB-Ausstellung?

#### `card_no` (bei `orderEVB`)
- Was ist die Kartennummer?
- Ist dieses Feld bei Neubestellungen leer?
- Wann wird es benoetigt?

#### `CardData` (bei `cancelCards`)
- In welchem Format muessen die Kartendaten uebergeben werden?
- Ist das die eVB-Nummer oder eine andere Referenz?

---

### 3.3 Error-Handling

- Wie werden Fehler zurueckgegeben?
  - Als SOAP Fault?
  - Als String mit Error-Code im Response-Body?
  - Als HTTP-Fehlercode?
- Gibt es eine Error-Code-Tabelle?
- Welche haeufigen Fehlerfaelle gibt es?
  - Ungueltige Credentials
  - Produkt nicht verfuegbar
  - GDV-Verbindung gestoert
  - Doppelte Bestellung
  - Rate Limiting

---

### 3.4 Authentifizierung

Die WSDL definiert drei Authentifizierungsparameter pro Request:

| Parameter | Beschreibung (unsere Annahme) | Korrekt? |
|-----------|-------------------------------|----------|
| `LegCode` | Legitimationscode | ? |
| `Portalnr` | Portal-Nummer / Mandanten-ID | ? |
| `Kdnr` | Kundennummer | ? |

Fragen:
- Sind `LegCode`, `Portalnr` und `Kdnr` statische Credentials oder werden sie pro Session generiert?
- Gibt es unterschiedliche Credentials fuer Test- und Produktionsumgebung?
- Gibt es zusaetzliche Sicherheitsmechanismen (IP-Whitelisting, Client-Zertifikate, etc.)?

---

## 4. Test-Zugang

Fuer die Entwicklung und Verifikation der Integration benoetigen wir:

1. **Test-Credentials**
   - `LegCode` fuer die Testumgebung
   - `Portalnr` fuer die Testumgebung
   - `Kdnr` fuer die Testumgebung

2. **Test-Endpoint Bestaetigung**
   - Ist `https://wservice-shop-test.vmax-kvs.de/wservice_extevb_api.php` der korrekte Test-Endpoint?
   - Gibt es Einschraenkungen in der Testumgebung? (z.B. nur bestimmte Produkte, keine echten eVB-Nummern)

3. **Test-Portal** (optional)
   - Gibt es ein Web-Portal, in dem wir Test-Bestellungen manuell pruefen koennen?
   - Zugang zum Vmax-Partnersystem fuer Verifikation?

---

## 5. Zusaetzliche Dokumentation

Falls vorhanden, wuerden uns folgende Materialien die Integration erheblich erleichtern:

- [ ] API-Dokumentation / Handbuch zum Webservice
- [ ] Beispiel-Code (PHP, Java, oder andere Sprache)
- [ ] Sequence-Diagramme fuer den Bestellprozess
- [ ] Vollstaendige Wertelisten (Produkt-IDs, Kennzeichentypen, Status-Codes)
- [ ] Changelog / Versionierungshinweise zum Webservice

---

## 6. Unser technisches Setup

Fuer Ihre Referenz - unsere Integrationsumgebung:

| Aspekt | Details |
|--------|---------|
| **Runtime** | Deno (TypeScript, Supabase Edge Functions) |
| **HTTP Client** | Native `fetch()` API |
| **SOAP** | Manuelles XML-Envelope-Building (kein SOAP-Client-Library) |
| **Hosting** | Supabase Cloud (EU Region) |
| **Ausgehende IPs** | Supabase Edge Function IPs (variabel) |

Falls IP-Whitelisting erforderlich ist, benoetigen wir Information darueber, damit wir eine entsprechende Loesung einrichten koennen (z.B. Proxy mit statischer IP).

---

## 7. Ansprechpartner

Bei Rueckfragen stehen wir gerne zur Verfuegung.

**Technischer Kontakt:**
- [Name und Kontaktdaten hier einfuegen]

**Benoetigte Antwortzeit:**
- Wir planen die Integration fuer Q1/Q2 2026
- Ein zeitnaher Austausch wuerde uns helfen, die Implementierung zu planen

---

*Dieses Dokument basiert auf der Analyse der WSDL-Datei `wserviceextevb.wsdl` (Service: VMXevbService). Alle technischen Fragen beziehen sich auf die darin definierten 13 SOAP-Operationen.*