Μαθήματα Γρήγορης Εκκίνησης

συμβουλή

Χρησιμοποιείτε Cursor, Claude ή κάποιο άλλο εργαλείο τεχνητής νοημοσύνης για κωδικοποίηση; Συνδέστε το με τα έγγραφα Legalesign για βοήθεια με γνώση συμφραζομένων ενώ ακολουθείτε αυτό το μάθημα.

Σε αυτό το μάθημα θα ολοκληρώσετε τις βασικές κλήσεις API που χρειάζονται οι περισσότεροι προγραμματιστές από μια ενσωμάτωση ψηφιακής υπογραφής - ανέβασμα εγγράφου και αποστολή για υπογραφή.

Το Legalesign API είναι κλιμακούμενο, ευέλικτο και έχει δοκιμαστεί σε συστήματα πελατών μας για πολλά χρόνια. Μπορείτε να το χρησιμοποιήσετε για ένα απλό έγγραφο με έναν υπογράφοντα, ή να στείλετε έγγραφα για μαρτυρίες ή εγκρίσεις, βελτιστοποιημένα για μαζικές αποστολές, με φόρμες και άλλα. Μπορείτε να το ενσωματώσετε για έναν συγκεκριμένο σκοπό ή να το ενσωματώσετε μέσα στο λογισμικό σας για τους πελάτες σας - δείτε ενσωματώσεις.

Το REST API εκτελεί τις περισσότερες λειτουργίες και είναι ο πιο εύκολος τρόπος για να ξεκινήσετε. Αν χρειάζεστε περισσότερα, δείτε την GraphQL διεπαφή. Το Legalesign είναι πρώτα API με GraphQL. Μπορείτε να χρησιμοποιήσετε όποιο προτιμάτε.

Θα ακολουθήσουμε τα παρακάτω βήματα:

1. Δημιουργήστε λογαριασμό + API Key (δείτε Επαλήθευση για πρόσβαση API).
2. Επιβεβαιώστε ότι τα διαπιστευτήρια λειτουργούν και πάρτε το ID της ομάδας σας.
3. Ανέβασμα εγγράφου μέσω της web εφαρμογής.
4. Αποστολή για υπογραφή μέσω API.
5. Λήψη του εγγράφου μετά την υπογραφή.
6. Ανέβασμα εγγράφου μέσω API.

Το Legalesign REST API είναι εύκολο στη χρήση. Η τεχνική αναφορά περιλαμβάνει έναν επεξεργαστή κώδικα. Μπορείτε να κάνετε αιτήσεις απευθείας από την τεχνική αναφορά με το api key σας, αλλιώς απλά αντιγράψτε και επικολλήστε κατευθείαν στον κώδικά σας.

Σχήμα 1: Ο Επεξεργαστής Κώδικα του REST API.

Βιβλιοθήκες πελάτη

• C# + Οδηγός
• Java
• Node.js
• PHP
• Python
• Ruby

Ή για τη διεπαφή GraphQL Node.js

συμβουλή

Συνιστούμε οι προγραμματιστές να δουλεύουν απευθείας με το API παρά με τα SDKs. Για βοήθεια, υπάρχει ένας γεννήτορας κώδικα για αντιγραφή-επικόλληση στην τεχνική προδιαγραφή, και η τεχνητή νοημοσύνη σας μπορεί γρήγορα να δημιουργήσει παραδείγματα χρησιμοποιώντας το OpenAPI spec. Γιατί; Το πρωτότυπο API έχει περισσότερες λειτουργίες από τα SDKs, στο τέλος θα θέλετε να γνωρίζετε για τα endpoints που χρησιμοποιείτε, θα αποφύγετε επιπλέον αφαιρετικές στρώσεις και εξαρτήσεις, και – βάσει της εμπειρίας μας – θα το κάνετε πιο γρήγορα.

1. Δημιουργία λογαριασμού

Πηγαίνετε στο legalesign sign up και ακολουθήστε τη διαδικασία για να δημιουργήσετε λογαριασμό.

Θα σας ζητηθεί να δημιουργήσετε μια ομάδα. Οι ομάδες είναι τα δομικά στοιχεία του Legalesign. Όλη η διαχείριση εγγράφων γίνεται εντός μιας ομάδας. Πρέπει να αναφέρεστε στην ομάδα σας στις περισσότερες κλήσεις API.

πληροφορίες

Μια ‘ομάδα’ ή μια ‘ομάδα’ (group) είναι το ίδιο πράγμα. Στην web εφαρμογή μιλάμε για 'ομάδες', αλλά στο σχήμα API αναφέρεται ως group.

Ρυθμίσεις API

Πηγαίνετε στο API Dashboard. Δημιουργήστε τα διαπιστευτήρια API στην ενότητα API Key.

Πάρτε μια στιγμή να εξερευνήσετε το Developer Portal.

Sandbox

Στην ενότητα Περιβάλλον (Environment), εμφανίζεται ειδοποίηση για το αν βρίσκεστε σε sandbox ή σε παραγωγική λειτουργία.

Το sandbox περιορίζει πού μπορείτε να στείλετε τα έγγραφά σας. Θα δείτε μια φόρμα για να προσθέσετε έως 5 εγκεκριμένα emails – προσθέστε μερικά τώρα.

Όταν η ενσωμάτωσή σας είναι έτοιμη: μεταβείτε σε λειτουργία παραγωγής.

συμβουλή

Δημιουργήστε μια δεύτερη ομάδα. Χρησιμοποιήστε την πρώτη ομάδα για ανάπτυξη (dev) και άλλες ομάδες για παραγωγή (prod). Ενημερώστε την υποστήριξη για το όνομα της ομάδας σας ανάπτυξης ώστε να μην χρεώνεται.

API key

Στην ενότητα API Key θα δείτε τα στοιχεία των API keys σας. Το ίδιο το κλειδί εμφανίζεται μόνο κατά τη δημιουργία του.

Η ενότητα Quickstart περιλαμβάνει παραδείγματα για αντιγραφή-επικόλληση ώστε να δοκιμάσετε το κλειδί σας.

Webhooks & Αρχεία καταγραφής

Προσθέστε webhooks (τους ακροατές σας για γεγονότα Legalesign), και ελέγξτε τα αρχεία καταγραφής σας.

2. Επιτυχής αίτηση GET

Η βασική διεύθυνση URL είναι πάντα: https://eu-api.legalesign.com/

Ξεκινήστε με μια αίτηση GET για να επιβεβαιώσετε ότι τα διαπιστευτήριά σας λειτουργούν. Αντικαταστήστε το username και τα secret values στον κώδικα παρακάτω.

Το Curl χρησιμοποιείται στα παραδείγματα, και μπορείτε να μεταβείτε μεταξύ cURL, Node.js, Python, C#, και Go χρησιμοποιώντας τις καρτέλες παρακάτω.

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