Zum Hauptinhalt springen
Version: 4.1 (2026 H2)

Connect API

Über die Connect API können Drittsysteme serverseitig die Dokumentgenerierung von primedocs über die primedocs Connect Schnittstelle nutzen.

Endpunkte​

Alle Connect-API-Endpunkte liegen unter …/api/v3/{datasourceId}/Connect. Der Request-Body ist jeweils das primedocs Connect-XML. Die Connect API läuft ohne Benutzerkontext (Client-Credentials); für Szenarien mit Benutzerkontext und Connected Services dient die Connect Session API.

MethodeEndpunktZweck
POST/DocumentGeneriert ein Dokument und gibt die Datei zurück. Mit dem Query-Parameter conversion=Pdf wird das Resultat als PDF zurückgegeben (Standard: None).
POST/ResultFührt die Generierung aus und gibt einen ConnectResultReport (JSON) zurück. Das Dokument selbst wird über einen Command (z.B. InvokeUrl) weiterverarbeitet.
POST/UpdateAktualisiert ein bestehendes primedocs-Dokument und gibt die aktualisierte Datei zurück. Unterstützt conversion=Pdf sowie behavior=Merge|Replace. Siehe Dokument aktualisieren.
GET/TemplatesListet die verfügbaren Vorlagen (paginiert).
POST/SessionErstellt eine Connect Session und gibt ein ConnectSessionResult mit sessionId und einem webAppLink auf die Web App zurück.
POST/FileVeraltet — bitte /Document verwenden.
hinweis

Die Validierung eines Connect erfolgt intern beim Erstellen einer Session (POST /Session); einen eigenständigen /Validate-Endpunkt gibt es in dieser API-Version nicht.

warnung
/File ist veraltet

Der frühere /File-Endpunkt bleibt aus Kompatibilitätsgründen bestehen, leitet aber auf /Document um. Neue Integrationen sollten /Document verwenden.

PDF-Ausgabe​

POST …/Connect/Document?conversion=Pdf gibt das generierte Dokument als PDF zurück. Ohne den Parameter (bzw. conversion=None) wird das native Office-Format geliefert.

Bei der serverseitigen PDF-Erzeugung gilt:

  • Bilder werden korrekt eingebettet — Bilder aus Profil und Organisationseinheit (z.B. Logos oder Unterschriften) sind im PDF enthalten.
  • Datumsformat gemäss Dokumentsprache — Datengebundene Datumsfelder werden gemäss der Sprache des Dokuments formatiert, nicht gemäss der Serversprache (also z.B. kein deutscher Monatsname in einem französischen Dokument).

Vorlagen abfragen (/Templates)​

GET …/Connect/Templates liefert eine paginierte Liste (Query-Parameter page, pageSize; Standard 10, max. 100). Optional kann gefiltert werden:

  • userQuery — z.B. title:*Brief* field[FIELD.ID]:*Wert*
  • templateQuery — z.B. templateId:GUID active:true tags:TAG1;TAG2 localizedName:*Brief*
  • uiLcid, userId — optional.

Die im templateQuery verwendbaren MetaTemplate-IDs liefert der gemeinsame Endpunkt GET .../Common/MetaTemplates. Er ist mit demselben Connect-Token (pd_ConnectWebApi) aufrufbar — ein zusätzlicher Client für die Admin API ist dafür nicht nötig.

Die Antwort enthält ausschliesslich Vorlagen, für die der Zielbenutzer die Berechtigungsstufe Verwenden besitzt — direkt oder über eine seiner Verzeichnisgruppen (siehe Vorlagenberechtigungen). Der Berechtigungsfilter wirkt vor der Seitenbildung: auch die Gesamtzahl der Treffer zählt nur berechtigte Vorlagen. Berechtigungen von Organisationseinheiten werden zusätzlich je Profil geprüft, sodass die zurückgegebenen Profile einer Vorlage ebenfalls nur freigegebene Einträge enthalten.

Dokument aktualisieren (/Update)​

POST …/api/v3/{datasourceId}/Connect/Update aktualisiert ein bestehendes, mit primedocs erzeugtes Dokument und gibt die aktualisierte Datei zurück (conversion=Pdf wird wie bei /Document unterstützt). Die fachlichen Details (Merge/Replace, Sprachüberschreibung, freigegebene Remote-Quellen) beschreibt Aktualisieren von Dokumenten.

Das zu aktualisierende Dokument wird auf eine von drei Arten übergeben:

  • Multipart (multipart/form-data) mit den Teilen document (die bestehende Office-Datei) und connect (das Connect-XML). Fehlt der document-Teil, folgt ein 400 mit entsprechendem Hinweis.
  • Inline als Base64 im Connect-XML (Body = reines Connect-XML): <DocumentLocation Format="DocxBase64">…base64…</DocumentLocation>.
  • Serverseitiger Abruf über <DocumentLocation Source="https://…"/> — nur für in den Datasource-Einstellungen freigegebene Remote-Quellen.
Query-ParameterBeschreibung
behavior (optional)Replace (Standard) oder Merge — steuert, wie eingehende Forms/Data-Werte angewendet werden. Alternativ als Attribut UpdateBehavior am DocumentLocation. Widersprüchliche Angaben (Query vs. Attribut) ergeben einen 400.
conversion (optional)None (Standard) oder Pdf.
proposedFileName (optional)Vorgeschlagener Dateiname.
hinweis
Abgrenzung zu /Document und /Result

/Document und /Result lehnen Update-Connects (mit DocumentLocation) ab und verweisen mit einem 400 auf /Update; umgekehrt lehnt /Update reine Generierungs-Connects ab.

Resultat​

Das Resultat ist abhängig vom Vorlagentyp. In allen Fällen wird eine Datei erstellt.

Bei Word-, Excel- und PowerPoint-Vorlagen ist es eine entsprechende Datei.

Outlook​

Bei allen Outlook-Vorlagen wird standardmässig HTML samt eine Liste von verlinkten Bildern im json-Format zurückgegeben:

{
   "Body":"<html><head></head><body><p>Hello World</p>\r\n<p><b>My Firstname</b> My LastName</p>\r\n<img src=\"cid:profile-org-logo-1312016b.png\"></body></html>",
   "AttachmentImages":[
      {
         "Name":"profile-org-logo-1312016b.png",
         "Base64Data":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAAadEVYdFNvZnR3YXJlAFBhaW50Lk5FVCB2My41LjEwMPRyoQAAAA1JREFUGFdj+P//PwMACPwC/ohfBuAAAAAASUVORK5CYII="
      }
   ]
}
  • Body: Beinhaltet den HTML Content der Signatur bzw. der E-Mail-Vorlage. Werden in der Vorlage auf Bilddaten des Profils zugegriffen (z.B. über <img src="{{Profile.Org.Logo}}" />) wird das Bild über ein cid-Link ausgetauscht und in der AttachmentImages hinterlegt.
    Hinweis: Werden externe Bilder verlinkt oder Bilder werden direkt via base64 in der Vorlage/Signatur hinterlegt, wird kein cid-Link hinzugefügt. Dies geschieht nur über die primedocs Bilder.
  • AttachmentImages: Beinhaltet alle cid-Bilder.
<primedocsConnect>
  <Template Id="e76712a7-d7ab-4112-9240-e688522e5f75" />
  <Author>
    <Profile Id="dfc92748-fbf2-4861-bfac-683fec6139fe" />
  </Author>
  <!-- This can be omitted, because this is the default: -->
  <Outlook ContentType="Html" />
</primedocsConnect>

PlainText​

Über die Connect API können auch PlainText Signaturen bzw. E-Mail Vorlagen definiert werden. Hierfür muss das Connect mit dem Outlook-Element konfiguriert werden:

<primedocsConnect>
  <Template Id="e76712a7-d7ab-4112-9240-e688522e5f75" />
  <Author>
    <Profile Id="dfc92748-fbf2-4861-bfac-683fec6139fe" />
  </Author>
  <Outlook ContentType="PlainText" />
</primedocsConnect>

Zurückgegeben wird in diesem Fall ein solches json:

{
  "PlainTextContent":"My Firstname My Lastname"
}

ConnectResultReport​

Der POST /Result-Endpunkt gibt einen ConnectResultReport als JSON zurück. Dieser beschreibt den Ausgang der Generierung und die Abarbeitung der Commands:

{
  "Status": "OK",
  "Message": null,
  "Messages": [
    { "Type": "Info", "Message": "…", "InternalMessage": null }
  ],
  "CreatedOnUtc": "2026-01-01T12:00:00Z",
  "Dialogs": [
    { "Title": "…", "Message": "…", "ButtonLabel": "…", "ButtonUri": "…" }
  ],
  "HasDownload": false
}
FeldBeschreibung
StatusAusgang der Generierung: OK, Error, Cancelled, Running oder Unknown.
MessageZusammenfassende Fehlermeldung, falls Status nicht OK ist (sonst null).
MessagesListe aller Log-Meldungen, je mit Type, Message und optionalem InternalMessage.
CreatedOnUtcZeitpunkt (UTC) der Fertigstellung.
DialogsAus ShowDialog-Commands erzeugte Dialoge (Title, Message, ButtonLabel, ButtonUri) zur Anzeige im Client.
HasDownloadtrue, wenn ein Download (z.B. aus einer Serienausgabe) bereitsteht.

Authentifizierung und Aufruf​

Um die Connect APIs aufzurufen, muss in der primedocs.config ein entsprechender Client registriert sein, siehe hierfür primedocs.config.

Nach der Registrierung kann damit ein AccessToken vom IdS angefordert werden. Mit dem AccessToken kann dann gegen den Connect/Document Endpunkt der WebApi der eigentliche Aufruf abgesetzt werden.

Dieses PowerShell-Beispiel zeigt den Bezug des AccessTokens und den Aufruf des Endpunktes:

# Configuration
$datasourceId = "b78c3707-d7c7-4fc7-b97f-87d70f63c1ac"
$tokenUrl = "https://{instanz}/ids/connect/token"
$baseApiUrl = "https://{instanz}/webapi/api"
$clientID = "CustomApiClient"
$clientSecret = "CustomClient_Secret_123"
$scope = "pd_ConnectWebApi"

$tokenRequestHeaders = @{
    "Content-Type" = "application/x-www-form-urlencoded"
}
$tokenRequestBody = @{
    client_id     = $clientID
    client_secret = $clientSecret
    grant_type    = "client_credentials"
    scope         = $scope
}

try {
    $tokenResponse = Invoke-RestMethod -Uri $tokenUrl -Method POST -Headers $tokenRequestHeaders -Body $tokenRequestBody
}
catch {
    Write-Error "Error making the request: $_"
    exit 1;
}
if (-not $tokenResponse.access_token) {
    Write-Error "Failed to obtain an access token!"
    exit 1
}

Write-Host "Access Token: $($tokenResponse.access_token)"
$accessToken = $tokenResponse.access_token

$apiRequestHeaders = @{
    "Authorization" = "Bearer $accessToken"
}

$putBodyRequestHeaders = @{
    "Content-Type"  = "application/json"
    "Authorization" = "Bearer $accessToken"
}

$xmlBodyRequestHeaders = @{
    "Content-Type"  = "application/xml"
    "Authorization" = "Bearer $accessToken"
}

function Show-Menu {
    Write-Host "================ Main Menu ================"
    Write-Host "1: Generate Document"
    Write-Host "2: Validate Connect Form"
    Write-Host "3: Create Connect Session"
    Write-Host "4: Get Templates"
    Write-Host "Q: Exit"
}

function GenerateDocument {
    $connectFilePath = Read-Host "Enter connect file path"
    $proposedFileName = Read-Host "Enter proposed file name (without extension, optional)"
    $outputFilePath = Read-Host "Enter output file path (e.g., C:\\Temp\\Generated.docx)"
    $pdfConversion = Read-Host "Convert result to pdf (y/n, default n)"

    if (-not (Test-Path $connectFilePath)) {
        Write-Error "Connect file not found: $connectFilePath"
        return
    }

    $connectFileContent = Get-Content -Path $connectFilePath -Raw

    $apiUrl = "$($baseApiUrl)/v3/$($datasourceId)/Connect/Document"
    if (![string]::IsNullOrWhiteSpace($proposedFileName)) {
        $apiUrl += "?proposedFileName=$proposedFileName"
    }
    
    if ($pdfConversion -eq "y" -or $pdfConversion -eq "Y") {
        if ($apiUrl -like "*?*") {
            $apiUrl += "&conversion=Pdf"
        }
        else {
            $apiUrl += "?conversion=Pdf"
        }
    }

    try {
        Invoke-WebRequest -Uri $apiUrl -Method POST -Headers $xmlBodyRequestHeaders -Body $connectFileContent -OutFile $outputFilePath
        Write-Host "File saved to: $outputFilePath"
    }
    catch {
        Write-Error "Error making the request: $_"
        exit 1;
    }
}

function ValidateConnectForm {
    $templateId = Read-Host "Enter Template ID"
    $fieldKey = Read-Host "Enter field key"
    $fieldValue = Read-Host "Enter field value"

    $body = @{
        templateId = $templateId
        formValues = @{
            $fieldKey = $fieldValue
        }
    }

    $apiUrl = "$($baseApiUrl)/v3/$($datasourceId)/Connect/Validate"

    try {
        $utf8body = ([System.Text.Encoding]::UTF8.GetBytes(($body | ConvertTo-Json)))
        $response = Invoke-RestMethod -Uri $apiUrl -Method POST -Headers $putBodyRequestHeaders -Body $utf8body
        $response | ConvertTo-Json -Depth 6
    }
    catch {
        Write-Error "Error making the request: $_"
        exit 1;
    }
}

function CreateConnectSession {
    $connectFilePath = Read-Host "Enter connect file path"

    if (-not (Test-Path $connectFilePath)) {
        Write-Error "Connect file not found: $connectFilePath"
        return
    }

    $connectFileContent = Get-Content -Path $connectFilePath -Raw

    $apiUrl = "$($baseApiUrl)/v3/$($datasourceId)/Connect/Session"

    try {
        $response = Invoke-RestMethod -Uri $apiUrl -Method POST -Headers $xmlBodyRequestHeaders -Body $connectFileContent
        Write-Output "SessionId: $($response.sessionId)"
    }
    catch {
        Write-Error "Error making the request: $_"
        exit 1;
    }
}

function GetTemplates {
    $pageSize = Read-Host "Enter pagesize"
    $page = Read-Host "Enter page"
    $userId = Read-Host "Enter userId (or empty)"
    $userQuery = Read-Host "Enter userQuery (or empty)"
    $templateQuery = Read-Host "Enter templateQuery (or empty)"
    $uiLcid = Read-Host "Enter uiLcid (or empty)"

    $apiUrl = "$($baseApiUrl)/v3/$($datasourceId)/Connect/Templates?pageSize=$($pageSize)&page=$($page)"

    if (![string]::IsNullOrWhiteSpace($userId)) { $apiUrl += "&userId=$userId" }
    if (![string]::IsNullOrWhiteSpace($userQuery)) { $apiUrl += "&userQuery=$userQuery" }
    if (![string]::IsNullOrWhiteSpace($templateQuery)) { $apiUrl += "&templateQuery=$templateQuery" }
    if (![string]::IsNullOrWhiteSpace($uiLcid)) { $apiUrl += "&uiLcid=$uiLcid" }

    try {
        $response = Invoke-RestMethod -Uri $apiUrl -Method GET -Headers $apiRequestHeaders
        foreach ($template in $response.data) {
            Write-Output "$($template.id): $($template.localizedName)'"
        }
        Write-Output "Page: $($response.pagingDetails.page) / $($response.pagingDetails.totalPages)"
    }
    catch {
        Write-Error "Error making the request: $_"
        exit 1;
    }
}


do {
    Show-Menu
    $selection = Read-Host "Please select an option"

    switch ($selection) {
        '1' { GenerateDocument }
        '2' { ValidateConnectForm }
        '3' { CreateConnectSession }
        '4' { GetTemplates }
        'Q' { break; }
        Default {
            Write-Host "Invalid option selected"
        }
    }
} while ($selection -ne 'Q')

Fehlerbehandlung​

Die HTTP-Statuscodes und das Fehler-Response-Format sind für alle API-Bereiche einheitlich unter API → Fehlerbehandlung beschrieben. Zusätzlich liefert der POST /Result-Endpunkt im Fehlerfall einen ConnectResultReport mit Status: "Error" und einer Message.

Swagger / Open API​

Die vollständige, stets aktuelle OpenAPI-Beschreibung kann direkt von einer laufenden Instanz bezogen werden, z.B. von der PrimeSoft-Referenzinstanz:

https://primesoft.primedocs.io/webapi/swagger/index.html

Sie können die Beschreibung auch über den Swagger Editor visualisieren. Nachfolgend als Beispiel der Ausschnitt für den Connect/Document-Endpunkt:

{
    "openapi": "3.0.1",
    "info": {
        "title": "primedocs WebApi",
        "version": "v3"
    },
    "paths": {
        "/api/v3/{datasourceId}/Connect/Document": {
            "post": {
                "tags": ["Connect"],
                "parameters": [
                    {
                        "name": "proposedFileName",
                        "in": "query",
                        "schema": { "type": "string" }
                    },
                    {
                        "name": "conversion",
                        "in": "query",
                        "schema": { "type": "string", "enum": ["None", "Pdf"] }
                    },
                    {
                        "name": "datasourceId",
                        "in": "path",
                        "required": true,
                        "schema": { "type": "string", "format": "uuid" }
                    }
                ],
                "responses": {
                    "200": { "description": "Success" }
                }
            }
        }
    }
}