API: orders for shops
One call per customer: text, recipient, done. Made for shops and CRM systems.
Place an order
An order is a handwritten piece for one recipient. PenBlitz picks the template of the product, fills in text and address and queues the job.
| Field | Meaning |
|---|---|
product | postcard, letter or card. GET /api/v1/products lists them. |
text | The text to write. May contain placeholders filled from variables. |
recipient | name, street, postal_code, city, country. |
external_id | Your own order number. |
with_envelope | Also write a DL envelope with the address. |
qr_data | Adds a QR code below the text. |
template_id | Use this template instead of the one of the product. |
scheduled_at | Do not start before this time. |
callback_url | Address that is notified when the order is done. |
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": "Dear {first_name}, happy birthday!",
"variables": {"first_name": "Jane"},
"recipient": {"name": "Jane Doe", "street": "1 Main St", "postal_code": "12345", "city": "Springfield"},
"with_envelope": false
}'No double prints
Send the same external_id again and you get the existing order back instead of a second print. It is safe to repeat a call after a timeout.
Status
GET /api/v1/orders/{id} accepts the order id or your external_id.
| Status | Meaning |
|---|---|
pending | Scheduled for later. |
queued | Waiting or being written. |
sent | Written. |
failed | Could not be written. |
canceled | Canceled. |
Cancel
DELETE /api/v1/orders/{id} cancels an order that has not been written yet.
Change the layout
The products point to the templates postcard, letter and card. Load the template in the app, adjust it and save it under the same id; every later order uses the new layout.