API: Bestellungen für Shops
Ein Aufruf pro Kunde: Text, Empfänger, fertig. Gemacht für Shops und CRM-Systeme.
Eine Bestellung aufgeben
Eine Bestellung ist ein handgeschriebenes Stück für einen Empfänger. PenBlitz nimmt die Vorlage des Produkts, füllt Text und Adresse ein und reiht den Auftrag ein.
| Feld | Bedeutung |
|---|---|
product | postcard, letter oder card. GET /api/v1/products listet sie auf. |
text | Der zu schreibende Text. Darf Platzhalter enthalten, die aus variables gefüllt werden. |
recipient | name, street, postal_code, city, country. |
external_id | Deine eigene Bestellnummer. |
with_envelope | Zusätzlich einen DL-Umschlag mit der Adresse beschriften. |
qr_data | Fügt unter dem Text einen QR-Code ein. |
template_id | Diese Vorlage statt der des Produkts verwenden. |
scheduled_at | Nicht vor diesem Zeitpunkt beginnen. |
callback_url | Adresse, die benachrichtigt wird, wenn die Bestellung erledigt ist. |
curl -X POST http://127.0.0.1:8787/api/v1/orders \
-H 'Content-Type: application/json' \
-d '{
"external_id": "A-1042",
"product": "postcard",
"text": "Liebe {first_name}, alles Gute zum Geburtstag!",
"variables": {"first_name": "Anna"},
"recipient": {"name": "Anna Muster", "street": "Hauptstraße 1", "postal_code": "12345", "city": "Musterstadt"},
"with_envelope": false
}'Keine doppelten Drucke
Sendest du dieselbe external_id noch einmal, bekommst du die bestehende Bestellung zurück statt eines zweiten Drucks. Ein Aufruf lässt sich nach einem Zeitüberlauf gefahrlos wiederholen.
Status
GET /api/v1/orders/{id} nimmt die Bestell-ID oder deine external_id.
| Status | Bedeutung |
|---|---|
pending | Für später eingeplant. |
queued | Wartet oder wird geschrieben. |
sent | Geschrieben. |
failed | Konnte nicht geschrieben werden. |
canceled | Abgebrochen. |
Stornieren
DELETE /api/v1/orders/{id} storniert eine Bestellung, die noch nicht geschrieben wurde.
Das Layout ändern
Die Produkte zeigen auf die Vorlagen postcard, letter und card. Lade die Vorlage in der App, pass sie an und speichere sie unter derselben ID; jede spätere Bestellung verwendet das neue Layout.