Shop-Anbindung: Schnittstelle in Kürze

Aus jeder Bestellung Ihres Onlineshops erstellt OfficePilot eine Rechnung mit QR-Zahlteil. Dazu sendet Ihr Shop pro Bestellung einen Webhook (HTTP-Aufruf) an OfficePilot.

Wer kann sie nutzen?

Fertige Plugins für einzelne Shop-Systeme gibt es nicht. Geeignet ist jeder Shop oder Dienst, der pro Bestellung einen HTTP-POST-Aufruf mit JSON senden kann (Webhook, Automatisierungsdienst oder eigener Code). Die Shop-Verbindung gehört zu den Plänen Standard und Professional (aktives Abo oder Testmonat).

Einrichten

Im Konto unter «Mein Unternehmen» → «Shop-Verbindung» erzeugen Sie den API-Schlüssel. Er wird nur einmal angezeigt; dort sehen Sie auch die genaue Adresse (URL) für Ihren Shop. Den Schlüssel können Sie jederzeit ersetzen oder widerrufen.

Anfrage

Methode und Adresse: POST auf den Pfad /api/shop/orders (vollständige URL siehe Konto)

Header

Authorization: Bearer <IHR-SCHLÜSSEL>Content-Type: application/json

Beispiel-Body

{
  "order_id": "10045",
  "buyer": {
    "name": "Anna Muster",
    "email": "anna@example.ch",
    "street": "Bahnhofstrasse",
    "house_number": "12",
    "postal_code": "8001",
    "city": "Zürich",
    "country": "CH"
  },
  "items": [
    { "name": "Kaffeebohnen 500 g", "quantity": 2, "unit_price": 5.00, "vat_rate": 2.6 }
  ],
  "currency": "CHF",
  "prices_include_vat": true
}

Pflicht sind order_id, buyer (name oder company) und mindestens eine Position in items (name, quantity, unit_price). Währung: nur CHF. prices_include_vat: true (Standard) heisst, die Preise enthalten die MWST; vat_rate pro Position ist optional (erlaubt: 0, 2.6, 3.8, 8.1), sonst gilt der Standardsatz aus dem Firmenprofil. Ohne MWST-Nummer im Firmenprofil wird keine MWST ausgewiesen. Höchstens 200 Positionen.

Antwort

Bei einer neuen Bestellung antwortet die Schnittstelle mit 201 und den Feldern ok: true, duplicate: false, order_id, invoice_id, invoice_number, invoice_number_pending, total, currency (CHF) und delivery (prepared oder sent); bei einer nur vorbereiteten Rechnung, die trotz eingeschaltetem automatischem Versand nicht zugestellt werden konnte, zusätzlich delivery_note mit dem Grund. Hat Ihre Firma eine eigene Nummernserie, hat eine nur vorbereitete Rechnung noch keine Nummer: Dann ist invoice_number null, invoice_number_pending true und invoice_draft_id enthält eine vorläufige Entwurfs-ID, die Sie nicht als Rechnungsnummer anzeigen sollten. Senden Sie dieselbe order_id nochmals, antwortet sie mit 200 und duplicate: true und legt keine zweite Rechnung an. Pro Schlüssel sind höchstens 30 Anfragen pro Minute erlaubt (pro IP-Adresse 60); der Body darf höchstens 200 000 Byte gross sein.

Fehlercodes

HTTP	code	Bedeutung
401	`unauthorized`	Schlüssel fehlt, ist ungültig oder widerrufen.
403	`plan_not_eligible`	Das Abo enthält die Shop-Verbindung nicht (oder ist nicht aktiv).
403	`limit_reached`	Das Dokumentenguthaben oder -kontingent ist aufgebraucht.
413	`payload_too_large`	Die Bestellung ist zu gross.
422	`invalid_payload`	Kein gültiges JSON oder eine Angabe fehlt bzw. ist ungültig; die Meldung nennt das Feld.
409	`order_in_progress`	Dieselbe order_id wird gerade noch verarbeitet. Später erneut senden (Header Retry-After beachten).
422	`currency_not_supported`	Im Firmenprofil ist als Rechnungswährung nicht CHF hinterlegt. Shop-Bestellungen werden nur in CHF verarbeitet.
429	`rate_limited / daily_limit`	Zu viele Anfragen, oder die Tagesgrenze für den automatischen Versand ist erreicht. Header Retry-After beachten.
500	`server_error`	Die Bestellung konnte nicht verarbeitet werden. Später nochmals senden.

Was passiert mit der Bestellung?

OfficePilot legt eine Rechnung mit QR-Zahlteil an. Ist «Rechnung automatisch zustellen» aus (Standard), wird die Rechnung nur vorbereitet: Sie erhalten eine E-Mail, prüfen die Rechnung und senden sie selbst. Ist die Einstellung ein, wird sie sofort per E-Mail an die Käuferin oder den Käufer zugestellt, ausser deren E-Mail-Adresse fehlt, die Rechnungsangaben im Firmenprofil sind unvollständig oder der Versand schlägt fehl: Dann wird sie nur vorbereitet und Sie werden benachrichtigt. Schalten Sie den automatischen Versand nur ein, wenn Sie Ihre Preisliste und Texte geprüft haben.

Zur Shop-Verbindung im Konto