Shop integration: the interface in brief

OfficePilot creates an invoice with a QR payment part from every order in your online shop. For this, your shop sends a webhook (HTTP call) to OfficePilot for each order.

Who can use it?

There are no ready-made plugins for individual shop systems. Any shop or service that can send an HTTP POST call with JSON for each order will work (a webhook, an automation service or your own code). The shop connection is part of the Standard and Professional plans (active subscription or trial month).

Setting up

In your account under “My company” → “Shop connection” you create the API key. It is shown only once; the exact address (URL) for your shop is shown there too. You can replace or revoke the key at any time.

Request

Method and address: POST to the path /api/shop/orders (full URL in your account)

Headers

Authorization: Bearer <YOUR-KEY>Content-Type: application/json

Example 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
}

Required are order_id, buyer (name or company) and at least one entry in items (name, quantity, unit_price). Currency: CHF only. prices_include_vat: true (default) means the prices include VAT; vat_rate per item is optional (allowed: 0, 2.6, 3.8, 8.1), otherwise the default rate from the company profile applies. Without a VAT number in the company profile, no VAT is shown. At most 200 items.

Response

For a new order the interface answers 201 with the fields ok: true, duplicate: false, order_id, invoice_id, invoice_number, invoice_number_pending, total, currency (CHF) and delivery (prepared or sent); for an invoice that is only prepared because automatic sending was on but delivery was not possible, also delivery_note with the reason. If your company uses its own number series, an invoice that is only prepared has no number yet: then invoice_number is null, invoice_number_pending is true and invoice_draft_id holds a provisional draft ID that you should not show as the invoice number. If you send the same order_id again, it answers 200 with duplicate: true and does not create a second invoice. At most 30 requests per minute are allowed per key (60 per IP address); the body may be at most 200,000 bytes.

Error codes

HTTP	code	Meaning
401	`unauthorized`	Key missing, invalid or revoked.
403	`plan_not_eligible`	The subscription does not include the shop connection (or is not active).
403	`limit_reached`	The document credit or allowance is used up.
413	`payload_too_large`	The order is too large.
422	`invalid_payload`	Not valid JSON, or a field is missing or invalid; the message names the field.
409	`order_in_progress`	The same order_id is still being processed. Send it again later (respect the Retry-After header).
422	`currency_not_supported`	The invoice currency in the company profile is not CHF. Shop orders are only processed in CHF.
429	`rate_limited / daily_limit`	Too many requests, or the daily limit for automatic sending is reached. Respect the Retry-After header.
500	`server_error`	The order could not be processed. Send it again later.

What happens to the order?

OfficePilot creates an invoice with a QR payment part. If “Deliver invoice automatically” is off (the default), the invoice is only prepared: you receive an email, check the invoice and send it yourself. If the setting is on, it is emailed to the buyer immediately, unless their email address is missing, the invoice details in the company profile are incomplete or sending fails: then it is only prepared and you are notified. Only switch automatic sending on once you have checked your price list and texts.

Go to the shop connection in your account