BSN-Chatsystem/dhl_csv_sendungsdatenimport_spec.md

# DHL Geschäftskundenportal CSV Sendungsdatenimport — Format Specification

> **Sources:** Official DHL XLS templates downloaded from `dhl.de` / `shop.deutschepost.de`
> *   `DHLCSVImport-VLS.xls` – Geschäftskundenportal (GKP) Version
> *   `dhlcsvimport_shop.xls` – DHL Online Frankierung (Privat/Shop) Version  
> *   `DHLCSVImport_de.xls` – Internationale Version
> *   `dhl-versenden-funktionen-im-detail-de-202302.pdf` – GKP "Versenden" Overview

---

## 1. General CSV Format Rules

| Parameter | GKP Version (VLS) | Shop/Private Version | International Version |
|-----------|-------------------|---------------------|----------------------|
| **Encoding** | CP1252 (Windows) | CP1252 (Windows) | CP1252 (Windows) |
| **Separator** | `;` (semicolon) **only** | `,` `;` `\|` `:` `#` or Tab | `;` (semicolon) **only** |
| **Line ending** | `<CR>`, `<LF>`, or `<CR><LF>` | `<CR>` or `<CR><LF>` | `<CR>`, `<LF>`, or `<CR><LF>` |
| **Quoting** | Double-quote fields containing separator or `"`; double `"` inside | Same | Same |
| **Max records** | **100** | **50** | **100** |
| **Empty lines** | Ignored | Ignored | Ignored |
| **Newlines in fields** | **Not allowed** | **Not allowed** | **Not allowed** |

---

## 2. Column Definitions (CSV Header / Spaltennamen)

The header row MUST contain these exact column names. Order must be preserved as shown.

| # | Field Name | Type | Required | Description |
|---|-----------|------|----------|-------------|
| 1 | `SEND_NAME1` | String(50) | ✅ First row | Sender name line 1: First+Last name or Company |
| 2 | `SEND_NAME2` | String(50) | ❌ Optional | Sender name line 2: c/o, department, etc. |
| 3 | `SEND_STREET` | String(50) | ✅ First row | Sender street name (without house number) |
| 4 | `SEND_HOUSENUMBER` | String(11) | ✅ First row | Sender house number |
| 5 | `SEND_PLZ` | String(11) | ✅ First row | Sender postal code |
| 6 | `SEND_CITY` | String(38) | ✅ First row | Sender city |
| 7 | `SEND_COUNTRY` | String(3) | ❌ Optional | ISO3 alpha country code. Default: `DEU` if empty |
| 8 | `RECV_NAME1` | String(50) | ✅ Every row | Recipient name line 1 |
| 9 | `RECV_NAME2` | String(50) | ❌ Optional | Recipient name line 2 |
| 10 | `RECV_STREET` | String(50) | ✅ Every row | Recipient street name |
| 11 | `RECV_HOUSENUMBER` | String(11) | ✅ Every row | Recipient house number |
| 12 | `RECV_PLZ` | String(11) | ✅ Every row | Recipient postal code |
| 13 | `RECV_CITY` | String(38) | ✅ Every row | Recipient city |
| 14 | `RECV_COUNTRY` | String(3) | ❌ Optional | ISO3 alpha. Default: `DEU` |
| 15 | `PRODUCT` | String(30) | ❌ Optional | Product key (see §3). If empty, must be chosen after import in the portal. |
| 16 | `COUPON` | String(30) | ✅ Every row | Coupon code assigned via GKP to your billing number. Valid for 100 uses. |
| 17 | `SEND_EMAIL` | String(100) | ✅ First row | Sender email address |

### Sender Inheritance Rule
Sender fields (`SEND_*`) only need to be populated in the **first data row** and whenever the sender changes. Subsequent rows inherit the last-seen sender values. Incomplete sender data in a row triggers an import error.

---

## 3. Product Codes (PRODUCT field)

### Germany Domestic — `*.DEU` suffix required

| Key | Product | Weight |
|-----|---------|--------|
| `PAK02.DEU` | DHL Paket | 2 kg |
| `PAK05.DEU` | DHL Paket | 5 kg |
| `PAK10.DEU` | DHL Paket | 10 kg |
| `PAK31.DEU` | DHL Paket | 31,5 kg |

**Your product `DHL PAKET GKP`** → use `PAK02.DEU`, `PAK05.DEU`, `PAK10.DEU`, or `PAK31.DEU` depending on weight.

### EU / International — `*.EU` suffix (Shop version only)

| Key | Product |
|-----|---------|
| `PAECK.EU` | Päckchen |
| `PAK05.EU` | Paket 5 kg |
| `PAK10.EU` | Paket 10 kg |
| `PAK20.EU` | Paket 20 kg |
| `PAK315.EU` | Paket 31,5 kg |

### International version (no suffix)

| Key | Product |
|-----|---------|
| `PAECKS` | Päckchen S |
| `PAECK` | Päckchen M |
| `PAK02` | Paket 2 kg |
| `PAK05` | Paket 5 kg |
| `PAK10` | Paket 10 kg |
| `PAK20` | Paket 20 kg |
| `PAK31` | Paket 31,5 kg |

---

## 4. Complete CSV Example (GKP Version)

```csv
SEND_NAME1;SEND_NAME2;SEND_STREET;SEND_HOUSENUMBER;SEND_PLZ;SEND_CITY;SEND_COUNTRY;RECV_NAME1;RECV_NAME2;RECV_STREET;RECV_HOUSENUMBER;RECV_PLZ;RECV_CITY;RECV_COUNTRY;PRODUCT;COUPON;SEND_EMAIL
Selma Sender;DHL Online Frankierung;Charles-de-Gaulle-Str.;20;53113;Bonn;DEU;Max Mustermann;DHL Online Frankierung;Charles-de-Gaulle-Str.;20;53113;Bonn;DEU;PAK02.DEU;ABCDEFG;selma.sender@domain.de
;;;;;;;Mustermann GmbH;z. Hdn. Herrn Mustermann;Bundeskanzlerplatz;2;53113;Bonn;DEU;PAK02.DEU;ABCDEFG;
;;;;;;;Mustermann GmbH;z. Hdn. Herrn Mustermann;Grüner Weg;10;53175;Bonn;DEU;PAK05.DEU;ABCDEFG;
Max Mustermann;;Steinweg;3;34117;Kassel;DEU;Mustermann GmbH;z. Hdn. Herrn Mustermann;Grüner Weg;10;53175;Bonn;DEU;PAK31.DEU;ABCDEFG;max.mustermann@domain.de
```

**Key observations:**
- Row 1: Full sender + first recipient
- Rows 2-3: Empty sender columns → inherits from row 1
- Row 4: New sender → all sender fields filled again, new email
- Every row has `RECV_*`, `PRODUCT`, and `COUPON`
- Semicolons separate all fields

---

## 5. Coupon Code (COUPON)

- A coupon code is assigned to your **billing number** (Abrechnungsnummer) via the Geschäftskundenportal.
- Each coupon is valid for **100 shipments**.
- The field is **required** in every row in the GKP version.
- Your billing number: **31647432600101** — you need to generate a coupon code for this number in the GKP portal.

---

## 6. Additional Notes

- The GKP "Versenden" module supports **custom CSV import templates** where you define your own column-to-field mapping. The fixed template above is the default/legacy format.
- Maximum **100 records** per import file. Excess rows are discarded.
- Fields exceeding the maximum length are **truncated** on import.
- House numbers and postal codes are strings — leading zeros preserved.
- No newlines allowed within field values.
- Country codes: ISO 3166-1 alpha-3 (e.g., `DEU`, `AUT`, `CHE`, `FRA`, `ITA`).

---

## 7. Source URLs

| Source | URL |
|--------|-----|
| GKP Template XLS | `https://www.dhl.de/content/dam/images/Paket/GK/downloads/DHLCSVImport-VLS.xls` |
| Shop/Private Template XLS | `https://shop.deutschepost.de/shop/pop/dhlcsvimport.xls` |
| International Template XLS | `https://www.dhl.de/int-versenden/gw/restweb/nepal/assets/downloads/DHLCSVImport_de.xls` |
| GKP Functions Overview PDF | `https://www.dhl.de/dam/jcr:211b2975-947c-4fa8-ae47-0bb340a1fd9d/dhl-versenden-funktionen-im-detail-de-202302.pdf` |