Tutorial Quickstart

suggerimento

Utilizzi Cursor, Claude o un altro strumento di codifica AI? Collegalo alla documentazione Legalesign per un aiuto contestuale mentre segui questo tutorial.

In questo tutorial completerai le chiamate API essenziali di cui la maggior parte degli sviluppatori ha bisogno in un'integrazione eSignature: caricare un documento e inviarlo per la firma.

L'API Legalesign è scalabile, versatile e testata in produzione nei sistemi dei nostri clienti da molti anni. Puoi usarla per un documento semplice con un solo firmatario, o inviare documenti per testimoni o approvazioni, ottimizzata per lotti, con moduli e altro. Puoi integrare per uno scopo unico o incorporarla nel tuo software per i tuoi clienti - vedi integrazioni.

L'API REST esegue la maggior parte delle funzioni ed è il modo più semplice per iniziare. Se hai bisogno di altro, dai un’occhiata all’interfaccia GraphQL. Legalesign è API first con GraphQL. Puoi usare entrambi, a seconda delle tue preferenze.

Seguiremo questi passaggi:

1. Crea un account + API Key (vedi Come ottenere la verifica per l’accesso API).
2. Conferma che le credenziali funzionano e ottieni il tuo team ID.
3. Carica un documento tramite la web app.
4. Invialo per la firma tramite l'API.
5. Scaricalo dopo la firma.
6. Carica un documento tramite l’API.

L’API REST Legalesign è facile da usare. Il riferimento tecnico include un editor di codice. Puoi effettuare richieste direttamente dal riferimento tecnico con la tua API key, altrimenti puoi semplicemente copiare e incollare direttamente nel tuo codice.

Figura 1: L’Editor di codice dell’API REST.

Librerie client

• C# + Come fare
• Java
• Node.js
• PHP
• Python
• Ruby

Oppure per l’interfaccia GraphQL Node.js

suggerimento

Consigliamo agli sviluppatori di lavorare direttamente con l’API piuttosto che con gli SDK. Per aiutare, c’è un generatore di codice “copia-incolla” nella specifica tecnica, e la tua AI amichevole può produrre rapidamente esempi usando la specifica OpenAPI. Perché? L’API sorgente ha più funzionalità degli SDK, comunque dovrai conoscere gli endpoint usati, eviterai overhead di astrazione e dipendenze e — basandoci sulla nostra esperienza — otterrai il risultato più velocemente.

1. Crea un account

Vai a registrazione Legalesign e segui la procedura per creare un account.

Ti verrà chiesto di creare un team. I team sono i mattoni fondamentali di Legalesign. Tutto il processo documentale avviene all’interno di un team. Devi riferirti al tuo team nella maggior parte delle chiamate API.

informazioni

Un 'team' o un 'gruppo' sono la stessa cosa. Nell’app web parliamo di 'team', ma nello schema API si chiama gruppo.

Impostazioni API

Vai al Dashboard API. Genera le credenziali API nella sezione API Key.

Prenditi un momento per esplorare il Developer Portal.

Sandbox

Nella sezione Ambiente, un avviso indica se sei in modalità sandbox o produzione.

La modalità sandbox applica un limite di 100 chiamate all’ora. Non ci sono restrizioni sugli indirizzi email dei destinatari.

Quando l’integrazione è pronta: passa alla modalità produzione.

suggerimento

Crea un secondo team. Usa il primo team per sviluppo e l’altro/i team per produzione. Comunica a supporto il nome del team di sviluppo per escluderlo dalla fatturazione.

API key

Nella sezione API Key vedrai i dettagli delle tue chiavi API. Ti verrà mostrata solo la chiave quando la crei.

La sezione Quickstart contiene esempi “copia e incolla” per testare la tua chiave.

Webhooks & Log

Aggiungi webhooks (i tuoi listener per eventi Legalesign), e controlla i log.

2. Una richiesta GET riuscita

L’URL radice è sempre: https://eu-api.legalesign.com/

Inizia con una richiesta GET per confermare che le tue credenziali funzionano. Sostituisci your_api_key con la tua chiave del Developer Portal.

Curl viene utilizzato negli esempi, e puoi passare tra cURL, Node.js, Python, C# e Go usando le schede in basso.

cURL

curl -H "Authorization: Bearer your_api_key" -H "Content-Type: application/json" -X GET https://eu-api.legalesign.com/api/v1/group/

Node.js

import fetch from 'node-fetch';

async function getGroups() {
  const response = await fetch('https://eu-api.legalesign.com/api/v1/group/', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer your_api_key',
      'Content-Type': 'application/json',
    },
  });

  if (!response.ok) {
    throw new Error(`Request failed with status ${response.status}`);
  }

  const data = await response.json();
  console.log(data);
}

getGroups().catch((error) => {
  console.error(error);
  process.exit(1);
});

Python

import requests

headers = {
    "Authorization": "Bearer your_api_key",
    "Content-Type": "application/json",
}

response = requests.get(
    "https://eu-api.legalesign.com/api/v1/group/",
    headers=headers,
    timeout=30,
)
response.raise_for_status()

print(response.json())

C#

using System;
using System.Net.Http;
using System.Threading.Tasks;

public class Program
{
    public static async Task Main()
    {
        using var client = new HttpClient();
        using var request = new HttpRequestMessage(
            HttpMethod.Get,
            "https://eu-api.legalesign.com/api/v1/group/"
        );

        request.Headers.TryAddWithoutValidation("Authorization", "Bearer your_api_key");
        request.Headers.TryAddWithoutValidation("Content-Type", "application/json");

        using var response = await client.SendAsync(request);
        response.EnsureSuccessStatusCode();

        var body = await response.Content.ReadAsStringAsync();
        Console.WriteLine(body);
    }
}

Go

package main

import (
	"fmt"
	"io"
	"log"
	"net/http"
)

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://eu-api.legalesign.com/api/v1/group/", nil)
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("Authorization", "Bearer your_api_key")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	if resp.StatusCode >= 400 {
		log.Fatalf("request failed: %s", resp.Status)
	}

	body, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(body))
}

Documentazione API: Riferimento API GET group.

Quando esegui la query sopra, vedrai ritornati i tuoi gruppi in JSON. Successo. 👏

I dati di risposta contengono il 'resource uri' per il tuo gruppo e sarà simile a /api/v1/group/:groupId/. Prendi nota, ti servirà per la maggior parte delle chiamate API.

suggerimento

Un resource uri sarà sempre formattato allo stesso modo. Per un PDF sarà '/api/v1/templatepdf/:pdfId/', per un documento inviato sarà '/api/v1/document/:documentId/'. Nota come tutti gli URI terminano con una barra. Vale anche per gli URL delle tue chiamate API, terminano sempre con una barra.

Se la richiesta GET è fallita, verifica che:

• l’header Authorization sia formattato correttamente (inizia con Bearer ),
• hai un header Content-Type con application/json, e
• il tuo url termina con una barra.

Vedi anche risoluzione problemi.

3. Carica un documento tramite web app

Per iniziare, caricheremo un documento tramite la web app e lo invieremo tramite API. Copriremo come caricare un documento tramite API più avanti.

Vai alla web app e carica il tuo documento. Aggiungi un ruolo firmatario singolo e trascina un campo firma. La pagina dell’editor indicherà se il documento è 'valido' (un esempio di 'non valido' potrebbe essere l’aggiunta di un ruolo firmatario senza un campo firma correlato).

Nell’editor del modulo, copia il lungo ID alfanumerico dall’URL, decodificalo in base64 e scarta le prime 3 lettere (che dovrebbero essere 'tpl'). Il resto è un UUID che è il tuo ID.

In linguaggio REST API, il resource uri per questo documento è /api/v1/templatepdf/UUID/.

Scopri di più su ID web e API.

La nostra nomenclatura è che un documento caricato è un “template” e quando ne invii uno crei un “documento”.

suggerimento

Se vuoi archiviare un template quando il documento viene inviato, imposta 'archive_upon_send' come attributo nella richiesta di upload. Se vuoi che il template non compaia mai e venga cancellato dopo l’invio, dagli il titolo '[deleted]' - i nostri sistemi di pulizia lo rileveranno e lo cancelleranno dopo uno o due giorni. Puoi anche impostare tempi di conservazione brevi a livello di gruppo - scopri di più.

4. Invia un documento per la firma

Ora invieremo questo tramite API. Usa le schede qui sotto per ottenere la richiesta nella lingua che preferisci.

cURL

curl -H "Authorization: Bearer your_api_key" -H "Content-Type: application/json" -X POST --data '{ "group": "/api/v1/group/[:groupId]/", "name": "Name of doc", "templatepdf": "/api/v1/templatepdf/UUID/", "signers": [{"firstname": "Joe", "lastname": "Bloggs", "email": "[your@email.com]", "order": 0 }], "do_email": true }' https://eu-api.legalesign.com/api/v1/document/

Node.js

import fetch from 'node-fetch';

const payload = {
  group: '/api/v1/group/[:groupId]/',
  name: 'Name of doc',
  templatepdf: '/api/v1/templatepdf/UUID/',
  signers: [
    {
      firstname: 'Joe',
      lastname: 'Bloggs',
      email: '[your@email.com]',
      order: 0,
    },
  ],
  do_email: true,
};

async function sendDocument() {
  const response = await fetch('https://eu-api.legalesign.com/api/v1/document/', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_api_key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(payload),
  });

  if (response.status !== 201) {
    const errorBody = await response.text();
    throw new Error(`Request failed with status ${response.status}: ${errorBody}`);
  }

  console.log('Document sent successfully');
  const location = response.headers.get('location');
  if (location) {
    console.log(`Location: ${location}`);
  }
}

sendDocument().catch((error) => {
  console.error(error);
  process.exit(1);
});

Python

import requests

payload = {
    "group": "/api/v1/group/[:groupId]/",
    "name": "Name of doc",
    "templatepdf": "/api/v1/templatepdf/UUID/",
    "signers": [
        {
            "firstname": "Joe",
            "lastname": "Bloggs",
            "email": "[your@email.com]",
            "order": 0,
        }
    ],
    "do_email": true,
}

headers = {
    "Authorization": "Bearer your_api_key",
    "Content-Type": "application/json",
}

response = requests.post(
    "https://eu-api.legalesign.com/api/v1/document/",
    json=payload,
    headers=headers,
    timeout=30,
)
response.raise_for_status()

print("Document sent successfully")
print("Location:", response.headers.get("Location"))

C#

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

public class Program
{
    public static async Task Main()
    {
        var payload = new
        {
            group = "/api/v1/group/[:groupId]/",
            name = "Name of doc",
            templatepdf = "/api/v1/templatepdf/UUID/",
            signers = new[]
            {
                new
                {
                    firstname = "Joe",
                    lastname = "Bloggs",
                    email = "[your@email.com]",
                    order = 0,
                },
            },
            do_email = true,
        };

        using var client = new HttpClient();
        using var request = new HttpRequestMessage(
            HttpMethod.Post,
            "https://eu-api.legalesign.com/api/v1/document/"
        );
        request.Headers.TryAddWithoutValidation("Authorization", "Bearer your_api_key");

        var json = JsonSerializer.Serialize(payload);
        request.Content = new StringContent(json, Encoding.UTF8, "application/json");

        using var response = await client.SendAsync(request);
        response.EnsureSuccessStatusCode();

        Console.WriteLine("Document sent successfully");
        if (response.Headers.Location is not null)
        {
            Console.WriteLine($"Location: {response.Headers.Location}");
        }
    }
}

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
)

func main() {
	payload := map[string]any{
		"group": "/api/v1/group/[:groupId]/",
		"name":  "Name of doc",
		"templatepdf": "/api/v1/templatepdf/UUID/",
		"signers": []map[string]any{
			{
				"firstname": "Joe",
				"lastname":  "Bloggs",
				"email":     "[your@email.com]",
				"order":     0,
			},
		},
		"do_email": true,
	}

	body, err := json.Marshal(payload)
	if err != nil {
		log.Fatal(err)
	}

	req, err := http.NewRequest(
		http.MethodPost,
		"https://eu-api.legalesign.com/api/v1/document/",
		bytes.NewReader(body),
	)
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("Authorization", "Bearer your_api_key")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusCreated {
		log.Fatalf("unexpected status: %s", resp.Status)
	}

	fmt.Println("Document sent successfully")
	fmt.Println("Location:", resp.Header.Get("Location"))
}

Aggiorna tutte le parentesi quadre. Riferimento API per inviare un documento.

suggerimento

Quando visiti la documentazione di riferimento per l’invio di un documento, dai un’occhiata approfondita a tutti gli attributi possibili. Vedrai molti che aiutano con le pratiche di integrazione — tag per i tuoi riferimenti e ID (che ti tornano nei webhook), un redirect per i firmatari, testo personalizzato nel pdf, e altro.

Una chiamata riuscita ritorna il codice di stato 201. ✨

Ottieni il nuovo ID del documento inviato

La parte importante della risposta è l’header location. Contiene il tuo nuovo ID documento.

suggerimento

Usa gli attributi 'tag' del documento e aggiungi i tuoi riferimenti per facilitare il collegamento con il tuo database.

L’header location sarà simile a /api/v1/status/:documentId/.

L’URI 'status' ritorna un set breve (e veloce da interrogare) di attributi documento.

Per richiedere tutto da un documento usa /api/v1/document/:documentId/.

informazioni

Se una richiesta ha esito negativo, il BODY della risposta solitamente contiene informazioni sull’errore. Se non ottieni un successo, controlla il BODY per un testo esplicativo. Vedi anche risoluzione problemi.

Scopri di più sulla chiamata API Send Document.

5. Scarica il documento firmato

Con l’ID del documento inviato ricevuto sopra, fai una richiesta di download PDF nella lingua che preferisci:

cURL

curl -H "Authorization: Bearer your_api_key" -o download.pdf -X GET https://eu-api.legalesign.com/api/v1/pdf/:documentId/

Node.js

import { writeFile } from 'node:fs/promises';
import fetch from 'node-fetch';

async function downloadPdf() {
  const response = await fetch('https://eu-api.legalesign.com/api/v1/pdf/:documentId/', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer your_api_key',
    },
  });

  if (!response.ok) {
    throw new Error(`Request failed with status ${response.status}`);
  }

  const buffer = await response.arrayBuffer();
  await writeFile('download.pdf', Buffer.from(buffer));
  console.log('Saved download.pdf');
}

downloadPdf().catch((error) => {
  console.error(error);
  process.exit(1);
});

Python

import requests

headers = {"Authorization": "Bearer your_api_key"}

response = requests.get(
    "https://eu-api.legalesign.com/api/v1/pdf/:documentId/",
    headers=headers,
    stream=True,
    timeout=30,
)
response.raise_for_status()

with open("download.pdf", "wb") as file:
    for chunk in response.iter_content(chunk_size=8192):
        file.write(chunk)

C#

using System;
using System.IO;
using System.Net.Http;
using System.Threading.Tasks;

public class Program
{
    public static async Task Main()
    {
        using var client = new HttpClient();
        using var request = new HttpRequestMessage(
            HttpMethod.Get,
            "https://eu-api.legalesign.com/api/v1/pdf/:documentId/"
        );
        request.Headers.TryAddWithoutValidation("Authorization", "Bearer your_api_key");

        using var response = await client.SendAsync(request);
        response.EnsureSuccessStatusCode();

        var bytes = await response.Content.ReadAsByteArrayAsync();
        await File.WriteAllBytesAsync("download.pdf", bytes);
        Console.WriteLine("Saved download.pdf");
    }
}

Go

package main

import (
	"io"
	"log"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest(
		http.MethodGet,
		"https://eu-api.legalesign.com/api/v1/pdf/:documentId/",
		nil,
	)
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("Authorization", "Bearer your_api_key")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	if resp.StatusCode >= 400 {
		log.Fatalf("request failed: %s", resp.Status)
	}

	file, err := os.Create("download.pdf")
	if err != nil {
		log.Fatal(err)
	}
	defer file.Close()

	if _, err := io.Copy(file, resp.Body); err != nil {
		log.Fatal(err)
	}

	log.Println("Saved download.pdf")
}

Riferimento API download PDF.

Il binario PDF è nel corpo della risposta. Il comando curl '-o' mette il BODY della risposta direttamente in un file.

Molte librerie REST o HTTP trattano gli oggetti di risposta HTTP come file, quindi salva semplicemente il tuo oggetto risposta come un normale file.

suggerimento

Usa i webhook per essere notificato di un evento firma e poi scaricare il documento. Vedi webhooks.

6. Carica un PDF

Click qui per scaricare un PDF di esempio con tag di testo, maggiori informazioni sui campi modulo PDF seguiranno.

Per questa chiamata, converti il tuo PDF in una stringa codificata base64. Questo non è correttamente fatto nel generatore di codice della documentazione. Copia invece questo pseudocodice e la tua AI amichevole lo convertirà nella tua lingua preferita:

$data = (
  'group': '/api/v1/group/:groupId/',
  'title': 'title of pdf',
  'pdf_file': base64encode(open('/path/to/file','rb')),
  'process_tags': true
)
$headers = (
  'Authorization': 'Bearer your_api_key',
  'Content-Type': 'application/json'
)
response = httplibrary.post('https://eu-api.legalesign.com/api/v1/templatepdf/', jsonEncode($data), $headers)
assert response.status == 201

pdfId = response.headers['location']

Riferimento API upload PDF.

Come al solito, una risposta POST riuscita restituirà il codice '201' e il nuovo ID sarà nell’header 'location' della risposta.

assert response.status == 201
pdfId = response.headers['location']

La tua resource URI pdf sarà simile a /api/v1/templatepdf/:pdfId/.

Invia il nuovo PDF

Torna al codice usato per inviare il primo documento e sostituisci il valore templatepdf.

Invia nuovamente la richiesta e il gioco è fatto, hai inviato il PDF per la firma.

Prima di iniziare a scrivere codice, però, continua a leggere per approfondire i campi PDF.

Che fine fanno i campi PDF?

Come fa Legalesign a sapere dove la persona deve firmare sul PDF, o quali sezioni modificare all’invio? La risposta è che il nostro PDF è stato pre-preparato con tag: mettiamo un tag testo Legalesign all’interno del PDF e impostiamo 'process_tags' a true nella richiesta di upload PDF.

Scarica un PDF di esempio con tag di testo.

I tag di testo sono testi formattati appositamente da inserire in un PDF. Legalesign analizzerà il testo nel file, sostituendo i tag con campi firma e moduli. Per un solo firmatario basta aggiungere: <<t=signature>>. Legalesign lo individuerà e posizionerà la firma lì. Scopri i text tags.

I text tags hanno una curva di apprendimento e richiedono prove ed errori. Ci sono altri metodi indicati di seguito, ma con i text tags ottieni la piena capacità del sistema moduli Legalesign. Usa la web app per testare i tag. Contatta il supporto per assistenza ed esempi.

Ecco 4 altri modi per impostare i campi:

1. Versione più facile/veloce. Imposta il tuo PDF usando la web app Legalesign.

Dopo aver caricato un PDF arriverai all’interfaccia editor dove puoi trascinare campi modulo.

Trascina una firma, poi prendi nota dell’ID codificato nell’indirizzo web. Sarà simile a 'dHBsMTRlZTQ0ZWUtZGE0Ni0xMWVmLTllZmUtMDI5ZGQ0ODkzZGRk'.

Decodifica l’ID in base64 e vedrai che è un UUID preceduto da 'tpl'. La parte UUID (rimuovi 'tpl') è il tuo pdfID. Scopri di più sugli ID Legalesign.

La tua resource URI API PDF sarà - /api/v1/templatepdf/:pdfId/.

Inseriscilo nell’attributo 'templatepdf' della chiamata send document.

informazioni

Se prevedi di inviare questo PDF più volte, assicurati che 'Auto archive' sia disattivato. Vedi come

2. Usa coordinate x/y per i campi.

Il modo più semplice per iniziare con coordinate x/y è configurare un PDF nella web app e poi fare una query API per quei campi (GET PDF Fields - /api/v1/templatepdf/:pdfId/fields/).

L’oggetto JSON che ricevi è lo stesso schema JSON necessario per creare campi.

Usalo come modello. Modifica i valori e POSTalo di nuovo allo stesso endpoint (modificando il PDF ID se appropriato). Endpoint Create PDF Field.

3. Incorpora la nostra pagina di modifica PDF. NOVITÀ!

Usa il nostro componente editor per incorporare il nostro editor PDF direttamente nella tua app. Scopri di più sul componente Document editor.

4. Campi modulo PDF NOVITÀ!

Se il tuo PDF contiene campi modulo PDF normali, Legalesign può importarli automaticamente.

Buona programmazione!

In questo tutorial hai ottenuto le credenziali API, interrogato con successo il tuo/i tuoi gruppi, inviato un documento per la firma usando HTML e PDF e scaricato un documento firmato.

Buona programmazione! Siamo qui per aiutarti, contatta il supporto per qualsiasi assistenza.

suggerimento

Ottimo, sei arrivato alla fine — grazie per aver letto. La nostra ultima richiesta e consiglio, basato su anni di esperienza di sviluppatori che integrano con questa API, è di prenderti un momento per leggere tutti gli attributi dell’endpoint crea documento (e cliccare per vedere cosa contengono 'signers', 'pdftext' e 'signertext') — è la chiamata più importante nella tua integrazione. Crea un documento di firma.

Passi successivi:

• Webhooks per notifiche in tempo reale
• Incorpora l’editor moduli
• Incorpora la pagina firma