Créer un document à partir de votre PDF via l'API

Cette page s’adresse aux personnes qui intègrent AssinaJá à un autre programme. Elle explique comment créer un document à partir de votre propre PDF, sans modèle. Vous avez besoin d’une clé API ; la référence complète se trouve sous Ouvrir la documentation de l’API, dans Paramètres → Développeurs.

Les trois étapes

Demandez une adresse d’import : GET /api/public/v1/Document/GenerateSignedUploadUrl. La réponse contient uploadUrl et documentPublicId ; l’adresse est valable 1 heure.
Importez le PDF vers l’uploadUrl avec un PUT, accompagné des en-têtes x-ms-blob-type: BlockBlob et Content-Type: application/pdf.
Créez le document : POST /api/public/v1/Document/CreateDocument, avec le documentPublicId de l’étape 1. La réponse contient le documentId.

Le document est assemblé en arrière-plan. Envoyez un en-tête Idempotency-Key avec une valeur de votre choix (un UUID, par exemple) : si la même requête arrive de nouveau dans les 24 heures avec la même clé, vous recevez le même documentId et aucun second document n’est créé.

Un corps de requête valide

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

Le champ signatureType accepte Simple, SimpleInitials, OTPSMS, IdConfirmation, CMD, CMDSCAP ou LDC.

Où placer les zones de signature

Les zones de chaque signataire se placent dans signerRecipients[].documentRecipientSignatureLocations.

N’utilisez pas signatureLocations. Ce champ existe sur le signataire, mais c’est celui que renvoient les détails du document lorsqu’on les lit (GET /Document/{id}). Dans une requête de création, il est refusé avec SIGNATURE_LOCATIONS_WRONG_FIELD.

Chaque zone comporte :

pageNumber — 1 pour la première page ;
x, y, width et height — tous obligatoires, en pourcentage de la page (de 0 à 100), mesurés à partir du coin supérieur gauche ;
x + width au maximum 100, et y + height au maximum 100.

Un signataire sans zone n’est pas invité à signer.

Les erreurs renvoyées immédiatement par la requête

Elles arrivent sous forme de 400 avec { code, message, detail }, et aucun document n’est créé. Le detail indique le champ concerné, par exemple signerRecipients[1].phoneNumber.

`code`	Quand	Que faire
`NO_SIGNER_RECIPIENTS`	`signerRecipients` est vide.	Ajoutez au moins un signataire.
`SIGNATURE_LOCATIONS_WRONG_FIELD`	Les zones ont été envoyées dans `signatureLocations` et `documentRecipientSignatureLocations` est vide.	Déplacez-les dans `documentRecipientSignatureLocations`.
`INVALID_SIGNATURE_LOCATION`	Une zone est incomplète ou sort de la page.	Vérifiez la zone indiquée dans le `detail` au regard des règles ci-dessus.
`SIGNER_PHONE_REQUIRED`	Un signataire dont le `signatureType` est `OTPSMS` n’a pas de `phoneNumber`.	Ajoutez le numéro de mobile, ou choisissez un autre type de signature.
`NO_SIGNATURE_LOCATIONS`	Aucun signataire n’a de zone.	Attribuez une zone à au moins un signataire.

Les deux dernières ne s’appliquent que lorsque le document va être envoyé. Si l’organisation a activé la politique Les documents créés hors du navigateur commencent en brouillon, le document reste en brouillon pour qu’une personne le complète, et le numéro de mobile et les zones sont vérifiés au moment de l’envoi.

Suivre le document après sa création

Tant que le document est en cours d’assemblage, GET /api/public/v1/Document/{id} répond 409 avec le code document_processing. Réessayez un peu plus tard.

Certains problèmes ne se révèlent qu’une fois le PDF ouvert — une zone sur une page que le PDF ne comporte pas, par exemple. Dans ce cas, GET /Document/{id}, PATCH /Document/{id}/Publish, GET /Document/{id}/SignUrl et GET /Document/{id}/SignUrls répondent tous 400 avec :

code : DOCUMENT_CREATION_FAILED ;
message : “The creation of the document with id N failed: …”, suivi du motif ;
detail : le code d’origine — par exemple SIGNER_PHONE_REQUIRED, VALIDATION_ERROR ou INTERNAL_ERROR.

Une erreur interne apparaît uniquement sous la forme INTERNAL_ERROR, sans plus de détails. Un document plus ancien peut répondre sans motif après le message et sans detail.

Ce document est définitif — redemander ne change pas la réponse. Pour réessayer, recommencez à l’étape 1 : un nouveau GenerateSignedUploadUrl, un nouvel import (le documentPublicId utilisé est consommé) et une nouvelle Idempotency-Key.

Envoyer un brouillon

Un document qui a commencé en brouillon s’envoie avec PATCH /api/public/v1/Document/{id}/Publish — la méthode est PATCH, pas POST. La publication envoie le document aux signataires.