SDK C#
Raccomandiamo di programmare direttamente contro l’API, il riferimento tecnico e la tua AI lo rendono semplice. Un SDK C# può essere generato utilizzando la specifica OpenAPI3 della nostra API e openapi generator. Tuttavia, se desideri un SDK, ti consigliamo di utilizzare il progetto generato fornito, poiché include correzioni per alcuni problemi come i campi nullable.
Il pacchetto contiene la propria documentazione (in docs/), ma gli esempi di seguito ti mostreranno come iniziare.
Get your API Key
-
Iscriviti per un account di prova.
-
Configura per API quando richiesto, e invia un’email al Supporto per ottenere una API Key. Devi dimostrare una certa conoscenza sull’uso della REST API, includi nella tua email: il nome e l’indirizzo della tua azienda, il tuo nome e ruolo, descrivi il tuo caso d’uso, e fornisci un breve riassunto della tua esperienza di programmazione/REST.
-
Una volta rilasciata, la tua API key sarà disponibile nell’app web. Vedrai che sei in modalità sandbox con un limite di 100 chiamate all’ora.
La tua API key va nell’intestazione "Authorization", e ha la forma: Bearer <your-api-key>.
La tua API key sarà chiaramente indicata nel Developer Portal.
Get the SDK and Example projects
Con i tuoi strumenti git preferiti clona il repository dello SDK C#.
git clone https://github.com/legalesign/LegalesignCsharpSDK.git legalesignSDK
Configure the Example project:
Apri LegalesignCsharpSDK.sln e compila il progetto. Dovresti vedere tre progetti inclusi nella soluzione, ci concentreremo su LegalesignTest che ti permetterà di iniziare a fare chiamate all’API REST.
Per risparmiare tempo potresti voler aggiungere username, secret, nome del gruppo, email di destinazione, nome e cognome come proprietà Text per txtUsername, txtSecretKey ecc. in Form1. Altrimenti dovrai fornire queste informazioni quando esegui il progetto Winform (assicurati che sia segnato come progetto di avvio). Se le inserisci direttamente nel codice, ricordati di rimuoverle una volta terminato il progetto.
Guardiamo il primo blocco di codice in Form1.cs:
private Configuration makeConfig() {
Configuration c = new Configuration();
c.AddApiKey("Authorization", $"Bearer {txtSecretKey.Text}");
return c;
}
Puoi vedere come questo usa lo username e il secret che fornisci e li passa nella configurazione per ogni chiamata che faremo dopo. Questo è il modo in cui le chiamate API vengono autorizzate.
Test a GET request:
Assicuriamoci che tu possa fare una semplice richiesta GET, per verificare che la tua autenticazione sia configurata correttamente.
Il codice seguente viene eseguito quando clicchi il pulsante Get Groups. Prenditi un momento per notare dove le informazioni di Configurazione sono passate tramite makeConfig(). Esegui il progetto, inserisci username e chiave nelle caselle se non le hai scritte direttamente nella proprietà Text e clicca sul pulsante Get Groups.
private void btnCall_Click(object sender, EventArgs e)
{
GroupApi group = new GroupApi(makeConfig());
GroupListResponse groupList = group.GetGroups();
richTextBox1.Text = groupList.ToJson();
}
Se ha successo, otterrai una lista JSON dei tuoi gruppi.
Altrimenti verifica di avere correttamente il valore di Authorization.
Questo codice ottiene i documenti in attesa di firma, un caso d’uso comune. Testalo esaminando e poi eseguendo il pulsante Get Documents.
private void button2_Click(object sender, EventArgs e)
{
DocumentApi docs = new DocumentApi(makeConfig());
DocumentListResponse documentList = docs.GetDocuments();
richTextBox1.Text = documentList.ToJson();
}
Le chiamate 'get_statuses()' e 'get_status()' sono modi più veloci per interrogare le informazioni di base di un documento.
Dovresti iniziare a capire come funziona lo SDK. Torna al file Readme del pacchetto, e vedrai tutti gli oggetti API da provare, e tutti i loro metodi.
Test a POST request
Ora invieremo un po’ di HTML personalizzato da far firmare in una chiamata API, poi caricheremo un PDF e lo invieremo.
Send an HTML document to get signed:
Ecco un piccolo pezzo di HTML a scopo dimostrativo, contenente un elemento firma. Sostituisci i valori di gruppo, nome ed email.
private void btnPost_Click(object sender, EventArgs e)
{
DocumentApi docs = new DocumentApi(makeConfig());
List<DocumentSignerPost> signers = new List<DocumentSignerPost>();
signers.Add(new DocumentSignerPost(email: txtEmail.Text, firstname: txtFirstname.Text, lastname: txtLastname.Text));
//You must provide group id as lowercase
DocumentPost dp = new DocumentPost(
group: $"/api/v1/group/{txtGroupName.Text.ToLower()}/",
name: "dotnetdocument",
text: rtbBodyHTML.Text,
signers: signers,
doEmail: true,
footerHeight:30,
footer: "Legalesign ID: {{doc_id}}");
try
{
InlineResponse201 resp = docs.PostDocument(dp);
richTextBox1.Text = resp.ToJson();
}
catch (Exception ex) {
throw ex;
}
}
Come sappiamo se è andato a buon fine? OpenAPI genera un’eccezione per risposte non 2XX. Vorrai inserire tutte le tue richieste in un blocco try/catch.
Ogni volta che fai un POST, probabilmente vorrai l’ID del nuovo oggetto. È nell’intestazione Location della risposta. Nel prossimo esempio vediamo come caricare un PDF da inviare ai firmatari, e ottenere l’ID di quel nuovo template.
Upload and send a PDF
Molto probabilmente utilizzerai i text-tags all’interno dei tuoi PDF, per definire dove le persone firmeranno o compileranno moduli. Usare il parametro processTags=true fa sapere al sistema di controllare il documento e creare campi per le informazioni e firme che il destinatario dovrà apporre. Un esempio base di PDF con tag è incluso nella root del progetto SDK.
Carichiamo un PDF usando la versione 'with_http_info' della richiesta POST per ottenere l’ID
private void btnUploadPdf_Click(object sender, EventArgs e)
{
DialogResult result = openFileDialog1.ShowDialog();
if (result == System.Windows.Forms.DialogResult.OK)
{
TemplatepdfApi pdf = new TemplatepdfApi(makeConfig());
// Get the file and convert the contents to a base64 byte array.
Byte[] bytes = File.ReadAllBytes(openFileDialog1.FileName);
String contents = Convert.ToBase64String(bytes);
Byte[] encodedBytes = Convert.FromBase64String(contents);
try
{
// Upload the pdf for our group to use with a title and a tag
ApiResponse <object> response = pdf.PostPdfTemplateWithHttpInfo(new TemplatePdfFieldPost(group: $"/api/v1/group/{txtGroupName.Text.ToLower()}/",
pdfFile: encodedBytes, processTags: true, title: "test tagged document"));
// Just to demonstrate how to read response headers we'll put the returned
// header in the output rich text box. The 'Location' header contains the new
// Template ID.
richTextBox1.Text = JsonConvert.SerializeObject(response.Headers);
// We'll save this so we can use it when calling Send with Template
txtPDFLocation.Text = response.Headers["Location"];
}
catch (Exception ex)
{
throw ex;
}
}
}
Poiché abbiamo impostato process_tags a true, tutti i tag sono stati elaborati quindi il tuo PDF è pronto. Come prima, abbiamo bisogno dell’ID del PDF per poterlo inviare. Fortunatamente l’abbiamo mantenuto nella casella di testo txtPdfLocation.
L’ultimo snippet da Send with Template mostra come usiamo quella posizione PDF per inviare un documento pre-caricato da firmare.
private void btnSendTemplate_Click(object sender, EventArgs e)
{
DocumentApi docs = new DocumentApi(makeConfig());
List<DocumentSignerPost> signers = new List<DocumentSignerPost>();
signers.Add(new DocumentSignerPost(email: txtEmail.Text, firstname: txtFirstname.Text, lastname: txtLastname.Text));
//You must provide group id as lowercase
DocumentPost dp = new DocumentPost(
group: $"/api/v1/group/{txtGroupName.Text.ToLower()}/",
name: "dotnetdocument",
template: txtPDFLocation.Text,
signers: signers,
doEmail: true,
footerHeight: 30,
footer: "Legalesign ID: {{doc_id}}");
try
{
InlineResponse201 resp = docs.PostDocument(dp);
richTextBox1.Text = resp.ToJson();
}
catch (Exception ex)
{
throw ex;
}
}
Get coding
Assicurati di controllare la documentazione generata da OpenAPI per i diversi tipi di chiamata e opzioni.
Alcuni errori comuni sono:
Il nome del gruppo deve corrispondere esattamente a uno già presente nella tua organizzazione.
La tua richiesta verrà rifiutata se le credenziali sono errate, scadute o bloccate.
Happy coding!