# Bestellung per API anlegen (Tutorial)

Dieses Tutorial zeigt das typische End-to-End-Flow:

1. Bestellung anlegen
2. Label erzeugen
3. PDF herunterladen
4. Tracking abrufen

Alle Beispiele mit `curl`, übertragbar auf jede Programmiersprache.

***

### Vorbereitung

* **API-Token** aus *Einstellungen → API / Schnittstelle* (siehe eigener Artikel).
* **Absenderadresse** in SendDrop angelegt. Ihre `senderAddressId` sehen Sie in der Adress-Verwaltung.
* **Carrier aktiviert**, den Sie nutzen möchten (z. B. GLS AT).

***

### Schritt 1: Bestellung anlegen

```http
POST /orders
Authorization: Bearer sk_live_xxxxxxxx
Content-Type: application/json

{
  "externalOrderId": "SHOP-ORDER-2026-00123",
  "senderAddressId": "sa_abc123",
  "recipient": {
    "name": "Max Mustermann",
    "company": "Muster GmbH",
    "street": "Musterstraße 1",
    "zip": "1010",
    "city": "Wien",
    "country": "AT",
    "phone": "+43 1 23456789",
    "email": "max@example.com"
  },
  "parcels": [
    { "weightKg": 1.5, "lengthCm": 30, "widthCm": 20, "heightCm": 10 }
  ]
}
```

**Antwort (gekürzt):**

```json
{
  "id": "ord_abc123",
  "status": "CREATED",
  "trackingNumber": null
}
```

Notieren Sie die `id`.

***

### Schritt 2: Label erzeugen

```http
POST /orders/ord_abc123/labels
Authorization: Bearer sk_live_xxxxxxxx
Content-Type: application/json

{
  "carrier": "GLS_AT_SMALL",
  "service": "BUSINESS_PARCEL"
}
```

**Antwort (gekürzt):**

```json
{
  "labelId": "lbl_xyz789",
  "trackingNumber": "123456789012",
  "pdfUrl": "https://api.senddrop.com/v1/labels/lbl_xyz789.pdf"
}
```

***

### Schritt 3: Label-PDF herunterladen

```http
GET /labels/lbl_xyz789.pdf
Authorization: Bearer sk_live_xxxxxxxx
```

Antwort: Binary-PDF (Content-Type: `application/pdf`). Speichern Sie das PDF und drucken Sie es oder geben Sie es an Ihren Fulfillment-Prozess weiter.

***

### Schritt 4: Tracking abrufen

```http
GET /orders/ord_abc123/tracking
Authorization: Bearer sk_live_xxxxxxxx
```

**Antwort:**

```json
{
  "trackingNumber": "123456789012",
  "status": "IN_TRANSIT",
  "events": [
    { "at": "2026-04-18T09:00:00Z", "status": "LABEL_CREATED" },
    { "at": "2026-04-18T17:30:00Z", "status": "HANDED_OVER_TO_CARRIER" }
  ]
}
```

***

### Alternativ: Bestellung + Label in einem Call

Für einen schlanken Flow können Sie beim Anlegen direkt ein Label mitverlangen:

```http
POST /orders?autoCreateLabel=true
...
{
  ...
  "carrier": "GLS_AT_SMALL",
  "service": "BUSINESS_PARCEL"
}
```

Die Antwort enthält dann sofort `trackingNumber` und `pdfUrl`.

***

### Idempotenz

Um doppelte Bestellungen bei Timeouts zu vermeiden, senden Sie einen **Idempotency-Key**:

```http
POST /orders
Idempotency-Key: shop-order-2026-00123
...
```

Bei wiederholtem Aufruf mit demselben Key erhalten Sie dieselbe Antwort, **ohne** eine Duplikat-Bestellung anzulegen.

***

### Fehlerbehandlung

Siehe Artikel *Rate Limits & Fehlerbehandlung*. Beispiel für eine Validierungsfehler-Antwort:

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'recipient.zip' is required",
    "fields": { "recipient.zip": "required" }
  }
}
```

***

### Code-Beispiel (Node.js)

```js
const res = await fetch("https://api.senddrop.com/v1/orders", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SENDDROP_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `shop-${orderId}`
  },
  body: JSON.stringify({
    externalOrderId: orderId,
    senderAddressId: "sa_abc123",
    recipient: { /* ... */ },
    parcels: [{ weightKg: 1.5 }]
  })
});

if (!res.ok) throw new Error(await res.text());
const order = await res.json();
console.log("Order created:", order.id);
```

***

### Nächste Schritte

* **Webhooks einrichten**: Status-Updates push-basiert empfangen.
* **Rate Limits & Fehlerbehandlung**: Robuste Integration bauen.

***

### Siehe auch

{% content-ref url="/pages/ZFJXurN97mu1mgXyHzat" %}
[SendDrop REST-API: Überblick](/10.-entwickler-and-integrationen/rest-api-ueberblick.md)
{% endcontent-ref %}

{% content-ref url="/pages/X9wi0yFXdrZChdSB8tjl" %}
[Webhooks einrichten](/10.-entwickler-and-integrationen/webhooks.md)
{% endcontent-ref %}

{% content-ref url="/pages/YMo2pftej5EmimqvdIny" %}
[Rate Limits & Fehlerbehandlung](/10.-entwickler-and-integrationen/rate-limits-fehler.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wiki.senddrop.com/10.-entwickler-and-integrationen/bestellung-per-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.