AcroFields (Campi PDF)

Gli AcroFields permettono di mappare automaticamente i campi di un modulo PDF (AcroForm) alle coordinate di firma o ai placeholder. Anziché specificare manualmente le coordinate positionX/positionY su ogni pagina, il sistema individua i campi del PDF per nome e li utilizza come aree di firma o campi compilabili.

Come Funzionano

Quando un PDF contiene campi AcroForm (creati con Adobe Acrobat, LibreOffice, ecc.), Askme Sign può individuarli automaticamente e mapparli a:

• Aree di firma: un campo AcroForm viene usato come posizione per la firma del firmatario
• Placeholder: un campo AcroForm viene convertito in un placeholder compilabile

La configurazione avviene a livello di firmatario nel campo acrofields dell'oggetto signers[].

---

Configurazione

Parametri

Campo	Tipo	Obbligatorio	Descrizione
acrofieldKeyword	string	Sì	Nome o pattern del campo AcroForm nel PDF da cercare.
acrofieldSignatureType	string	No	Tipo di firma da applicare se il campo è di tipo firma (codice azione: S, E, V, Q, ecc.).
acrofieldMatch	string	No	Strategia di corrispondenza del nome. Default: contains.

Modalità di Corrispondenza (acrofieldMatch)

Valore	Descrizione	Esempio
full	Corrispondenza esatta del nome del campo.	firma_cliente corrisponde solo a firma_cliente.
prefix	Il nome del campo inizia con la keyword.	firma corrisponde a firma_cliente, firma_responsabile.
postfix	Il nome del campo termina con la keyword.	cliente corrisponde a firma_cliente, nome_cliente.
contains	Il nome del campo contiene la keyword (default).	firma corrisponde a area_firma_1, firma_cliente.

---

Esempio

PDF con campi AcroForm

Supponiamo di avere un PDF con i seguenti campi AcroForm:

• firma_cliente (campo firma)
• firma_responsabile (campo firma)
• data_contratto (campo testo)
• nome_cliente (campo testo)

Richiesta API

{
  "documents": [
    { "filename": "contratto-acroform.pdf", "base64content": "..." }
  ],
  "name": "Contratto con AcroFields",
  "signers": [
    {
      "email": "[email protected]",
      "firstName": "Mario",
      "lastName": "Rossi",
      "action": "S",
      "acrofields": [
        {
          "acrofieldKeyword": "firma_cliente",
          "acrofieldSignatureType": "S",
          "acrofieldMatch": "full"
        }
      ]
    },
    {
      "email": "[email protected]",
      "firstName": "Luigi",
      "lastName": "Verdi",
      "action": "S",
      "acrofields": [
        {
          "acrofieldKeyword": "firma_responsabile",
          "acrofieldSignatureType": "S",
          "acrofieldMatch": "full"
        }
      ]
    }
  ]
}

Il sistema trova automaticamente i campi firma_cliente e firma_responsabile nel PDF e li usa come aree di firma per i rispettivi firmatari, senza bisogno di specificare le coordinate manuali.

---

Rilevamento AcroFields

Quando si carica un documento con l'endpoint POST /api/v2/documents/upload, la risposta indica se il PDF contiene campi AcroForm:

{
  "filename": "contratto-acroform.pdf",
  "pages": 3,
  "hasAcrofields": true,
  "acrofields": [
    { "keyword": "firma_cliente", "page": 3, "x": 100, "y": 700, "width": 200, "height": 50 },
    { "keyword": "firma_responsabile", "page": 3, "x": 350, "y": 700, "width": 200, "height": 50 }
  ]
}

Questo permette di conoscere i campi disponibili prima di creare la pratica.

---

Quando Usare gli AcroFields

Scenario	AcroFields	Coordinate manuali
PDF con campi form predefiniti	Sì	No
PDF generico senza campi	No	Sì
Template riutilizzabile con posizioni fisse	Opzionale	Sì
Integrazione con sistemi che generano PDF con campi	Sì	No

suggerimento

Gli AcroFields e le coordinate manuali possono essere combinati nella stessa pratica: usare AcroFields per i campi predefiniti nel PDF e coordinate manuali per posizioni aggiuntive.