Tutorial Quickstart
Usi Cursor, Claude o un altro strumento AI per la programmazione? Collegalo alla documentazione Legalesign per un aiuto contestuale mentre segui questo tutorial.
In questo tutorial completerai le chiamate API chiave di cui la maggior parte degli sviluppatori ha bisogno per un'integrazione eSignature: caricare un documento e inviarlo per la firma.
L'API Legalesign è scalabile, versatile e testata in ambienti di produzione nei sistemi dei nostri clienti da molti anni. Puoi usarla per un documento con un solo firmatario, o inviare documenti per la testimonianza o approvazioni, ottimizzata per batch, con moduli e altro. Puoi integrare per uno scopo oppure 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, controlla l'interfaccia GraphQL. Legalesign è API-first con GraphQL. Puoi usare entrambi, come preferisci.
Seguiremo questi passaggi:
- Crea un account + API Key (vedi Come ottenere l'accesso API verificato).
- Conferma che le credenziali funzionano e ottieni il tuo ID team.
- Carica un documento tramite l'app web.
- Invia il documento per la firma tramite l'API.
- Scaricalo dopo la firma.
- Carica un documento tramite l'API.
L'API REST Legalesign è facile da usare. Il riferimento tecnico include un editor di codice. Puoi fare richieste direttamente dal riferimento tecnico con la tua api key, altrimenti copia e incolla direttamente nel tuo codice.
Figura 1: L'editor di codice REST API.
Librerie client
O per l'interfaccia GraphQL Node.js
Raccomandiamo agli sviluppatori di lavorare direttamente con l'API anziché con gli SDK. Per aiutarti, c'è un generatore di codice da tagliare e incollare nella specifica tecnica, e la tua AI può rapidamente produrre esempi usando la specifica OpenAPI. Perché? L'API sorgente ha più funzionalità degli SDK, alla fine vorrai comunque conoscere gli endpoint usati, eviterai overhead di astrazione e dipendenze e — in base alla nostra esperienza — finirai per ottenere risultati più rapidamente.
1. Crea un account
Vai a iscrizione Legalesign e segui il processo per creare un account.
Ti sarà chiesto di creare un team. I team sono i blocchi fondamentali di Legalesign. Tutto il trattamento dei documenti avviene in un team. Devi fare riferimento al tuo team nella maggior parte delle chiamate API.
Un 'team' o un 'gruppo' sono la stessa cosa. Nell'app web parliamo di 'team', mentre nello schema API è un gruppo.
Impostazioni API
Vai al Cruscotto API. Genera le tue credenziali API nella sezione API Key.
Prenditi un momento per rivedere il Portale Sviluppatori.
Sandbox
Nella sezione Ambiente, un avviso mostra se sei in modalità sandbox o produzione.
La Sandbox limita dove puoi inviare i tuoi documenti. Vedrai un form per aggiungere fino a 5 email approvate - aggiungine alcune ora.
Quando la tua integrazione è pronta: passa alla modalità produzione.
Crea un secondo team. Usa il primo team per lo sviluppo e l'altro team o altri per produzione. Comunica al supporto il nome del team dev per escluderlo dalla fatturazione.
API key
Nella sezione API Key vedrai i dettagli delle tue chiavi API. La chiave ti viene mostrata solo quando ne crei una nuova.
La sezione Quickstart contiene esempi da copiare e incollare per testare la tua chiave.
Webhooks & Log
Aggiungi webhooks (i tuoi listener per gli eventi Legalesign) e rivedi i tuoi log.
2. Una richiesta GET riuscita
L'URL root è sempre: https://eu-api.legalesign.com/
Inizia con una richiesta GET per confermare che le tue credenziali funzionano. Sostituisci i valori username e secret nel codice qui sotto.
Curl è usato negli esempi, puoi cambiare tra cURL, Node.js, Python, C#, e Go usando le tab sottostanti.
- cURL
- Node.js
- Python
- C#
- Go
curl -H "Authorization: ApiKey username:secret" -H "Content-Type: application/json" -X GET https://eu-api.legalesign.com/api/v1/group/
import fetch from 'node-fetch';
async function getGroups() {
const response = await fetch('https://eu-api.legalesign.com/api/v1/group/', {
method: 'GET',
headers: {
'Authorization': 'ApiKey username:secret',
'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);
});
import requests
headers = {
"Authorization": "ApiKey username:secret",
"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())
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", "ApiKey username:secret");
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);
}
}
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", "ApiKey username:secret")
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: GET group riferimenti API.
Quando esegui la query sopra, vedrai i tuoi gruppi restituiti in JSON. Successo. 👏
I dati della risposta contengono l'‘resource uri’ per il tuo gruppo e appare come /api/v1/group/:groupId/. Prendi nota di questo, ti servirà per la maggior parte delle chiamate API.
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 finiscono con uno slash. Lo stesso vale per gli URL delle tue chiamate API, terminare sempre con uno slash.
Se la richiesta GET fallisce controlla che:
- la tua ApiKey sia formattata correttamente (inizia con 'ApiKey'),
- tu abbia un header Content-Type per application/json, e
- il tuo url finisca con uno slash.
Vedi anche risoluzione problemi.
3. Carica un documento tramite l'app web
Per iniziare, caricheremo un documento tramite l'app web e lo invieremo tramite l'API. Come caricare un documento tramite l'API lo vedremo dopo.
Vai all'app web 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 aggiungere un ruolo firmatario senza un campo firma collegato).
Nell'editor del form, 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.
Nel linguaggio REST API l'URI di risorsa 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 lo invii crei un ‘documento’.
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 appaia mai e si cancelli dopo l'invio, dagli il titolo '[deleted]' — i nostri sistemi di pulizia lo rileveranno e lo elimineranno dopo un giorno o due. Puoi anche impostare tempi di conservazione brevi a livello di gruppo - scopri di più.
4. Invia un documento per la firma
Ora lo invieremo tramite l'API. Ricorda di usare una email approvata nella tua sandbox. Usa le tab sottostanti per ottenere la richiesta nella lingua che preferisci.
- cURL
- Node.js
- Python
- C#
- Go
curl -H "Authorization: ApiKey [username]:[secret]" -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/
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': 'ApiKey [username]:[secret]',
'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);
});
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": "ApiKey [username]:[secret]",
"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"))
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", "ApiKey [username]:[secret]");
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}");
}
}
}
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", "ApiKey [username]:[secret]")
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.
Quando visiti la documentazione di riferimento per inviare un documento dai un’occhiata a tutti gli attributi possibili. Ne vedrai molti che aiutano nelle praticità di un’integrazione — tag per i tuoi riferimenti e ID (che ti tornano indietro con i webhook), un redirect per i firmatari, impostare testo personalizzato nel pdf, e altro.
Una chiamata riuscita restituirà codice di stato 201. ✨
Ottieni l'ID del nuovo documento inviato
La parte importante della risposta è l'header location. Contiene il tuo nuovo ID documento.
Usa gli attributi ‘tag’ del documento e aggiungi i tuoi riferimenti per facilitare il collegamento con il tuo database.
L’header location apparirà come /api/v1/status/:documentId/.
L’URI ‘status’ restituisce un set breve (e veloce da interrogare) di attributi documento.
Per richiedere tutte le informazioni di un documento usa /api/v1/document/:documentId/.
Se una richiesta non va a buon fine il CORPO della risposta contiene solitamente informazioni sull'errore. Se non ottieni uno status di successo, controlla il CORPO 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 che hai ricevuto sopra, fai una richiesta di download PDF nella lingua che preferisci:
- cURL
- Node.js
- Python
- C#
- Go
curl -H "Authorization: ApiKey [username]:[secret]" -o download.pdf -X GET https://eu-api.legalesign.com/api/v1/pdf/:documentId/
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': 'ApiKey [username]:[secret]',
},
});
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);
});
import requests
headers = {"Authorization": "ApiKey [username]:[secret]"}
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)
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", "ApiKey [username]:[secret]");
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");
}
}
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", "ApiKey [username]:[secret]")
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 per download PDF.
Il binario PDF è nel corpo della risposta. Il comando curl '-o' mette il CORPO della risposta direttamente in un file.
Molte librerie REST o HTTP trattano gli oggetti risposta HTTP come file quindi basta salvare l’oggetto risposta come un file normale.
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, più informazioni sui campi modulo PDF seguiranno.
Per questa chiamata, converti il tuo PDF in una stringa codificata base64. Questo non è fatto correttamente nel generatore di codice della documentazione. Invece copia questo pseudocodice e la tua AI amichevole lo convertirà nel linguaggio preferito:
$data = (
'group': '/api/v1/group/:groupId/',
'title': 'title of pdf',
'pdf_file': base64encode(open('/path/to/file','rb')),
'process_tags': true
)
$headers = (
'Authorization': 'ApiKey username:secret',
'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']
Come al solito, una risposta POST riuscita restituirà stato ‘201’ e il nuovo ID sarà nell’intestazione location della risposta.
assert response.status == 201
pdfId = response.headers['location']
La tua URI risorsa pdf sarà come /api/v1/templatepdf/:pdfId/.
Invia il nuovo PDF
Torna al codice che usasti per inviare il tuo primo documento, e sostituisci il valore templatepdf.
Esegui di nuovo la richiesta e il gioco è fatto, hai inviato il PDF per la firma.
Prima di iniziare a programmare, però, continua a leggere per saperne di più sui campi PDF.
Che fine fanno i campi PDF?
Come fa Legalesign a sapere dove la persona deve firmare sul PDF, o le sezioni da modificare all'invio? La risposta è che il nostro PDF è stato preparato in anticipo con tag: mettiamo un tag testuale Legalesign dentro il PDF e impostiamo 'process_tags' a true nella richiesta di upload PDF.
Scarica un PDF di esempio con tag di testo.
I tag testuali sono testo formattato appositamente da inserire nel PDF. Legalesign analizza il testo nel tuo file, sostituendo i tag con campi firma e modulo. Per un firmatario basta aggiungere: <<t=signature>>. Legalesign lo identificherà e posizionerà la firma lì. Scopri i tag testuali.
I tag testuali hanno una curva di apprendimento e necessitano di tentativi. Altri metodi sono elencati sotto, ma ottieni la piena capacità del sistema moduli Legalesign con essi. Usa l’app web per testare i tag. Contatta supporto per assistenza ed esempi.
Ecco altri 4 modi per configurare i campi:
1. Versione più facile/veloce. Configura il PDF usando l’app web Legalesign.
Dopo aver caricato un PDF accederai all’interfaccia editor dove puoi trascinare e rilasciare campi modulo.
Trascina una firma, poi annota l’ID codificato nell’indirizzo web. Questo sarà qualcosa come 'dHBsMTRlZTQ0ZWUtZGE0Ni0xMWVmLTllZmUtMDI5ZGQ0ODkzZGRk'.
Decodifica in base64 questo ID e vedrai che è un UUID preceduto da 'tpl'. La parte UUID (rimuovi 'tpl') è il tuo pdfID. Scopri di più sugli ID Legalesign.
La tua API URI risorsa PDF sarà - /api/v1/templatepdf/:pdfId/.
Metti questo nell’attributo 'templatepdf' della chiamata invia documento.
Se prevedi di inviare questo PDF più di una volta, assicurati che ‘Auto archive’ sia disattivato. Ecco come
2. Usa coordinate x/y per i campi.
Il modo più semplice per iniziare con coordinate x/y è preparare un PDF nell'app web e poi interrogare via API quei campi (GET PDF Fields - /api/v1/templatepdf/:pdfId/fields/).
L'oggetto JSON che ricevi è esattamente lo stesso schema JSON che ti serve per creare i campi.
Usalo come modello. Modifica i valori e invialo di nuovo con POST allo stesso endpoint (modificando l’ID PDF di conseguenza). 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 il componente editor documento.
4. Campi modulo PDF NOVITÀ!
Se il tuo PDF contiene campi modulo PDF normali, Legalesign può importarli automaticamente.
Buona programmazione!
In questo tutorial hai acquisito credenziali API, interrogato con successo il tuo gruppo o gruppi, inviato un documento per la firma usando HTML e PDF, e scaricato un documento firmato.
Buona programmazione! Siamo qui per aiutarti, contatta supporto per assistenza.
Bravo, sei arrivato alla fine — grazie per aver letto. Il nostro consiglio finale, 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 della tua integrazione. Crea un documento da firmare.