Tutorial di Avvio Rapido

Accesso all'API richiede approvazione

Per usare l'API Legalesign devi contattarci per ottenere l'approvazione all'uso dell'API per il tuo account.

suggerimento

Usi Cursor, Claude o un altro strumento AI per il coding? Connettilo ai documenti 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 di firma elettronica – caricare un documento e inviarlo per la firma.

L'API Legalesign è scalabile, versatile e testata in ambienti produttivi nei sistemi dei nostri clienti da molti anni. Puoi usarla per un documento con un solo firmatario, oppure inviare documenti per testimoni o approvazioni, ottimizzata per lotti, con moduli e altro. Puoi integrare per uno scopo 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 più, dai un'occhiata all'interfaccia GraphQL. Legalesign è API-first con GraphQL. Puoi usare entrambi, a tua preferenza.

Seguiremo questi passi:

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 quel documento 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 fare richieste direttamente dal riferimento tecnico con la tua chiave API, altrimenti copia e incolla direttamente nel tuo codice.

Figura 1: L'editor di codice dell'API REST.

Librerie client

• C# + Guida
• Java
• Node.js
• PHP
• Python
• Ruby

Oppure per l'interfaccia GraphQL Node.js

suggerimento

Raccomandiamo 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ò rapidamente produrre esempi usando la spec OpenAPI. Perché? L'API sorgente ha più funzionalità degli SDK, vorrai comunque conoscere gli endpoint usati, eviti overhead di astrazione e dipendenze, e – basandoci sulla nostra esperienza – ti fa risparmiare tempo.

1. Crea un account

Vai su legalesign registrazione. Usa una email normale per creare l'account (non usare Google), identità federate come Google non funzioneranno per l'API.

Ti sarà chiesto di creare un team. I team sono i mattoni di Legalesign. Tutto il processo documentale avviene in 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.

Contatta il supporto per una Chiave API. Dicci il tuo caso d'uso, la tua esperienza con sviluppo API e qualche dettaglio per confermare che sei reale (es. dettagli di dove lavori).

Impostazioni API

Una volta verificato vai alla Dashboard API. Genera le tue credenziali API nella sezione Chiave API.

Prenditi un momento per esplorare 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 modulo per aggiungere fino a 5 email approvate – aggiungine alcune ora.

Quando la tua integrazione è pronta: passa alla modalità produzione.

suggerimento

Crea un secondo team. Usa il primo team per sviluppo e gli altri team per produzione. Comunica al supporto il nome del tuo team di sviluppo per escluderlo dalla fatturazione.

Chiave API

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

La sezione Quickstart contiene esempi da copiare e incollare per testare la tua chiave.

Webhook & Log

Aggiungi webhook (i tuoi listener per eventi Legalesign) e rivedi 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 username e valori secret nel codice qui sotto.

Curl è usato negli esempi, puoi passare tra cURL, Node.js, Python, C#, e Go usando le tab qui sotto.

cURL

curl -H "Authorization: ApiKey username:secret" -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': '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);
});

Python

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())

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", "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);
    }
}

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", "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))
}

cURL

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/

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': '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);
});

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": "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"))

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", "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}");
        }
    }
}

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", "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"))
}

cURL

curl -H "Authorization: ApiKey [username]:[secret]" -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': '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);
});

Python

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)

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", "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");
    }
}

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", "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")
}

$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']

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