Tutorial Quickstart

suggerimento

Usi Cursor, Claude o un altro strumento di 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 da 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 semplice documento con un firmatario solo o inviare documenti per testimoni o approvazioni, ottimizzati per batch, con moduli e altro. Puoi integrare per uno scopo specifico o incorporarla nel tuo software per i tuoi clienti - vedi integrazioni.

La REST API esegue la maggior parte delle funzioni ed è il modo più semplice per iniziare. Se vuoi di più, guarda l'interfaccia GraphQL. Legalesign è API first con GraphQL. Puoi usare entrambe, come preferisci.

Seguiamo questi passaggi:

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

L’API REST Legalesign è facile da usare. La riferimento tecnico include un editor di codice. Puoi effettuare richieste direttamente dalla sezione di riferimento tecnico con la tua chiave API, altrimenti basta copiare e incollare direttamente nel tuo codice.

Figura 1: L’Editor del Codice REST API.

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 da copiare e incollare nella specifica tecnica, e la tua AI può produrre rapidamente esempi usando la specifica OpenAPI. Perché? L’API sorgente ha più funzionalità rispetto agli SDK, alla fine vorrai comunque conoscere gli endpoint che usi, eviterai costi di astrazione e dipendenze e — basandoci sulla nostra esperienza — finirai il lavoro più velocemente.

1. Crea un account

Vai su sign up Legalesign e segui il processo per creare un account.

Ti verrà chiesto di creare un team. I team sono i mattoni fondamentali di Legalesign. Tutta la lavorazione dei documenti avviene in un team. Devi fare riferimento 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 è un gruppo.

Impostazioni API

Vai alla Dashboard API. Genera le tue credenziali API nella sezione Chiave API.

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 la tua integrazione è pronta: passa in modalità produzione.

suggerimento

Crea un secondo team. Usa il primo per sviluppo e altri team per produzione. Comunica all’assistenza il nome del tuo team di sviluppo per esentarlo dalla fatturazione.

Chiave API

Nella sezione Chiave API vedrai i dettagli delle tue chiavi. La chiave stessa viene mostrata solo quando la crei.

Il Developer Portal contiene esempi da copiare e incollare per testare la tua chiave.

Webhook & Log

Aggiungi webhook (i tuoi ascoltatori per eventi Legalesign) e controlla i log.

2. Una richiesta GET riuscita

L’URL di base è 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 dal Developer Portal.

Nei esempi viene usato curl, e puoi passare tra cURL, Node.js, Python, C# e Go usando le schede qui sotto.

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: GET gruppo Riferimento API.

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

I dati di risposta contengono l’‘URI risorsa’ del tuo gruppo e assomiglia a /api/v1/group/:groupId/. Prendi nota di questo, ti servirà per la maggior parte delle chiamate API.

suggerimento

Un URI risorsa sarà sempre formattato nello stesso modo. Per un PDF sarebbe '/api/v1/templatepdf/:pdfId/', per un documento inviato sarà '/api/v1/document/:documentId/'. Nota come tutti gli URI terminano con una barra. Lo stesso vale per gli URL delle chiamate API, terminano sempre con una barra.

Se la richiesta GET fallisce, verifica che:

• l’header Authorization sia formattato correttamente (inizia con Bearer ),
• hai un header Content-Type per application/json, e
• l’URL termini con una barra.

Vedi anche risoluzione problemi.

3. Carica un documento tramite l’app web

Per iniziare, caricheremo un documento attraverso l’app web e lo invieremo poi tramite API. Tratteremo come caricare un documento tramite API dopo.

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

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

L’ID REST API per questo documento è /api/v1/templatepdf/UUID/.

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 appaia mai e venga eliminato dopo l’invio, dagli il titolo '[deleted]' - i nostri sistemi di pulizia lo rileveranno ed elimineranno 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 prendere 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 inviare un documento dai un’occhiata approfondita a tutti gli attributi possibili. Vedrai molti che saranno utili nella pratica di un’integrazione - tag per i tuoi riferimenti e ID (che ti tornano via webhook), un redirect per i firmatari, testo personalizzato nel pdf, e altro ancora.

Una chiamata riuscita restituirà codice di stato 201. ✨

Ottieni il nuovo ID 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à del tipo /api/v1/status/:documentId/.

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

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

informazioni

Se una richiesta non ha successo, il CORPO della risposta di solito contiene informazioni sull’errore. Se non ricevi un codice di successo, controlla il CORPO per un testo esplicativo. Vedi anche risoluzione problemi.

Approfondisci la chiamata API Invia Documento.

5. Scarica il documento firmato

Con l’ID del documento inviato che hai ricevuto sopra, effettua 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 CORPO della risposta direttamente in un file.

Molte librerie REST o HTTP trattano gli oggetti risposta HTTP come se fossero file, in tal caso salva semplicemente il tuo oggetto risposta come un file normale.

suggerimento

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

6. Carica un documento tramite API

Click qui per scaricare un PDF di esempio con tag di testo, più informazioni sui campi modulo PDF a seguire.

Per questa chiamata, converti il tuo PDF in una stringa codificata base64. Questo non è fatto correttamente nel generatore di codice della documentazione. Copia questo pseudocodice e l'AI lo convertirà nella 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.

Una risposta POST riuscita restituirà stato 201 e il nuovo ID sarà nell’header di risposta location.

Il tuo URI risorsa pdf sarà del tipo /api/v1/templatepdf/:pdfId/.

Altri formati di file

Word, HTML, testo semplice, XLSX e file immagine sono tutti supportati. Caricali usando l’uploader file GraphQL, che rileva automaticamente il formato e converte in PDF. Recupera l’ID e invialo tramite REST API come al solito. Vedi anche comprendere REST e GraphQL IDs. I text tag verranno riconosciuti normalmente.

Invia il nuovo PDF

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

Effettua di nuovo la richiesta e il gioco è fatto, hai inviato il tuo PDF per la firma.

Prima di iniziare a programmare, però, continua a leggere per saperne di più sui campi PDF.

Cosa succede con 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 era pre-preparato con tag: abbiamo inserito un text tag Legalesign all’interno del PDF e impostato 'process_tags' su true nella richiesta di upload PDF.

Scarica un PDF di esempio con tag di testo.

I text tag sono testo formattato appositamente per essere inserito in un PDF. Legalesign analizzerà il testo nel tuo file, sostituendo i tag con campi firma e modulo. Per un firmatario è sufficiente aggiungere: <<t=signature>>. Legalesign lo identificherà e posizionerà la firma lì. Scopri di più sui text tag.

Altri metodi per localizzare i tuoi campi sono descritti in seguito, ma con i text tag ottieni la piena capacità del sistema di moduli Legalesign. Usa l’app web per testare i tuoi tag. Contatta il supporto per assistenza ed esempi.

Ecco 4 altri modi per impostare i campi:

1. Versione più semplice/veloce. Imposta il tuo PDF usando l’app web Legalesign.

Dopo aver caricato un PDF, accederai all’interfaccia editor dove puoi trascinare i campi modulo.

Trascina una firma, quindi prendi nota dell’ID codificato nell’indirizzo web. Sarà qualcosa come 'dHBsMTRlZTQ0ZWUtZGE0Ni0xMWVmLTllZmUtMDI5ZGQ0ODkzZGRk'.

Decodifica 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.

Il tuo URI risorsa PDF API sarà - /api/v1/templatepdf/:pdfId/.

Inseriscilo nell’attributo 'templatepdf' della chiamata per inviare il documento.

informazioni

Se intendi 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 è impostare un PDF nell’app web e quindi inviare una query API per quei campi (GET PDF Fields - /api/v1/templatepdf/:pdfId/fields/).

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

Usalo come modello. Modifica i valori e POSTalo allo stesso endpoint (modificando l’ID PDF come necessario). Endpoint Crea campo PDF.

3. Incorpora la nostra pagina di modifica PDF. NUOVO!

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

4. Campi Modulo PDF NUOVO!

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

Buona programmazione!

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

Siamo qui per aiutarti, contatta il supporto per qualsiasi assistenza.

suggerimento

Esamina le opzioni di invio disponibili. Prenditi un momento per leggere tutti gli attributi sull’endpoint crea documento, in particolare gli attributi 'signers', 'pdftext' e 'signertext'. Crea un documento di firma.

Prossimi passi:

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