Anleitung zur Freigado API

{
  "templates": [
    {
      "id": "6f1c2a8e-…",
      "name": "Auftragsverarbeitungsvertrag",
      "filename": "avv.pdf",
      "roles": ["Kunde", "Geschäftsführung"],
      "signerCount": 2,
      "senderFields": [
        { "id": "firma", "label": "Firma", "type": "text", "required": true }
      ],
      "reminderDays": [3, 7, 14],
      "message": "Bitte prüfen und unterschreiben.",
      "updatedAt": "2026-10-29T13:12:17.885Z"
    }
  ]
}

{
  "templateId": "6f1c2a8e-…",
  "externalId": "AUFTRAG-2026-0815",
  "recipients": [
    { "email": "einkauf@kunde.de" },
    { "email": "gf@kunde.de" }
  ],
  "fieldValues": { "firma": "Muster GmbH" },
  "message": "Bitte bis Freitag unterschreiben.",
  "reminderDays": [3, 7, 14],
  "senderEmail": "vertrieb@ihre-firma.de"
}

[
  { "id": "ok",      "label": "Freigegeben",               "outcome": "APPROVED" },
  { "id": "auflage", "label": "Mit Auflagen freigegeben",  "outcome": "APPROVED",
    "annotation": "Freigabe unter Vorbehalt der genannten Änderungen." },
  { "id": "nein",    "label": "Abgelehnt",                 "outcome": "REJECTED" }
]

{
  "documentId": "b3994c73-…",
  "externalId": "VORGANG-4712",
  "token": "…",
  "reviewUrl": "https://freigado.de/d/…",
  "status": "PENDING",
  "expiresAt": "2026-11-28T14:17:12.742Z",
  "flowMode": "single",
  "signers": [ { "position": 0, "email": "pruefer@example.com", "status": "ACTIVE" } ]
}

{
  "documentId": "510b1aa7-…",
  "externalId": "AUFTRAG-2026-0815",
  "status": "APPROVED",
  "filename": "avv.pdf",
  "createdAt": "2026-10-29T14:17:47.005Z",
  "expiresAt": "2026-11-28T14:17:46.995Z",
  "reviewUrl": "https://freigado.de/d/…",
  "decision": {
    "outcome": "APPROVED",
    "selectedOptionId": null,
    "selectedLabel": null,
    "annotation": null,
    "comment": "Passt so.",
    "decidedAt": "2026-10-30T09:12:03.000Z",
    "decidedByEmail": "gf@kunde.de",
    "ipAddress": "…",
    "userAgent": "…"
  },
  "templateId": "6f1c2a8e-…",
  "signers": [
    { "position": 0, "role": "Kunde", "email": "einkauf@kunde.de", "status": "COMPLETED",
      "invitedAt": "…", "firstOpenedAt": "…", "decidedAt": "…", "remindersSent": 1 },
    { "position": 1, "role": "Geschäftsführung", "email": "gf@kunde.de", "status": "COMPLETED",
      "invitedAt": "…", "firstOpenedAt": "…", "decidedAt": "…", "remindersSent": 0 }
  ],
  "reminderDays": [3, 7, 14],
  "events": [
    { "id": "04bbad8b-…", "type": "created",  "at": "…", "signerPosition": null, "data": {} },
    { "id": "811fae85-…", "type": "invited",  "at": "…", "signerPosition": 0,    "data": {} },
    { "id": "9a0d…",      "type": "reminder_sent", "at": "…", "signerPosition": 0,
      "data": { "number": 1, "isLast": false } },
    …
    { "id": "c71e…",      "type": "completed", "at": "…", "signerPosition": null, "data": {} }
  ],
  "result": {
    "available": true,
    "availableUntil": "2026-11-06T09:12:04.000Z",
    "files": [
      { "kind": "document", "filename": "avv.pdf", "size": 13250, "sha256": "5f2c…" }
    ]
  }
}

recipients         = ["x@x.de","y@x.de","z@abc.de"]
decisionOptions    = [{"id":"ok","label":"Freigeben","outcome":"APPROVED"}]
message            = Bitte prüfen und freigeben.
reminderDays       = [3,7,14]
externalId         = VORGANG-4713
senderEmail        = sachbearbeiter@example.com
attachmentDelivery = append
file               = vertrag.pdf   (PDF)
attachments        = anlage.pdf    (optional, bis zu 5×)

"attachmentDelivery": "append",
"attachments": [
  { "position": 0, "filename": "anlage.pdf", "size": 864,
    "sha256": "35228331…227432f5", "readAt": "2026-10-29T15:45:27.272Z",
    "readBy": [ { "position": 0, "email": "x@x.de", "readAt": "…" },
                { "position": 1, "email": "y@x.de", "readAt": "…" } ] }
]

{
  "organization": { "id": "…", "name": "Muster GmbH" },
  "plan":  { "key": "business", "label": "Business", "trial": false, "trialEndsAt": null },
  "quota": { "period": "month", "periodStart": "2026-10-01T00:00:00.000Z",
             "limit": 1500, "used": 12, "remaining": 1488 },
  "features": { "multipleRecipients": true, "maxRecipients": 10, "signature": true,
                "maxAttachments": 5, "reminders": true, "templates": true, "decisionOptions": true },
  "limits": { "maxUploadMb": 20, "maxOrderMb": 12, "documentTtlDays": 30, "apiResultRetentionDays": 7 },
  "apiKey": { "scopes": ["ingest", "read"] }
}

#!/usr/bin/env bash
# Freigado API – Beispiel für bash (benötigt: curl ≥ 7.76, openssl, jq, sha256sum)
set -euo pipefail

BASE_URL="${FREIGADO_BASE_URL:-https://freigado.de}"
API_KEY="${FREIGADO_API_KEY:?Bitte FREIGADO_API_KEY setzen}"
SIGNING_SECRET="${FREIGADO_SIGNING_SECRET:?Bitte FREIGADO_SIGNING_SECRET setzen}"

# Signatur = base64url(HMAC-SHA256(Signing-Secret, "<timestamp>." + Body))
# $1 = Timestamp, $2 = Datei mit dem exakten Body (bei GET weglassen)
sign() {
  { printf '%s.' "$1"; if [ -n "${2:-}" ]; then cat "$2"; fi; } |
    openssl dgst -sha256 -hmac "$SIGNING_SECRET" -binary |
    openssl base64 -A | tr '+/' '-_' | tr -d '='
}

# api METHODE PFAD [BODY-DATEI] [CONTENT-TYPE]  → Antwort auf stdout
api() {
  local method="$1" path="$2" body="${3:-}" ctype="${4:-application/json}"
  local ts; ts="$(date +%s)"   # Unix-Sekunden (Millisekunden sind ebenfalls erlaubt)
  local args=(-sS --fail-with-body -X "$method" "$BASE_URL$path"
    -H "Authorization: Bearer $API_KEY"
    -H "X-Timestamp: $ts"
    -H "X-Signature: $(sign "$ts" "$body")")
  if [ -n "$body" ]; then args+=(-H "Content-Type: $ctype" --data-binary "@$body"); fi
  curl "${args[@]}"
}

# 1) Vorlagen auflisten
api GET /api/v1/templates | jq '.templates[] | {id, name, signerCount, senderFields}'

# 2) Vorgang aus Vorlage anlegen – der Body wird als Datei geschrieben,
#    damit exakt dieselben Bytes signiert und gesendet werden.
jq -n '{
  templateId:   "<vorlagen-id>",
  externalId:   "VORGANG-4711",
  recipients:   [ { email: "kunde@example.com" } ],
  fieldValues:  { },
  reminderDays: [3, 7, 14]
}' > body.json
DOC_ID=$(api POST /api/v1/documents body.json | jq -r .documentId)
echo "Vorgang angelegt: $DOC_ID"

# 3) Status abfragen (Polling)
STATUS=$(api GET "/api/v1/documents/$DOC_ID")
echo "$STATUS" | jq '{status, signers: [.signers[] | {email, status}], events: (.events | length)}'

# 4) Ergebnis abholen, SHA-256 prüfen, Abruf bestätigen
if [ "$(echo "$STATUS" | jq -r '.result.available // false')" = "true" ]; then
  api GET "/api/v1/documents/$DOC_ID/files/document" > ergebnis.pdf
  EXPECTED=$(echo "$STATUS" | jq -r '.result.files[] | select(.kind == "document") | .sha256')
  ACTUAL=$(sha256sum ergebnis.pdf | cut -d' ' -f1)
  if [ "$EXPECTED" = "$ACTUAL" ]; then
    echo '{}' > ack.json
    api POST "/api/v1/documents/$DOC_ID/files/ack" ack.json
    echo "Ergebnis gespeichert und Abruf bestätigt."
  else
    echo "Prüfsumme stimmt nicht – Download wiederholen, KEIN ack senden." >&2
  fi
fi

# Vorgang per PDF-Upload (multipart/form-data) – nutzt sign() und api() von oben.
# curl -F kann nicht verwendet werden: Die Signatur braucht den fertigen Body vorab.
BOUNDARY="----freigado$(date +%s)$RANDOM"
{
  printf -- '--%s\r\nContent-Disposition: form-data; name="recipientEmail"\r\n\r\n%s\r\n' "$BOUNDARY" "pruefer@example.com"
  printf -- '--%s\r\nContent-Disposition: form-data; name="externalId"\r\n\r\n%s\r\n' "$BOUNDARY" "VORGANG-4712"
  printf -- '--%s\r\nContent-Disposition: form-data; name="file"; filename="vertrag.pdf"\r\n' "$BOUNDARY"
  printf -- 'Content-Type: application/pdf\r\n\r\n'
  cat vertrag.pdf
  printf -- '\r\n--%s--\r\n' "$BOUNDARY"
} > upload.bin
api POST /api/v1/documents upload.bin "multipart/form-data; boundary=$BOUNDARY" | jq

# PDF mit Freigabeablauf ohne Vorlage – nutzt sign() und api() von oben.
# x@x.de → y@x.de → z@abc.de nacheinander, für alle derselbe Button „Freigeben“.

# 0) Konto prüfen: Kontingent und ob mehrere Empfänger im Tarif enthalten sind
ACCOUNT=$(api GET /api/v1/account)
echo "Noch frei: $(echo "$ACCOUNT" | jq -r '.quota.remaining') Vorgänge"
if [ "$(echo "$ACCOUNT" | jq -r '.features.multipleRecipients')" != "true" ]; then
  echo "Mehrere Empfänger sind erst ab dem Team-Tarif verfügbar." >&2; exit 1
fi

# 1) multipart vollständig erzeugen (Textfelder, PDF, optionale Anlage), dann signiert senden
BOUNDARY="----freigado$(date +%s)$RANDOM"
field() { printf -- '--%s\r\nContent-Disposition: form-data; name="%s"\r\n\r\n%s\r\n' "$BOUNDARY" "$1" "$2"; }
pdf() {
  printf -- '--%s\r\nContent-Disposition: form-data; name="%s"; filename="%s"\r\n' "$BOUNDARY" "$1" "$(basename "$2")"
  printf -- 'Content-Type: application/pdf\r\n\r\n'
  cat "$2"
  printf -- '\r\n'
}
{
  field recipients      '["x@x.de","y@x.de","z@abc.de"]'
  field decisionOptions '[{"id":"ok","label":"Freigeben","outcome":"APPROVED"}]'
  field message         'Bitte prüfen und freigeben.'
  field reminderDays    '[3,7,14]'
  field externalId      'VORGANG-4713'
  field senderEmail     'sachbearbeiter@example.com'
  field attachmentDelivery 'append'   # Anlagen ins Ergebnis: separate (Standard) | append | embed
  pdf file        vertrag.pdf
  pdf attachments anlage.pdf          # optional, bis zu 5 Anlagen
  printf -- '--%s--\r\n' "$BOUNDARY"
} > ablauf.bin
DOC_ID=$(api POST /api/v1/documents ablauf.bin "multipart/form-data; boundary=$BOUNDARY" | jq -r '.documentId')
echo "Vorgang angelegt: $DOC_ID"

# 2) Status wie gewohnt abfragen (je Person: signers[].status und signers[].selectedLabel)
api GET "/api/v1/documents/$DOC_ID" | jq -r '.status'

# Vorgang zurückziehen (nur solange er offen ist) – Begründung optional
printf '%s' '{"reason":"Falsche Version hochgeladen"}' > cancel.json
api POST "/api/v1/documents/$DOC_ID/cancel" cancel.json | jq -r '.status'    # → CANCELED

# Freigado API - Beispiel fuer Windows PowerShell 5.1 und PowerShell 7
$ErrorActionPreference = "Stop"
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

$BaseUrl       = if ($env:FREIGADO_BASE_URL) { $env:FREIGADO_BASE_URL } else { "https://freigado.de" }
$ApiKey        = $env:FREIGADO_API_KEY          # "ipa_live_xxxxxxxx.<geheim>"
$SigningSecret = $env:FREIGADO_SIGNING_SECRET

# Signatur = base64url(HMAC-SHA256(Signing-Secret, "<timestamp>." + Body))
function Get-FreigadoSignature([string]$Timestamp, [byte[]]$Body) {
    $hmac   = New-Object System.Security.Cryptography.HMACSHA256 (,[Text.Encoding]::UTF8.GetBytes($SigningSecret))
    $prefix = [Text.Encoding]::UTF8.GetBytes("$Timestamp.")
    $data   = New-Object byte[] ($prefix.Length + $Body.Length)
    [Array]::Copy($prefix, 0, $data, 0, $prefix.Length)
    [Array]::Copy($Body, 0, $data, $prefix.Length, $Body.Length)
    $b64 = [Convert]::ToBase64String($hmac.ComputeHash($data))
    return $b64.TrimEnd("=").Replace("+", "-").Replace("/", "_")
}

# Signierte Anfrage. -OutFile speichert die Antwort (z. B. PDF) als Datei.
function Invoke-Freigado([string]$Method, [string]$Path, [byte[]]$Body = @(),
                         [string]$ContentType = "application/json", [string]$OutFile) {
    $ts = [string][DateTimeOffset]::UtcNow.ToUnixTimeSeconds()
    $p = @{
        Method          = $Method
        Uri             = "$BaseUrl$Path"
        UseBasicParsing = $true
        Headers         = @{
            "Authorization" = "Bearer $ApiKey"
            "X-Timestamp"   = $ts
            "X-Signature"   = (Get-FreigadoSignature $ts $Body)
        }
    }
    if ($Body.Length -gt 0) { $p.Body = $Body; $p.ContentType = $ContentType }
    if ($OutFile) { $p.OutFile = $OutFile }
    $r = Invoke-WebRequest @p
    if ($OutFile -or $r.StatusCode -eq 204) { return $null }
    # Antwort explizit als UTF-8 lesen (PS 5.1 raet sonst die Kodierung)
    $text = [Text.Encoding]::UTF8.GetString($r.RawContentStream.ToArray())
    return $text | ConvertFrom-Json
}

function ConvertTo-Utf8Json($Object) {
    return [Text.Encoding]::UTF8.GetBytes(($Object | ConvertTo-Json -Depth 10 -Compress))
}

# 1) Vorlagen auflisten
$templates = (Invoke-Freigado GET "/api/v1/templates").templates
$templates | Select-Object id, name, signerCount | Format-Table

# 2) Vorgang aus Vorlage anlegen
$body = ConvertTo-Utf8Json @{
    templateId   = "<vorlagen-id>"
    externalId   = "VORGANG-4711"
    recipients   = @(@{ email = "kunde@example.com" })
    fieldValues  = @{}
    reminderDays = @(3, 7, 14)
}
$doc = Invoke-Freigado POST "/api/v1/documents" $body
"Vorgang angelegt: $($doc.documentId)"

# 3) Status abfragen (Polling)
$status = Invoke-Freigado GET "/api/v1/documents/$($doc.documentId)"
"Status: $($status.status), Ereignisse: $(@($status.events).Count)"

# 4) Ergebnis abholen, SHA-256 pruefen, Abruf bestaetigen
if ($status.result -and $status.result.available) {
    $file = "$PWD\ergebnis.pdf"
    Invoke-Freigado GET "/api/v1/documents/$($doc.documentId)/files/document" -OutFile $file
    $expected = ($status.result.files | Where-Object kind -eq "document").sha256
    $actual   = (Get-FileHash $file -Algorithm SHA256).Hash.ToLower()
    if ($expected -eq $actual) {
        Invoke-Freigado POST "/api/v1/documents/$($doc.documentId)/files/ack" (ConvertTo-Utf8Json @{}) | Out-Null
        "Ergebnis gespeichert und Abruf bestaetigt."
    } else {
        Write-Warning "Pruefsumme stimmt nicht - Download wiederholen, KEIN ack senden."
    }
}

# Vorgang per PDF-Upload (multipart/form-data) - nutzt Invoke-Freigado von oben.
$boundary = "----freigado" + [Guid]::NewGuid().ToString("N")
$enc = [Text.Encoding]::UTF8
$ms  = New-Object System.IO.MemoryStream
function Add-Part([string]$Text) { $b = $enc.GetBytes($Text); $ms.Write($b, 0, $b.Length) }
Add-Part "--$boundary`r`nContent-Disposition: form-data; name=`"recipientEmail`"`r`n`r`npruefer@example.com`r`n"
Add-Part "--$boundary`r`nContent-Disposition: form-data; name=`"externalId`"`r`n`r`nVORGANG-4712`r`n"
Add-Part "--$boundary`r`nContent-Disposition: form-data; name=`"file`"; filename=`"vertrag.pdf`"`r`nContent-Type: application/pdf`r`n`r`n"
$pdf = [IO.File]::ReadAllBytes("$PWD\vertrag.pdf"); $ms.Write($pdf, 0, $pdf.Length)
Add-Part "`r`n--$boundary--`r`n"
$upload = Invoke-Freigado POST "/api/v1/documents" $ms.ToArray() "multipart/form-data; boundary=$boundary"
"Vorgang angelegt: $($upload.documentId)"

# PDF mit Freigabeablauf ohne Vorlage - nutzt Invoke-Freigado von oben.
# x@x.de -> y@x.de -> z@abc.de nacheinander, fuer alle derselbe Button "Freigeben".

# 0) Konto pruefen: Kontingent und ob mehrere Empfaenger im Tarif enthalten sind
$account = Invoke-Freigado GET "/api/v1/account"
"Tarif: $($account.plan.label), noch frei: $($account.quota.remaining)"
if (-not $account.features.multipleRecipients) { throw "Mehrere Empfaenger erst ab dem Team-Tarif." }

# 1) multipart vollstaendig erzeugen (Textfelder, PDF, optionale Anlage), dann signiert senden
$boundary = "----freigado" + [Guid]::NewGuid().ToString("N")
$enc = [Text.Encoding]::UTF8
$ms  = New-Object System.IO.MemoryStream
function Add-Part([string]$Text) { $b = $enc.GetBytes($Text); $ms.Write($b, 0, $b.Length) }
function Add-Field([string]$Name, [string]$Value) {
    Add-Part "--$boundary`r`nContent-Disposition: form-data; name=`"$Name`"`r`n`r`n$Value`r`n"
}
function Add-Pdf([string]$Name, [string]$Path) {
    $fileName = [IO.Path]::GetFileName($Path)
    Add-Part "--$boundary`r`nContent-Disposition: form-data; name=`"$Name`"; filename=`"$fileName`"`r`nContent-Type: application/pdf`r`n`r`n"
    $bytes = [IO.File]::ReadAllBytes($Path); $ms.Write($bytes, 0, $bytes.Length)
    Add-Part "`r`n"
}
Add-Field "recipients"      '["x@x.de","y@x.de","z@abc.de"]'
Add-Field "decisionOptions" '[{"id":"ok","label":"Freigeben","outcome":"APPROVED"}]'
Add-Field "message"         "Bitte pruefen und freigeben."
Add-Field "reminderDays"    "[3,7,14]"
Add-Field "externalId"      "VORGANG-4713"
Add-Field "senderEmail"     "sachbearbeiter@example.com"
Add-Field "attachmentDelivery" "append"         # separate (Standard) | append | embed
Add-Pdf   "file"            "$PWD\vertrag.pdf"
Add-Pdf   "attachments"     "$PWD\anlage.pdf"      # optional, bis zu 5 Anlagen
Add-Part  "--$boundary--`r`n"
$flow = Invoke-Freigado POST "/api/v1/documents" $ms.ToArray() "multipart/form-data; boundary=$boundary"
"Vorgang angelegt: $($flow.documentId) - Ablauf: $(($flow.signers | ForEach-Object { $_.email }) -join ' -> ')"

# Vorgang zurueckziehen (nur solange er offen ist) - Begruendung optional
$canceled = Invoke-Freigado POST "/api/v1/documents/$($flow.documentId)/cancel" (ConvertTo-Utf8Json @{ reason = "Falsche Version hochgeladen" })
"Status: $($canceled.status)"    # CANCELED

// Freigado API – Beispiel für C# (.NET 6+; ebenso .NET Framework 4.7.2 mit System.Net.Http)
using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Security.Cryptography;
using System.Text;
using System.Threading.Tasks;

public sealed class FreigadoClient
{
    private static readonly HttpClient Http = new HttpClient();
    private readonly string _baseUrl;
    private readonly string _apiKey;
    private readonly string _signingSecret;

    public FreigadoClient(string baseUrl, string apiKey, string signingSecret)
    {
        _baseUrl = baseUrl.TrimEnd('/');
        _apiKey = apiKey;
        _signingSecret = signingSecret;
    }

    /// <summary>base64url(HMAC-SHA256(Signing-Secret, "&lt;timestamp&gt;." + Body))</summary>
    public static string Sign(string timestamp, byte[] body, string signingSecret)
    {
        using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(signingSecret)))
        {
            byte[] prefix = Encoding.UTF8.GetBytes(timestamp + ".");
            hmac.TransformBlock(prefix, 0, prefix.Length, null, 0);
            hmac.TransformFinalBlock(body, 0, body.Length);
            return Convert.ToBase64String(hmac.Hash).TrimEnd('=').Replace('+', '-').Replace('/', '_');
        }
    }

    /// <summary>Signierte Anfrage. body = exakt die Bytes, die gesendet werden (GET: leer).</summary>
    public async Task<HttpResponseMessage> SendAsync(HttpMethod method, string path,
        byte[] body = null, string contentType = "application/json")
    {
        body = body ?? new byte[0];
        string ts = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();
        var req = new HttpRequestMessage(method, _baseUrl + path);
        req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", _apiKey);
        req.Headers.Add("X-Timestamp", ts);
        req.Headers.Add("X-Signature", Sign(ts, body, _signingSecret));
        if (body.Length > 0)
        {
            req.Content = new ByteArrayContent(body);
            req.Content.Headers.ContentType = MediaTypeHeaderValue.Parse(contentType);
        }
        HttpResponseMessage res = await Http.SendAsync(req);
        if (!res.IsSuccessStatusCode)
        {
            // Fehlerformat: { "error": "...", "code": "...", "meta": { ... } }
            string err = await res.Content.ReadAsStringAsync();
            throw new HttpRequestException((int)res.StatusCode + ": " + err);
        }
        return res;
    }

    public async Task<string> GetJsonAsync(string path)
    {
        var res = await SendAsync(HttpMethod.Get, path);
        return await res.Content.ReadAsStringAsync();
    }

    public async Task<string> PostJsonAsync(string path, string json)
    {
        var res = await SendAsync(HttpMethod.Post, path, Encoding.UTF8.GetBytes(json));
        return await res.Content.ReadAsStringAsync();
    }

    /// <summary>Vorgang per PDF-Upload: multipart erst vollständig erzeugen, dann signieren.</summary>
    public async Task<string> UploadPdfAsync(string pdfPath, string recipientEmail, string externalId)
    {
        var form = new MultipartFormDataContent();
        var file = new ByteArrayContent(File.ReadAllBytes(pdfPath));
        file.Headers.ContentType = new MediaTypeHeaderValue("application/pdf");
        form.Add(file, "file", Path.GetFileName(pdfPath));
        form.Add(new StringContent(recipientEmail), "recipientEmail");
        form.Add(new StringContent(externalId), "externalId");
        byte[] body = await form.ReadAsByteArrayAsync();
        string contentType = form.Headers.ContentType.ToString(); // inkl. boundary
        var res = await SendAsync(HttpMethod.Post, "/api/v1/documents", body, contentType);
        return await res.Content.ReadAsStringAsync();
    }

    /// <summary>Ergebnis-PDF laden, SHA-256 prüfen und erst dann den Abruf bestätigen.</summary>
    public async Task<bool> DownloadAndAckAsync(string documentId, string expectedSha256, string targetPath)
    {
        var res = await SendAsync(HttpMethod.Get, "/api/v1/documents/" + documentId + "/files/document");
        byte[] pdf = await res.Content.ReadAsByteArrayAsync();
        string actual;
        using (var sha = SHA256.Create())
            actual = BitConverter.ToString(sha.ComputeHash(pdf)).Replace("-", "").ToLowerInvariant();
        if (actual != expectedSha256) return false;      // kein ack → erneut versuchen
        File.WriteAllBytes(targetPath, pdf);              // erst sicher speichern …
        await SendAsync(HttpMethod.Post, "/api/v1/documents/" + documentId + "/files/ack",
            Encoding.UTF8.GetBytes("{}"));                // … dann bestätigen (löscht bei Freigado)
        return true;
    }
}

// Verwendung (z. B. in einer Konsolen-App); JSON-Verarbeitung mit System.Text.Json (.NET 6+)
using System;
using System.Net.Http;
using System.Text.Json;
using System.Threading.Tasks;

public static class Program
{
    public static async Task Main()
    {
        var client = new FreigadoClient(
            Environment.GetEnvironmentVariable("FREIGADO_BASE_URL") ?? "https://freigado.de",
            Environment.GetEnvironmentVariable("FREIGADO_API_KEY"),
            Environment.GetEnvironmentVariable("FREIGADO_SIGNING_SECRET"));

        // 1) Vorlagen auflisten
        Console.WriteLine(await client.GetJsonAsync("/api/v1/templates"));

        // 2) Vorgang aus Vorlage anlegen
        string body = JsonSerializer.Serialize(new
        {
            templateId = "<vorlagen-id>",
            externalId = "VORGANG-4711",
            recipients = new[] { new { email = "kunde@example.com" } },
            fieldValues = new { },
            reminderDays = new[] { 3, 7, 14 }
        });
        using JsonDocument created = JsonDocument.Parse(await client.PostJsonAsync("/api/v1/documents", body));
        string id = created.RootElement.GetProperty("documentId").GetString();
        Console.WriteLine("Vorgang angelegt: " + id);

        // 3) Status abfragen (Polling)
        using JsonDocument status = JsonDocument.Parse(await client.GetJsonAsync("/api/v1/documents/" + id));
        Console.WriteLine("Status: " + status.RootElement.GetProperty("status").GetString());

        // 4) Ergebnis abholen, prüfen, bestätigen
        JsonElement result = status.RootElement.GetProperty("result");
        if (result.ValueKind == JsonValueKind.Object)
        {
            foreach (JsonElement f in result.GetProperty("files").EnumerateArray())
            {
                if (f.GetProperty("kind").GetString() != "document") continue;
                bool ok = await client.DownloadAndAckAsync(id, f.GetProperty("sha256").GetString(), "ergebnis.pdf");
                Console.WriteLine(ok ? "Ergebnis gespeichert und bestätigt." : "Prüfsumme falsch – erneut versuchen.");
            }
        }
    }
}

// Ergänzung für die Klasse FreigadoClient (oben): Konto, PDF mit Freigabeablauf, Zurückziehen
public Task<string> GetAccountAsync() => GetJsonAsync("/api/v1/account");

/// <summary>PDF ohne Vorlage an einen oder mehrere Empfänger nacheinander (Reihenfolge = Array).</summary>
public async Task<string> UploadFlowAsync(string pdfPath, string[] recipients, string externalId,
    string decisionOptionsJson = null, string message = null, string[] attachmentPaths = null)
{
    var form = new MultipartFormDataContent();
    var file = new ByteArrayContent(File.ReadAllBytes(pdfPath));
    file.Headers.ContentType = new MediaTypeHeaderValue("application/pdf");
    form.Add(file, "file", Path.GetFileName(pdfPath));
    // Empfänger als JSON-Array, z. B. ["x@x.de","y@x.de","z@abc.de"]
    form.Add(new StringContent("[\"" + string.Join("\",\"", recipients) + "\"]"), "recipients");
    form.Add(new StringContent(externalId), "externalId");
    form.Add(new StringContent("[3,7,14]"), "reminderDays");
    form.Add(new StringContent("append"), "attachmentDelivery");   // separate (Standard) | append | embed
    if (decisionOptionsJson != null) form.Add(new StringContent(decisionOptionsJson), "decisionOptions");
    if (message != null) form.Add(new StringContent(message), "message");
    foreach (string att in attachmentPaths ?? new string[0])      // optional, bis zu 5 Anlagen
    {
        var part = new ByteArrayContent(File.ReadAllBytes(att));
        part.Headers.ContentType = new MediaTypeHeaderValue("application/pdf");
        form.Add(part, "attachments", Path.GetFileName(att));
    }
    byte[] body = await form.ReadAsByteArrayAsync();
    var res = await SendAsync(HttpMethod.Post, "/api/v1/documents", body, form.Headers.ContentType.ToString());
    return await res.Content.ReadAsStringAsync();
}

/// <summary>Offenen Vorgang zurückziehen (Links ungültig, Datei gelöscht). Antwort = Statusobjekt.</summary>
public Task<string> CancelAsync(string documentId, string reason) =>
    PostJsonAsync("/api/v1/documents/" + documentId + "/cancel",
        "{\"reason\":\"" + reason.Replace("\\", "\\\\").Replace("\"", "\\\"") + "\"}");

// Verwendung (z. B. in Program.Main): x@x.de → y@x.de → z@abc.de nacheinander, ein Button „Freigeben“
using JsonDocument account = JsonDocument.Parse(await client.GetAccountAsync());
if (!account.RootElement.GetProperty("features").GetProperty("multipleRecipients").GetBoolean())
    throw new InvalidOperationException("Mehrere Empfänger erst ab dem Team-Tarif.");

using JsonDocument flow = JsonDocument.Parse(await client.UploadFlowAsync(
    "vertrag.pdf", new[] { "x@x.de", "y@x.de", "z@abc.de" }, "VORGANG-4713",
    decisionOptionsJson: "[{\"id\":\"ok\",\"label\":\"Freigeben\",\"outcome\":\"APPROVED\"}]",
    message: "Bitte prüfen und freigeben.",
    attachmentPaths: new[] { "anlage.pdf" }));
string flowId = flow.RootElement.GetProperty("documentId").GetString();
Console.WriteLine("Vorgang angelegt: " + flowId);

// Bei Bedarf zurückziehen (nur solange offen):
using JsonDocument canceled = JsonDocument.Parse(await client.CancelAsync(flowId, "Falsche Version hochgeladen"));
Console.WriteLine("Status: " + canceled.RootElement.GetProperty("status").GetString());   // CANCELED

// Freigado API – Beispiel für Node.js 18+ (ohne Zusatzpakete), als freigado.mjs speichern
import crypto from "node:crypto";
import { readFile, writeFile } from "node:fs/promises";

const BASE_URL = process.env.FREIGADO_BASE_URL ?? "https://freigado.de";
const API_KEY = process.env.FREIGADO_API_KEY;               // "ipa_live_xxxxxxxx.<geheim>"
const SIGNING_SECRET = process.env.FREIGADO_SIGNING_SECRET;

// Signatur = base64url(HMAC-SHA256(Signing-Secret, "<timestamp>." + Body))
function sign(timestamp, body) {
  return crypto.createHmac("sha256", SIGNING_SECRET).update(`${timestamp}.`).update(body).digest("base64url");
}

// Signierte Anfrage; body = exakt die Bytes, die gesendet werden (GET: leer)
async function api(method, path, body = Buffer.alloc(0), contentType = "application/json") {
  const timestamp = String(Math.floor(Date.now() / 1000));
  const headers = {
    Authorization: `Bearer ${API_KEY}`,
    "X-Timestamp": timestamp,
    "X-Signature": sign(timestamp, body),
  };
  if (body.length > 0) headers["Content-Type"] = contentType;
  const res = await fetch(BASE_URL + path, { method, headers, body: body.length > 0 ? body : undefined });
  if (!res.ok) {
    const err = await res.json().catch(() => ({}));   // { error, code, meta }
    throw new Error(`${res.status} ${err.code ?? ""} ${err.error ?? res.statusText}`);
  }
  return res;
}
const jsonBody = (obj) => Buffer.from(JSON.stringify(obj), "utf8");

// 1) Vorlagen auflisten
const { templates } = await (await api("GET", "/api/v1/templates")).json();
console.table(templates.map((t) => ({ id: t.id, name: t.name, signerCount: t.signerCount })));

// 2) Vorgang aus Vorlage anlegen
const doc = await (await api("POST", "/api/v1/documents", jsonBody({
  templateId: "<vorlagen-id>",
  externalId: "VORGANG-4711",
  recipients: [{ email: "kunde@example.com" }],
  fieldValues: {},
  reminderDays: [3, 7, 14],
}))).json();
console.log("Vorgang angelegt:", doc.documentId);

// 3) Status abfragen (Polling)
const status = await (await api("GET", `/api/v1/documents/${doc.documentId}`)).json();
console.log("Status:", status.status, "– Ereignisse:", status.events.length);

// 4) Ergebnis abholen, SHA-256 prüfen, erst dann Abruf bestätigen
if (status.result?.available) {
  const meta = status.result.files.find((f) => f.kind === "document");
  const pdf = Buffer.from(await (await api("GET", `/api/v1/documents/${doc.documentId}/files/document`)).arrayBuffer());
  if (crypto.createHash("sha256").update(pdf).digest("hex") === meta.sha256) {
    await writeFile("ergebnis.pdf", pdf);
    await api("POST", `/api/v1/documents/${doc.documentId}/files/ack`, jsonBody({}));
    console.log("Ergebnis gespeichert und Abruf bestätigt.");
  } else {
    console.warn("Prüfsumme stimmt nicht – Download wiederholen, KEIN ack senden.");
  }
}

// Vorgang per PDF-Upload (multipart/form-data) – nutzt api() von oben.
// Das Formular wird zuerst vollständig kodiert, damit genau diese Bytes signiert werden.
const form = new FormData();
form.append("file", new Blob([await readFile("vertrag.pdf")], { type: "application/pdf" }), "vertrag.pdf");
form.append("recipientEmail", "pruefer@example.com");
form.append("externalId", "VORGANG-4712");
const encoded = new Request("http://localhost/", { method: "POST", body: form });
const uploadBody = Buffer.from(await encoded.arrayBuffer());
const upload = await (await api("POST", "/api/v1/documents", uploadBody, encoded.headers.get("content-type"))).json();
console.log("Vorgang angelegt:", upload.documentId);

// PDF mit Freigabeablauf ohne Vorlage – nutzt api() und jsonBody() von oben.
// x@x.de → y@x.de → z@abc.de nacheinander, für alle derselbe Button „Freigeben“.

// 0) Konto prüfen: Kontingent und ob mehrere Empfänger im Tarif enthalten sind
const account = await (await api("GET", "/api/v1/account")).json();
console.log("Tarif:", account.plan.label, "– noch frei:", account.quota.remaining);
if (!account.features.multipleRecipients) throw new Error("Mehrere Empfänger erst ab dem Team-Tarif.");

// 1) Formular vollständig kodieren, dann genau diese Bytes signieren und senden
const flowForm = new FormData();
flowForm.append("file", new Blob([await readFile("vertrag.pdf")], { type: "application/pdf" }), "vertrag.pdf");
flowForm.append("recipients", JSON.stringify(["x@x.de", "y@x.de", "z@abc.de"]));
flowForm.append("decisionOptions", JSON.stringify([{ id: "ok", label: "Freigeben", outcome: "APPROVED" }]));
flowForm.append("message", "Bitte prüfen und freigeben.");
flowForm.append("reminderDays", JSON.stringify([3, 7, 14]));
flowForm.append("externalId", "VORGANG-4713");
flowForm.append("senderEmail", "sachbearbeiter@example.com");
flowForm.append("attachmentDelivery", "append");   // Anlagen ins Ergebnis: separate (Standard) | append | embed
// optional, bis zu 5 Anlagen:
flowForm.append("attachments", new Blob([await readFile("anlage.pdf")], { type: "application/pdf" }), "anlage.pdf");
const flowReq = new Request("http://localhost/", { method: "POST", body: flowForm });
const flowBody = Buffer.from(await flowReq.arrayBuffer());
const flow = await (await api("POST", "/api/v1/documents", flowBody, flowReq.headers.get("content-type"))).json();
console.log("Vorgang angelegt:", flow.documentId, "–", flow.signers.map((s) => s.email).join(" → "));

// Vorgang zurückziehen (nur solange er offen ist) – Begründung optional
const canceled = await (await api("POST", `/api/v1/documents/${flow.documentId}/cancel`,
  jsonBody({ reason: "Falsche Version hochgeladen" }))).json();
console.log("Status:", canceled.status);   // CANCELED

# Freigado API – Beispiel für Python 3.8+ (pip install requests)
import base64, hashlib, hmac, json, os, time
import requests

BASE_URL = os.environ.get("FREIGADO_BASE_URL", "https://freigado.de")
API_KEY = os.environ["FREIGADO_API_KEY"]                # "ipa_live_xxxxxxxx.<geheim>"
SIGNING_SECRET = os.environ["FREIGADO_SIGNING_SECRET"]


def sign(timestamp: str, body: bytes) -> str:
    """base64url(HMAC-SHA256(Signing-Secret, "<timestamp>." + Body)) ohne '='."""
    mac = hmac.new(SIGNING_SECRET.encode("utf-8"), timestamp.encode("ascii") + b"." + body, hashlib.sha256)
    return base64.urlsafe_b64encode(mac.digest()).rstrip(b"=").decode("ascii")


def api(method: str, path: str, body: bytes = b"", content_type: str = "application/json") -> requests.Response:
    """Signierte Anfrage; body = exakt die Bytes, die gesendet werden (GET: leer)."""
    timestamp = str(int(time.time()))
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "X-Timestamp": timestamp,
        "X-Signature": sign(timestamp, body),
    }
    if body:
        headers["Content-Type"] = content_type
    res = requests.request(method, BASE_URL + path, headers=headers, data=body or None, timeout=60)
    if not res.ok:
        raise RuntimeError(f"{res.status_code}: {res.text}")   # {"error", "code", "meta"}
    return res


def json_body(obj) -> bytes:
    return json.dumps(obj, ensure_ascii=False).encode("utf-8")


# 1) Vorlagen auflisten
for t in api("GET", "/api/v1/templates").json()["templates"]:
    print(t["id"], t["name"], "Empfänger:", t["signerCount"])

# 2) Vorgang aus Vorlage anlegen
doc = api("POST", "/api/v1/documents", json_body({
    "templateId": "<vorlagen-id>",
    "externalId": "VORGANG-4711",
    "recipients": [{"email": "kunde@example.com"}],
    "fieldValues": {},
    "reminderDays": [3, 7, 14],
})).json()
print("Vorgang angelegt:", doc["documentId"])

# 3) Status abfragen (Polling)
status = api("GET", f"/api/v1/documents/{doc['documentId']}").json()
print("Status:", status["status"], "– Ereignisse:", len(status["events"]))

# 4) Ergebnis abholen, SHA-256 prüfen, erst dann Abruf bestätigen
if status.get("result"):
    meta = next(f for f in status["result"]["files"] if f["kind"] == "document")
    pdf = api("GET", f"/api/v1/documents/{doc['documentId']}/files/document").content
    if hashlib.sha256(pdf).hexdigest() == meta["sha256"]:
        with open("ergebnis.pdf", "wb") as fh:
            fh.write(pdf)
        api("POST", f"/api/v1/documents/{doc['documentId']}/files/ack", json_body({}))
        print("Ergebnis gespeichert und Abruf bestätigt.")
    else:
        print("Prüfsumme stimmt nicht – Download wiederholen, KEIN ack senden.")

# Vorgang per PDF-Upload (multipart/form-data) – nutzt api() von oben.
# requests kodiert das Formular vorab; signiert werden genau diese Bytes.
with open("vertrag.pdf", "rb") as fh:
    prepared = requests.Request(
        "POST", BASE_URL,
        files={"file": ("vertrag.pdf", fh.read(), "application/pdf")},
        data={"recipientEmail": "pruefer@example.com", "externalId": "VORGANG-4712"},
    ).prepare()
upload = api("POST", "/api/v1/documents", prepared.body, prepared.headers["Content-Type"]).json()
print("Vorgang angelegt:", upload["documentId"])

# PDF mit Freigabeablauf ohne Vorlage – nutzt api() und json_body() von oben.
# x@x.de → y@x.de → z@abc.de nacheinander, für alle derselbe Button „Freigeben“.

# 0) Konto prüfen: Kontingent und ob mehrere Empfänger im Tarif enthalten sind
account = api("GET", "/api/v1/account").json()
print("Tarif:", account["plan"]["label"], "– noch frei:", account["quota"]["remaining"])
if not account["features"]["multipleRecipients"]:
    raise SystemExit("Mehrere Empfänger erst ab dem Team-Tarif.")

# 1) Formular vorab kodieren; signiert werden genau diese Bytes
with open("vertrag.pdf", "rb") as fh, open("anlage.pdf", "rb") as ah:
    prepared = requests.Request(
        "POST", BASE_URL,
        files=[
            ("file", ("vertrag.pdf", fh.read(), "application/pdf")),
            ("attachments", ("anlage.pdf", ah.read(), "application/pdf")),   # optional, bis zu 5
        ],
        data={
            "recipients": json.dumps(["x@x.de", "y@x.de", "z@abc.de"]),
            "decisionOptions": json.dumps([{"id": "ok", "label": "Freigeben", "outcome": "APPROVED"}]),
            "message": "Bitte prüfen und freigeben.",
            "reminderDays": json.dumps([3, 7, 14]),
            "externalId": "VORGANG-4713",
            "senderEmail": "sachbearbeiter@example.com",
            "attachmentDelivery": "append",   # separate (Standard) | append | embed
        },
    ).prepare()
flow = api("POST", "/api/v1/documents", prepared.body, prepared.headers["Content-Type"]).json()
print("Vorgang angelegt:", flow["documentId"], "-", " -> ".join(s["email"] for s in flow["signers"]))

# Vorgang zurückziehen (nur solange er offen ist) – Begründung optional
canceled = api("POST", f"/api/v1/documents/{flow['documentId']}/cancel",
               json_body({"reason": "Falsche Version hochgeladen"})).json()
print("Status:", canceled["status"])   # CANCELED