Ein Dokument aus Ihrem PDF über die API erstellen

Diese Seite richtet sich an alle, die AssinaJá mit einem anderen Programm integrieren. Sie erklärt, wie Sie ein Dokument aus einem eigenen PDF erstellen, ohne Vorlage. Sie brauchen einen API-Schlüssel; die vollständige Referenz finden Sie unter API-Dokumentation öffnen, in Einstellungen → Entwickler.

Die drei Schritte

Fordern Sie eine Upload-Adresse an: GET /api/public/v1/Document/GenerateSignedUploadUrl. Die Antwort enthält uploadUrl und documentPublicId; die Adresse gilt 1 Stunde.
Laden Sie das PDF mit einem PUT an die uploadUrl hoch, mit den Headern x-ms-blob-type: BlockBlob und Content-Type: application/pdf.
Erstellen Sie das Dokument: POST /api/public/v1/Document/CreateDocument, mit der documentPublicId aus Schritt 1. Die Antwort enthält die documentId.

Das Dokument wird im Hintergrund zusammengestellt. Senden Sie einen Header Idempotency-Key mit einem eigenen Wert (zum Beispiel einer UUID): Kommt dieselbe Anfrage innerhalb der folgenden 24 Stunden mit demselben Schlüssel erneut an, erhalten Sie dieselbe documentId, und es wird kein zweites Dokument erstellt.

Ein gültiger Body

{
  "documentPublicId": "<documentPublicId do passo 1>",
  "emailSubject": "Por favor assine o contrato",
  "emailMessage": "Segue o contrato de que falámos.",
  "signerRecipients": [
    {
      "name": "Maria Silva",
      "email": "maria@example.pt",
      "phoneNumber": "+351912345678",
      "signatureType": "OTPSMS",
      "protectionMode": "None",
      "order": 1,
      "documentRecipientSignatureLocations": [
        { "pageNumber": 2, "x": 10, "y": 80, "width": 30, "height": 8 }
      ]
    }
  ]
}

signatureType akzeptiert Simple, SimpleInitials, OTPSMS, IdConfirmation, CMD, CMDSCAP oder LDC.

Wohin die Signaturfelder gehören

Die Felder jedes Unterzeichners gehören in signerRecipients[].documentRecipientSignatureLocations.

Verwenden Sie nicht signatureLocations. Dieses Feld gibt es beim Unterzeichner, aber es ist das, was die Dokumentdetails beim Lesen zurückgeben (GET /Document/{id}). In einer Erstellungsanfrage wird es mit SIGNATURE_LOCATIONS_WRONG_FIELD abgelehnt.

Jedes Feld hat:

pageNumber — 1 für die erste Seite;
x, y, width und height — alle Pflicht, in Prozent der Seite (0 bis 100), gemessen von der linken oberen Ecke;
x + width höchstens 100 und y + height höchstens 100.

Ein Unterzeichner ohne Felder wird nicht zur Unterschrift eingeladen.

Fehler, die die Anfrage sofort zurückgibt

Sie kommen als 400 mit { code, message, detail }, und es wird kein Dokument erstellt. detail nennt das betroffene Feld, zum Beispiel signerRecipients[1].phoneNumber.

`code`	Wann	Was zu tun ist
`NO_SIGNER_RECIPIENTS`	`signerRecipients` ist leer.	Fügen Sie mindestens einen Unterzeichner hinzu.
`SIGNATURE_LOCATIONS_WRONG_FIELD`	Die Felder kamen in `signatureLocations`, und `documentRecipientSignatureLocations` ist leer.	Verschieben Sie sie nach `documentRecipientSignatureLocations`.
`INVALID_SIGNATURE_LOCATION`	Ein Feld ist unvollständig oder ragt über die Seite hinaus.	Prüfen Sie das in `detail` genannte Feld anhand der obigen Regeln.
`SIGNER_PHONE_REQUIRED`	Ein Unterzeichner mit `signatureType` `OTPSMS` hat keine `phoneNumber`.	Ergänzen Sie die Mobilnummer oder wählen Sie einen anderen Signaturtyp.
`NO_SIGNATURE_LOCATIONS`	Kein Unterzeichner hat Felder.	Geben Sie mindestens einem Unterzeichner ein Feld.

Die letzten beiden gelten nur, wenn das Dokument versendet werden soll. Hat die Organisation die Richtlinie Außerhalb des Browsers erstellte Dokumente beginnen als Entwurf aktiviert, bleibt das Dokument ein Entwurf, den eine Person vervollständigt, und Mobilnummer und Felder werden beim Versand geprüft.

Das Dokument nach der Erstellung verfolgen

Solange das Dokument zusammengestellt wird, antwortet GET /api/public/v1/Document/{id} mit 409 und dem code document_processing. Fragen Sie kurz danach erneut.

Manche Probleme zeigen sich erst, wenn das PDF geöffnet ist — etwa ein Feld auf einer Seite, die das PDF nicht hat. In diesem Fall antworten GET /Document/{id}, PATCH /Document/{id}/Publish, GET /Document/{id}/SignUrl und GET /Document/{id}/SignUrls alle mit 400 und:

code: DOCUMENT_CREATION_FAILED;
message: “The creation of the document with id N failed: …”, gefolgt vom Grund;
detail: der ursprüngliche Code — zum Beispiel SIGNER_PHONE_REQUIRED, VALIDATION_ERROR oder INTERNAL_ERROR.

Ein interner Fehler erscheint nur als INTERNAL_ERROR, ohne weitere Details. Ein älteres Dokument kann ohne Grund nach der Meldung und ohne detail antworten.

Dieses Dokument ist endgültig — erneutes Fragen ändert die Antwort nicht. Für einen neuen Versuch beginnen Sie wieder bei Schritt 1: eine neue GenerateSignedUploadUrl, ein neuer Upload (die verwendete documentPublicId ist verbraucht) und ein neuer Idempotency-Key.

Einen Entwurf senden

Ein Dokument, das als Entwurf begonnen hat, wird mit PATCH /api/public/v1/Document/{id}/Publish gesendet — die Methode ist PATCH, nicht POST. Das Veröffentlichen sendet das Dokument an die Unterzeichner.