REST-API für jedes Shopsystem

Ihr Shopsystem hat keine fertige Stempl-Anbindung? Senden Sie bezahlte Bestellungen per POST an Stempl. Dieselbe Technik nutzen unsere Anbindungen für Shopify und WooCommerce.

1. API-Schlüssel

Im Dashboard unter Shops legen Sie einen Shop vom Typ „API“ an. Der Schlüssel (stk_…) wird nur einmal angezeigt. Er gehört zu genau einem Shop; alle Shops eines Kontos teilen sich einen lückenlosen Nummernkreis.

2. Bestellung senden

POST https://getstempl.de/v1/orders mit dem Header Authorization: Bearer stk_… und Content-Type: application/json. Alle Geldbeträge sind ganze Cent (Ganzzahlen), nie Kommazahlen.

{
  "source": "api",
  "externalId": "10042",
  "orderName": "#10042",
  "currency": "EUR",
  "pricesIncludeTax": true,
  "paidAt": "2026-11-13T10:15:00Z",
  "buyer": {
    "name": "Erika Mustermann",
    "company": "Muster GmbH",
    "vatId": "DE123456789",
    "email": "erika@example.com",
    "isBusiness": true,
    "address": { "street": "Hauptstraße 5", "zip": "80331", "city": "München", "country": "DE" }
  },
  "lines": [
    { "sku": "TEE-7", "title": "Bio-Grüntee 100 g", "qty": 2, "unitCents": 428,
      "taxRate": 7, "taxCents": 56, "discountCents": 0, "kind": "goods" }
  ],
  "shipping": [ { "title": "DHL Paket", "cents": 490, "taxRate": 19, "taxCents": 78 } ],
  "prepaidCents": 0,
  "totalPaidCents": 1346
}

externalId ist die Bestellnummer in Ihrem System. Dieselbe Bestellung erneut zu senden erzeugt nie eine zweite Rechnung.
pricesIncludeTax: true, wenn unitCents Bruttopreise sind. taxRate in Prozent (19, 7, 5.5), taxCents der enthaltene bzw. aufgeschlagene Steuerbetrag.
totalPaidCents ist, was der Käufer gezahlt hat. Weicht es vom Rechnungsbetrag ab, wird die Rechnung nicht erstellt (centgenauer Abgleich).
Optional: shipTo, suppliedAt (Leistungsdatum), payment.dueDate (offene Rechnung mit Zahlungsziel), format: "xrechnung" mit buyerReference (Pro).
Erstattung: dieselbe Bestellung mit refundOf (Erstattungs-ID, Zeitpunkt, erstattete Positionen, totalCents). Daraus entsteht eine Rechnungskorrektur.

3. Antwort

202 bei neuer Bestellung, 200 wenn sie schon bekannt ist; beide mit { "created": true, "invoice": { "id": "…", "status": "DRAFT", … } }. Die Rechnung entsteht im Hintergrund, meist in wenigen Sekunden.

4. Status abfragen

GET https://getstempl.de/v1/invoices/{id} liefert status (DRAFT in Arbeit, VALID geprüft, ERROR mit errors), die Rechnungsnummer und die Download-Adressen.

5. Fehler

Jeder Fehler hat die Form { "error": { "code": "…", "message": "…" } }.

400 ungültiges JSON · 401 Schlüssel fehlt oder falsch · 405 falsche Methode
422 die Bestellung ist inhaltlich ungültig (Text sagt, welches Feld)
503 konnte nicht eingereiht werden: erneut senden ist gefahrlos

6. Beispiel mit curl

curl -X POST https://getstempl.de/v1/orders \
  -H "Authorization: Bearer stk_…" \
  -H "Content-Type: application/json" \
  -d @bestellung.json

CSV statt API

Ohne Programmierung: Im Dashboard unter Import laden Sie eine CSV-Datei hoch (Vorlage zum Download). Fragen: support@getstempl.de.