Docx direkt über API herunterladen

[Leo]

Hallo zusammen,

ich bin auf der Suche nach einer Möglichkeit einen Zusatzbericht direkt über die API zu laden. Bisher habe ich die .docx-Berichte immer so geladen:

/intern/Smaps/{smapId}/Versions/{version}/Data/{id}?format=Docx&markAsExported=false&useDefault=false&accessToken={token}

Gibt es einen Weg hier auch den Slot für den zweiten Breicht mit zu übergeben und direkt zu laden?

 

In den Storys habe ich mir schon die release News durchgelesen und die dort beschriebene Möglichkeit ausprobiert. Leider gibt mir die SwaggerUI nur eine zip-Datei mit Pdf-Inhalt. Es sind zwar die richtigen Daten aber ich hätte die gerene als docx. Wenn möglich direkt die .docx-Datei.

 

Gibt es hier eine Möglichkeit?

 

[Bülent Erbas]

Hallo @Leo

vielleicht hilft dir die Antwort von Nova weiter:
 

Hallo! Du möchtest gezielt einen Zusatzbericht (zweiten Berichtsslot) einer smap als .docx-Datei direkt über die API herunterladen – nicht als ZIP, sondern als einzelne DOCX-Datei. Hier findest du den aktuellen Stand und die wichtigsten Hinweise zur Umsetzung:

---

1. Aktueller API-Stand: Zusatzberichte als DOCX direkt laden

Seit Ende 2024/Anfang 2025 gibt es laut Release Notes und Dokumentation einen neuen REST-API-Endpunkt, mit dem Zusatzberichte gezielt abgerufen werden können. Die relevante Route ist:

https://platform.smapone.com/Backend/preview/Smaps/{smapId}/Versions/{version}/Reports/Slots/{slotPosition}/Records.{recordId}?format=docx

• {smapId}: Deine smap-ID
• {version}: Die gewünschte Version (z.B. 1)
• {slotPosition}: 2 für den Zusatzbericht
• {recordId}: Die Datensatz-ID
• format=docx: Für das Word-Format

Authentifizierung

Die Authentifizierung erfolgt nicht per Bearer Token, sondern über Basic Access Authorization. Das accessToken wird dabei als Passwort verwendet, der Benutzername kann beliebig gewählt werden (z.B. "user:accessToken"). Der Header sieht folgendermaßen aus:

Authorization: Basic <Base64-encoded-string>

Beispiel für einen Header:

Authorization: Basic YWJjZGVmZ2hpajEyMzQ1Njc4OTA6WA==

Alternativ kann das accessToken als Query-Parameter übergeben werden:

https://platform.smapone.com/Backend/preview/Smaps/{smapId}/Versions/{version}/Reports/Slots/{slotPosition}/Records.{recordId}?format=docx&accessToken=abcdefghij1234567890

Rate Limiting

Die REST API ist auf maximal 60 Requests pro Minute (gleitendes Fenster) limitiert. Bei Überschreitung wird HTTP 429 ("Too Many Requests") zurückgegeben, bis die Minute abgelaufen ist. Wenn du Skripte mit mehreren API-Aufrufen verwendest (z.B. in einer Schleife), solltest du nach jedem Aufruf eine Pause von mindestens einer Sekunde einbauen, um das Limit einzuhalten.

---

2. Praktische Umsetzung

a) Direkt als DOCX laden (empfohlene Methode):

Passe deinen API-Call wie folgt an:

• Entferne den Header accept: application/zip
• Setze stattdessen:

  accept: application/vnd.openxmlformats-officedocument.wordprocessingml.document
  

Beispiel-cURL:

curl -X 'GET' \
  'https://platform.smapone.com/Backend/preview/Smaps/{smapId}/Versions/{version}/Reports/Slots/2/Records.{recordId}?format=docx' \
  -H 'accept: application/vnd.openxmlformats-officedocument.wordprocessingml.document' \
  -H 'Authorization: Basic <Base64-encoded-string>'

Ergebnis:
Du erhältst die .docx-Datei direkt als Response, ohne ZIP-Container.

---

b) Wenn weiterhin ZIP geliefert wird:

Manche API-Versionen liefern aus Kompatibilitätsgründen immer ZIP, auch wenn nur eine Datei enthalten ist. In diesem Fall musst du die DOCX aus dem ZIP entpacken. Das Verhalten kann sich je nach API-Version und Backend-Einstellung unterscheiden.

---

3. Beispielskript: PowerShell

Wichtiger Hinweis: Bitte überprüfe das folgende Skript sorgfältig und führe es nur aus, wenn du die Aktionen vollständig verstehst. Die Ausführung von Skripten kann unbeabsichtigte Änderungen an deinem System oder deinen Daten zur Folge haben.

# PowerShell-Beispiel zum Download eines Zusatzberichts als DOCX

# Parameter
$smapId = "DEINE_SMAP_ID"
$version = "1"
$slotPosition = "2" # 2 = Zusatzbericht
$recordId = "DEIN_RECORD_ID"
$accessToken = "DEIN_ACCESS_TOKEN"

# Basic Auth vorbereiten (Benutzername beliebig, z.B. "user")
$pair = "user:$accessToken"
$bytes = [System.Text.Encoding]::UTF8.GetBytes($pair)
$base64 = [Convert]::ToBase64String($bytes)
$headers = @{
    "accept" = "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
    "Authorization" = "Basic $base64"
}

$url = "https://platform.smapone.com/Backend/preview/Smaps/$smapId/Versions/$version/Reports/Slots/$slotPosition/Records.$recordId?format=docx"

# Download
Invoke-RestMethod -Uri $url -Headers $headers -Method Get -OutFile "Zusatzbericht_$recordId.docx"

---

4. Beispielskript: Python

Wichtiger Hinweis: Bitte überprüfe das folgende Skript sorgfältig und führe es nur aus, wenn du die Aktionen vollständig verstehst. Die Ausführung von Skripten kann unbeabsichtigte Änderungen an deinem System oder deinen Daten zur Folge haben.

import requests
import base64

smapId = "DEINE_SMAP_ID"
version = "1"
slotPosition = "2"  # 2 = Zusatzbericht
recordId = "DEIN_RECORD_ID"
accessToken = "DEIN_ACCESS_TOKEN"

url = f"https://platform.smapone.com/Backend/preview/Smaps/{smapId}/Versions/{version}/Reports/Slots/{slotPosition}/Records.{recordId}?format=docx"

# Basic Auth vorbereiten (Benutzername beliebig, z.B. "user")
userpass = f"user:{accessToken}"
b64 = base64.b64encode(userpass.encode()).decode()
headers = {
    "accept": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    "Authorization": f"Basic {b64}"
}

response = requests.get(url, headers=headers)
if response.status_code == 200:
    with open(f"Zusatzbericht_{recordId}.docx", "wb") as f:
        f.write(response.content)
else:
    print("Fehler:", response.status_code, response.text)

---

5. Quellen & weiterführende Infos

• Release Notes: Download von Berichten (April 2025)
• Release Notes: Zusatzberichte über REST API (Dezember 2024)
• API Dokumentation (Swagger)

---

6. Zusammenfassung & Empfehlung

• Nutze die neue Route mit Slot-Position und dem gewünschten Format.
• Setze explizit den passenden accept-Header, um direkt DOCX zu erhalten.
• Authentifiziere dich immer per Basic Auth (accessToken als Passwort).
• Beachte das Rate Limit von 60 Requests pro Minute, insbesondere bei automatisierten Skripten.
• Falls weiterhin ZIP geliefert wird, ist dies aktuell das Standardverhalten der API und ein direktes DOCX-Download wird (noch) nicht unterstützt – dann bleibt nur das Entpacken.

---

Tipp:
Teste den Call mit verschiedenen accept-Headern. Sollte es weiterhin Probleme geben, prüfe, ob die API-Version deines Systems bereits das direkte DOCX-Download-Feature unterstützt. Die Entwicklung ist hier noch im Fluss, wie die Release Notes zeigen.