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.

Methode	Endpunkt	Zweck
`POST`	`/Document`	Generiert ein Dokument und gibt die Datei zurück. Mit dem Query-Parameter `conversion=Pdf` wird das Resultat als PDF zurückgegeben (Standard: `None`).
`POST`	`/Result`	Führt die Generierung aus und gibt einen `ConnectResultReport` (JSON) zurück. Das Dokument selbst wird über einen Command (z.B. `InvokeUrl`) weiterverarbeitet.
`GET`	`/Templates`	Listet die verfügbaren Vorlagen (paginiert).
`POST`	`/Session`	Erstellt eine Connect Session und gibt einen Link auf die Web App zurück.
`POST`	`/File`	Veraltet — bitte `/Document` verwenden.

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.

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.

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"
}

Authentifizierung und Aufruf

Um die Connect APIs aufzurufen, muss in der primedocs.config solch ein 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')

Swagger / Open API

Die aktuelle Connect API Open API sieht folgendermassen aus. Sie können diese Beschreibung z.B. über den Swagger Editor visualisieren.

{
    "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" }
                }
            }
        }
    }
}

Endpunkte​

PDF-Ausgabe​

Vorlagen abfragen (/Templates)​

Resultat​

Outlook​

PlainText​

Authentifizierung und Aufruf​

Swagger / Open API​