sproof Sign: Power Automate Connector

Überblick

Der sproof Sign Connector für Power Automate stellt einen Teil der sproof Sign API bereit und ermöglicht es, Flows zu erstellen, die Signaturanfragen erzeugen, deren Status abfragen, signierte Dokumente herunterladen und Dokumente löschen — ganz ohne Code. Voraussetzung sind ein sproof Sign Account, ein Plan, der die verwendeten Aktionen und Signaturarten unterstützt, sowie ein gültiges API-Token.

Verfügbare Aktionen

Der Connector implementiert die folgenden fünf Endpunkte der sproof Sign API:

Connector-Aktion	API-Endpunkt	Was sie macht	API-Referenz
Create Signature Request	POST /documents/signature	Erstellt eine neue Signaturanfrage aus einem oder mehreren hochgeladenen Dokumenten. Unterstützt sowohl Einzeldokumente als auch mehrteilige Envelopes, mit Empfänger:innen und Signaturrollen im Request-Body.	OpenAPI-Spezifikation
Create Signature Request Using Placeholders	POST /documents/signature	Erstellt eine Signaturanfrage aus einem Dokument, das bereits Platzhalter enthält. Empfänger:innen und Positionen der Signaturfelder werden automatisch aus den Platzhaltern extrahiert und müssen nicht separat angegeben werden.	OpenAPI-Spezifikation
Get Signature Status	GET /documents/{memberId}	Liefert den aktuellen Status einer Signaturanfrage (z. B. ausstehend, signiert, abgelehnt. Für die Abfrage wird die id des Senders verwendet, die bei der Erstellung der Signaturanfrage zurückgegeben wird.	OpenAPI-Spezifikation
Delete Document	DELETE /documents/{memberId}	Löscht ein Dokument oder entfernt den Zugriff eines einzelnen Members darauf. Die genaue Wirkung hängt davon ab, ob die memberId zum Sender oder zu einem/einer Empfänger:in gehört, ob das Dokument Teil eines Envelopes ist, und vom optionalen all-Flag.	OpenAPI-Spezifikation
Get Document	GET /documents/download/{memberId}	Lädt das signierte Dokument herunter — entweder als binäres PDF oder als Base64-codierten String (Parameter format).	OpenAPI-Spezifikation

Vollständige Endpunkt-Details, Request-/Response-Schemas und Fehlercodes: sproof Sign API-Dokumentation (interaktive Referenz, basierend auf der OpenAPI-Spezifikation).

Verwendung des Connectors

Verbindung: Erstellen Sie eine Verbindung mit Ihrem sproof Sign API-Token (Einstellungen → API Tokens in der sproof Sign Web-App).
Aktion: Fügen Sie den Connector zu einem Flow hinzu und wählen Sie eine der fünf oben aufgeführten Aktionen aus.
Requests verketten: Create Signature Request und Create Signature Request Using Placeholders geben für jede:n Empfänger:in die memberId zurück — speichern Sie diese (z. B. in einer Variable oder Ihrem Datenspeicher), um sie später mit Get Signature Status, Get Document oder Delete Document im selben oder einem anderen Flow zu verwenden.
Status abfragen (Polling): Get Request Status sendet keine automatischen Updates. Verwenden Sie einen wiederkehrenden/geplanten Flow oder eine Do until-Schleife mit Verzögerung, um den Status abzufragen, bis die Anfrage signiert, abgelehnt oder abgelaufen ist.
Ergebnisse herunterladen: Sobald eine Anfrage signiert ist (Status des Dokuments ist auf “completed”), rufen Sie Get Document mit format = pdf auf, um die Binärdatei zu erhalten (z. B. zum Speichern in SharePoint/OneDrive), oder mit format = base64, wenn der nächste Schritt einen Text-/JSON-Wert erwartet.
Platzhalter vs. explizite Felder: Verwenden Sie Create Signature Request Using Placeholders, wenn Empfänger:innen und Signaturpositionen bereits im Quelldokument definiert sind; verwenden Sie andernfalls Create Signature Request und geben Sie Empfänger:innen/Positionen im Flow an.

Bekanntes Problem: Konfiguration von recipientDetails

Bei „Create Signature Request“ ist „recipientDetails“ (innerhalb von „envelopeData“) keine feste Menge an Feldern, sondern ein Objekt, dessen Keys die E-Mail-Adressen der Empfänger:innen sind und dessen Werte die jeweiligen Empfängerdetails sind. Da Power Automate seine strukturierte Eingabeansicht anhand eines festen Schemas erstellt, kann es ein Feld, dessen Keys sich je Request ändern, weder darstellen noch ausfüllbar machen. In der Praxis bedeutet das:

recipientDetails kann nicht über die normale Eingabeansicht in Power Automate konfiguriert werden — das Feld erscheint leer, ausgegraut oder akzeptiert keinen dynamischen Inhalt.
Wechseln Sie stattdessen für dieses Feld in den Freitext- (bzw. Ausdrucks-)Modus — klicken Sie auf das Kontextmenü des Eingabefelds (das Symbol oben rechts am Feld, oder „…“ auf der Karte) und wählen Sie „Eingabe im Rohformat“ / „Switch to input entire array“ (die genaue Bezeichnung variiert je nach Connector-Version) — und geben Sie recipientDetails als reines JSON-Objekt ein, statt die geführten Felder zu nutzen.
Die als Keys verwendeten E-Mail-Adressen in recipientDetails müssen exakt mit den Empfänger-E-Mails in inviteData an anderer Stelle desselben Requests übereinstimmen. Stimmt ein Key nicht mit der E-Mail eines eingeladenen Empfängers/einer eingeladenen Empfängerin überein (auch bei Groß-/Kleinschreibung oder Tippfehlern), kann sproof Sign die Details nicht zuordnen — die Anfrage schlägt fehl oder die Details werden ignoriert.

Hier ist ein Ausschnitt aus einem „Create Signature Request“-Payload. In diesem Fall wurden zwei Empfänger definiert. Ein Signierender und eine Betrachterin:

...
recipientDetails: {
  max.mustermann@sproof.com: {
    role: 'signer',
    signaturePositions: [
      {
        page: 0,
        x: 0.57489,
        y: 0.8455,
        width: 0.35,
        height: 0.1
        }
      ]
    },
    maria.musterfrau@sproof.com: {
      role: 'viewer'
    }
}
...

Troubleshooting

{
  "message": "The document cannot be processed (Request failed with status code 400)",
  "errorCode": 422002,
  "traceId": "3497be3e4c516fd0fb41bb076e8aa1b3"
}

Fehler: „The document cannot be processed“ (400 / errorCode 422002)

Dieser Fehler wird meist dadurch verursacht, dass der im Feld data übergebene Wert kein gültiger Base64-String ist. So beheben Sie ihn:

Eingabe zuerst prüfen: Öffnen Sie den Ausführungsverlauf der Create Signature Request-Aktion und prüfen Sie den Eingabewert von data, um zu bestätigen, dass er tatsächlich Base64-codiert ist.
In string(...) einschließen: Auch wenn der Wert korrekt formatiert aussieht, sollten Sie ihn in den Ausdruck string() einschließen, um sicherzustellen, dass er als reiner Base64-String behandelt wird. Das ist besonders wichtig, wenn data ein dynamischer Wert aus einer vorherigen Aktion ist, da Power Automate ihn sonst in einem Typ durchreichen kann, der kein sauberer String ist.

Weiterführende Ressourcen

sproof Sign: Die richtige Integrationsstrategie finden (API)
Ein Beispiel für einen einfachen Signaturprozess mithilfe von „Create Signature Requests“: sproof Sign: Einholen von Signaturen (API)
Vollständige API-Referenz (alle Endpunkte, Schemas, Fehlercodes)