Creare un documento dal suo PDF tramite l'API

Questa pagina è rivolta a chi integra AssinaJá con un altro programma. Spiega come creare un documento a partire da un suo PDF, senza modello. Serve una chiave API; il riferimento completo si trova in Apri la documentazione dell’API, in Impostazioni → Sviluppatori.

I tre passaggi

1. Chieda un indirizzo di caricamento: GET /api/public/v1/Document/GenerateSignedUploadUrl. La risposta contiene uploadUrl e documentPublicId; l’indirizzo vale 1 ora.
2. Carichi il PDF su uploadUrl con un PUT, con le intestazioni x-ms-blob-type: BlockBlob e Content-Type: application/pdf.
3. Crei il documento: POST /api/public/v1/Document/CreateDocument, con il documentPublicId del passaggio 1. La risposta contiene il documentId.

Il documento viene assemblato in background. Invii un’intestazione Idempotency-Key con un valore suo (un UUID, per esempio): se la stessa richiesta arriva di nuovo nelle 24 ore successive con la stessa chiave, riceve lo stesso documentId e non viene creato un secondo documento.

Un corpo valido

{
  "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 accetta Simple, SimpleInitials, OTPSMS, IdConfirmation, CMD, CMDSCAP o LDC.

Dove vanno le aree di firma

Le aree di ciascun firmatario vanno in signerRecipients[].documentRecipientSignatureLocations.

Non usi signatureLocations. Quel campo esiste nel firmatario, ma è quello che i dettagli del documento restituiscono in lettura (GET /Document/{id}). In una richiesta di creazione viene rifiutato con SIGNATURE_LOCATIONS_WRONG_FIELD.

Ogni area ha:

• pageNumber — 1 per la prima pagina;
• x, y, width e height — tutti obbligatori, in percentuale della pagina (da 0 a 100), misurati dall’angolo superiore sinistro;
• x + width al massimo 100, e y + height al massimo 100.

Un firmatario senza aree non viene invitato a firmare.

Errori che la richiesta restituisce subito

Arrivano come 400 con { code, message, detail }, e non viene creato alcun documento. Il detail indica il campo, per esempio signerRecipients[1].phoneNumber.

code	Quando	Che cosa fare
NO_SIGNER_RECIPIENTS	signerRecipients è vuoto.	Aggiunga almeno un firmatario.
SIGNATURE_LOCATIONS_WRONG_FIELD	Le aree sono arrivate in signatureLocations e documentRecipientSignatureLocations è vuoto.	Le sposti in documentRecipientSignatureLocations.
INVALID_SIGNATURE_LOCATION	Un’area è incompleta o esce dalla pagina.	Controlli l’area indicata nel detail rispetto alle regole qui sopra.
SIGNER_PHONE_REQUIRED	Un firmatario con signatureType OTPSMS non ha phoneNumber.	Aggiunga il cellulare, oppure scelga un altro tipo di firma.
NO_SIGNATURE_LOCATIONS	Nessun firmatario ha aree.	Assegni un’area ad almeno un firmatario.

Gli ultimi due si applicano solo quando il documento sta per essere inviato. Se l’organizzazione ha attivo il criterio I documenti creati fuori dal browser partono come bozza, il documento resta in bozza perché una persona lo completi, e il cellulare e le aree vengono verificati al momento dell’invio.

Seguire il documento dopo la creazione

Mentre il documento viene assemblato, GET /api/public/v1/Document/{id} risponde 409 con il code document_processing. Riprovi poco dopo.

Alcuni problemi emergono solo con il PDF aperto — un’area su una pagina che il PDF non ha, per esempio. In quel caso, GET /Document/{id}, PATCH /Document/{id}/Publish, GET /Document/{id}/SignUrl e GET /Document/{id}/SignUrls rispondono tutti 400 con:

• code: DOCUMENT_CREATION_FAILED;
• message: “The creation of the document with id N failed: …”, seguito dal motivo;
• detail: il codice originale — per esempio SIGNER_PHONE_REQUIRED, VALIDATION_ERROR o INTERNAL_ERROR.

Un errore interno compare solo come INTERNAL_ERROR, senza altri dettagli. Un documento più vecchio può rispondere senza motivo dopo il messaggio e senza detail.

Quel documento è definitivo — richiedere di nuovo non cambia la risposta. Per riprovare, ricominci dal passaggio 1: un nuovo GenerateSignedUploadUrl, un nuovo caricamento (il documentPublicId usato non è più valido) e una nuova Idempotency-Key.

Inviare una bozza

Un documento nato come bozza si invia con PATCH /api/public/v1/Document/{id}/Publish — il metodo è PATCH, non POST. La pubblicazione invia il documento ai firmatari.

Correlati

• Creare una chiave API
• Ricevere webhook
• Configurare i criteri dell’organizzazione