REST-API für deine KMU-Software

So sieht ein API-Aufruf aus

Mit deinem API-Schlüssel holst du dir ein Token und rufst danach jeden Endpunkt mit einem normalen HTTP-Aufruf ab. Hier am Beispiel der Briefe, einmal mit curl und einmal in Python.

# 1. Token holen (client_id + Schlüssel aus den Einstellungen, API-Schlüssel)
TOKEN=$(curl -s -X POST \
  https://auth.printerless.ch/realms/members/protocol/openid-connect/token \
  -d grant_type=client_credentials \
  -d client_id=$CLIENT_ID \
  -d client_secret=$CLIENT_SECRET | jq -r .access_token)

# 2. API-Call mit Bearer-Token (Beispiel: Briefe abrufen)
curl -s https://api.printerless.ch/v2/letters/letter/ \
  -H "Authorization: Bearer $TOKEN"

import requests

# 1. Token holen
token = requests.post(
    "https://auth.printerless.ch/realms/members/protocol/openid-connect/token",
    data={
        "grant_type": "client_credentials",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
    },
).json()["access_token"]

# 2. Briefe abrufen
letters = requests.get(
    "https://api.printerless.ch/v2/letters/letter/",
    headers={"Authorization": f"Bearer {token}"},
).json()
print(letters["items"])

OpenAPI-Spezifikation exportieren

Die OpenAPI-Spezifikation liegt unter api.printerless.ch/openapi/ und ist die maschinenlesbare Grundlage der Swagger-Oberfläche. Der Abruf braucht Authentifizierung, hängst du kein gültiges Token an, antwortet die Schnittstelle mit 401.

// OpenAPI-Spezifikation exportieren (Authentifizierung erforderlich)
const token = await fetch(
  "https://auth.printerless.ch/realms/members/protocol/openid-connect/token",
  {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "client_credentials",
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
    }),
  },
).then(r => r.json()).then(d => d.access_token)

const openapi = await fetch("https://api.printerless.ch/openapi/", {
  headers: { Authorization: `Bearer ${token}` },
}).then(r => r.json())

console.log(openapi) // vollständige OpenAPI-3-Spezifikation

TypeScript-Client generieren

Aus der OpenAPI-Spezifikation generierst du dir mit dem öffentlichen openapi-generator-cli einen fertigen TypeScript-Client. Das Tool läuft eigenständig über npx, ohne Installation und ohne Abhängigkeit zu Printerless. Denselben Ansatz gibt es auch für Python und viele weitere Sprachen, du tauschst dazu nur den Generator-Namen (zum Beispiel python statt typescript-axios).

# 1. OpenAPI-Spezifikation mit Token herunterladen
curl -s https://api.printerless.ch/openapi/ \
  -H "Authorization: Bearer $TOKEN" > openapi.json

# 2. TypeScript-Client generieren (öffentliches Tool, keine Abhängigkeit zu Printerless)
npx @openapitools/openapi-generator-cli generate \
  -i openapi.json \
  -g typescript-axios \
  -o ./printerless-client