REST-API pour ton logiciel PME

Voici à quoi ressemble un appel API

Avec ta clé API, tu récupères un token, puis tu appelles chaque point de terminaison avec une requête HTTP normale. Voici l’exemple des lettres, une fois avec curl et une fois en 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"])

Exporter la spécification OpenAPI

La spécification OpenAPI se trouve sous api.printerless.ch/openapi/ et constitue la base lisible par machine de l’interface Swagger. La récupération nécessite une authentification. Si tu n’ajoutes pas de token valable, l’interface répond avec 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

Générer un client TypeScript

À partir de la spécification OpenAPI, tu génères un client TypeScript prêt à l’emploi avec l’outil public openapi-generator-cli. L’outil fonctionne de manière autonome via npx, sans installation et sans dépendance à Printerless. La même approche existe aussi pour Python et beaucoup d’autres langages. Il suffit de remplacer le nom du générateur, par exemple python au lieu de 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