Hilfe - Produkte & Funktionen
German English
Hilfe - Produkte & Funktionen
German English
Breadcrumbs

Examples

This page shows typical requests against the Public API. The examples cover almost all available operations: read queries, maintaining customers synchronously, and the asynchronous pushing of orders and payments.

The IDs and amounts used here are placeholders; replace <your-api-token> with your token. For the basics of authentication, pagination and time zones, see Getting Started.

Querying Sales Point closings

Shifts (Sales Point closings) can be filtered by Sales Point and period:

Bash
curl -H "Authorization: Token <your-api-token>" \
  "https://api.diekasse.app/v1/public/shifts/?sales_point=450e8400-e29b-41d4-a716-446655440001&timestamp__gte=2026-06-01T00:00:00Z&timestamp__lte=2026-06-30T23:59:59Z"
JSON
{
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "sales_point": "450e8400-e29b-41d4-a716-446655440001",
      "started": "2026-06-15T09:00:00Z",
      "started_by_username": "cashier_001",
      "ended": "2026-06-15T17:30:00Z",
      "ended_by_username": "cashier_001",
      "timestamp": "2026-06-15T17:30:00Z"
    }
  ]
}

For background on this process, see Sales Point Closing.

Querying an invoice with its orders and line items

A payment (invoice) returns key data and the payment items:

Bash
curl -H "Authorization: Token <your-api-token>" \
  "https://api.diekasse.app/v1/public/payments/650e8400-e29b-41d4-a716-446655440006/"
JSON
{
  "id": "650e8400-e29b-41d4-a716-446655440006",
  "sales_point": "450e8400-e29b-41d4-a716-446655440001",
  "type": "PAYMENT",
  "sequential_id": 1234,
  "timestamp": "2026-06-15T15:30:00Z",
  "items": [
    { "method_name": "VISA", "method_type": "CREDIT_CARD", "gross_price": "19.99", "tip": "1.00", "currency_code": "EUR" }
  ],
  "metadata": { "gross": "19.99", "net": "16.80", "vat": "3.19" }
}

Retrieve the associated orders including their line items via the payment filter:

Bash
curl -H "Authorization: Token <your-api-token>" \
  "https://api.diekasse.app/v1/public/orders/?payment=650e8400-e29b-41d4-a716-446655440006"
JSON
{
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "payment": "650e8400-e29b-41d4-a716-446655440006",
      "order_group_name": "Table 5",
      "items": [
        { "article_name": "Espresso", "quantity": 2.0, "gross_price": "5.00", "vat_rate": "20.00" }
      ],
      "metadata": { "gross": "5.00", "net": "4.17", "vat": "0.83" }
    }
  ]
}

Querying reports

Turnover reports expect a period and a Sales Point:

Bash
curl -H "Authorization: Token <your-api-token>" \
  "https://api.diekasse.app/v1/public/reports/turnover/venue/?sales_point=450e8400-e29b-41d4-a716-446655440001&start=2026-06-01T00:00:00Z&end=2026-06-30T23:59:59Z"
JSON
{
  "next": null,
  "previous": null,
  "results": [
    {
      "name": "Main location",
      "net": "5234.56",
      "vat": "1046.91",
      "gross": "6281.47",
      "methods": [
        { "name": "VISA", "type": "CREDIT_CARD", "gross": "3650.00", "count": 45 },
        { "name": "Cash", "type": "CASH", "gross": "2631.47", "count": 112 }
      ]
    }
  ]
}

For an overview of the analyses in the interface, see Reports on the Sales Point.

Querying stock levels

stock-transactions/latest returns the most recent stock movement per article and warehouse:

Bash
curl -H "Authorization: Token <your-api-token>" \
  "https://api.diekasse.app/v1/public/stock-transactions/latest/?warehouse=150e8400-e29b-41d4-a716-446655440002"
JSON
{
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "950e8400-e29b-41d4-a716-446655440040",
      "warehouse": "150e8400-e29b-41d4-a716-446655440002",
      "article": "050e8400-e29b-41d4-a716-446655440005",
      "type": "STOCK_UP",
      "quantity": 45.5,
      "cost": "12.90",
      "created": "2026-06-15T10:00:00Z",
      "updated": "2026-06-15T10:00:00Z"
    }
  ]
}

Articles and warehouses are referenced by UUID; resolve the names via articles or in inventory management. type states the kind of movement (ORDER, CANCEL, STOCK_UP, REDUCE, STOCKTAKING, TRANSFER, DAILY).

The stock of all warehouses is additionally available as a CSV file:

Bash
curl -H "Authorization: Token <your-api-token>" \
  "https://api.diekasse.app/v1/public/warehouse/stockup/?warehouse=150e8400-e29b-41d4-a716-446655440002"

Both endpoints are read-only. Stock levels cannot be changed through the Public API – record additions and reductions at the Sales Point or in the bessa Manager.

For more on stock handling, see Inventory Management.

Creating and changing customers

customers is the only resource that is written synchronously. A new customer is created with POST:

Bash
curl -X POST -H "Authorization: Token <your-api-token>" -H "Content-Type: application/json" \
  "https://api.diekasse.app/v1/public/customers/" \
  -d '{
    "first_name": "Maria",
    "last_name": "Huber",
    "email": "maria.huber@example.com",
    "external_id": "CRM-4711",
    "default_discount_percentage": 5.0
  }'

The response contains the created customer including the id. Individual fields are changed afterwards with PATCH:

Bash
curl -X PATCH -H "Authorization: Token <your-api-token>" -H "Content-Type: application/json" \
  "https://api.diekasse.app/v1/public/customers/a50e8400-e29b-41d4-a716-446655440050/" \
  -d '{ "default_discount_percentage": 10.0 }'

Use external_id to link the customer to the record in your own system. To find customers again, the list endpoint offers the filters first_name, last_name, email and phone, as well as search.

Pushing an order (asynchronous)

An order is submitted as a job:

Bash
curl -X POST -H "Authorization: Token <your-api-token>" -H "Content-Type: application/json" \
  "https://api.diekasse.app/v1/public/requests/orders/" \
  -d '{
    "sales_point": "450e8400-e29b-41d4-a716-446655440001",
    "order_group": "350e8400-e29b-41d4-a716-446655440003",
    "type": "ORDER",
    "items": [
      { "article": "050e8400-e29b-41d4-a716-446655440005", "quantity": 1.0, "price": "2.50" }
    ]
  }'

The required fields are sales_point, order_group, type (ORDER or CANCEL) and items. Look up the matching order group ID via order-groups; order_group_nr, order_group_name and order_sub_group_nr can be passed optionally.

The response contains the job ID; processing happens asynchronously:

JSON
{
  "id": "770e8400-e29b-41d4-a716-446655440020",
  "type": "ORDER",
  "sales_point": "450e8400-e29b-41d4-a716-446655440001",
  "created": "2026-06-15T15:35:00Z",
  "received": null,
  "processed": null,
  "success": null,
  "result": null
}

Query the status afterwards via GET /v1/public/requests/orders/<id>/. received and processed are set once the Sales Point has received and processed the job; success (true/false) and result contain the outcome.

Pushing a payment (asynchronous)

A payment for an open order group is submitted in the same way:

Bash
curl -X POST -H "Authorization: Token <your-api-token>" -H "Content-Type: application/json" \
  "https://api.diekasse.app/v1/public/requests/payment/" \
  -d '{
    "sales_point": "450e8400-e29b-41d4-a716-446655440001",
    "payment": {
      "open_order_group": "250e8400-e29b-41d4-a716-446655440007",
      "payments": [
        { "method": "550e8400-e29b-41d4-a716-446655440008", "value": "5.95", "tip": "0.50", "currency": "EUR" }
      ]
    }
  }'
JSON
{
  "id": "880e8400-e29b-41d4-a716-446655440030",
  "type": "PAYMENT",
  "sales_point": "450e8400-e29b-41d4-a716-446655440001",
  "created": "2026-06-15T15:40:00Z",
  "received": null,
  "processed": null,
  "success": null,
  "result": null
}

To cancel a payment, use POST /v1/public/requests/payment-cancel/ with the Sales Point and the payment ID:

JSON
{
  "sales_point": "450e8400-e29b-41d4-a716-446655440001",
  "payment": "650e8400-e29b-41d4-a716-446655440006"
}

As with pushing, the status is queried via the respective GET .../requests/.../<id>/ endpoint.