C# SDK
Συνιστούμε να κωδικοποιείτε απευθείας ενάντια στο API, η τεχνική αναφορά και η AI σας το καθιστούν απλό. Ένα C# SDK μπορεί να δημιουργηθεί χρησιμοποιώντας την προδιαγραφή OpenAPI3 του API μας και το openapi generator. Ωστόσο, εάν θέλετε SDK, σας προτείνουμε να χρησιμοποιήσετε το παραγόμενο έργο που παρέχεται, καθώς περιλαμβάνει διορθώσεις σε κάποια ζητήματα όπως τα πεδία που μπορούν να είναι null.
Το πακέτο περιέχει τη δική του τεκμηρίωση (στο docs/), αλλά τα παρακάτω παραδείγματα θα σας δείξουν πώς να ξεκινήσετε.
Get your API Key
-
Εγγραφείτε για έναν δοκιμαστικό λογαριασμό.
-
Διαμορφώστε για API όταν σας ζητηθεί, και στείλτε email στην Υποστήριξη για να λάβετε ένα API Key. Πρέπει να δείξετε ένα επίπεδο κατανόησης για τη χρήση του REST API, συμπεριλάβετε στο email σας: το όνομα και τη διεύθυνση της εταιρείας σας, το όνομά σας και τον ρόλο σας, περιγράψτε τη χρήση που θέλετε, και δώστε μια σύντομη περίληψη της προγραμματιστικής/ REST εμπειρίας σας.
-
Μόλις εκδοθεί, το API key σας θα είναι διαθέσιμο στην web εφαρμογή. Θα δείτε ότι βρίσκεστε σε sandbox mode με όριο 100 κλήσεων ανά ώρα.
Το API key σας μπαίνει στην κεφαλίδα "Authorization" και έχει τη μορφή: Bearer <your-api-key>.
Το API key σας θα υποδεικνύεται σαφώς στο Developer Portal.
Get the SDK and Example projects
Με τα εργαλεία git της επιλογής σας κάντε clone το αποθετήριο του C# SDK.
git clone https://github.com/legalesign/LegalesignCsharpSDK.git legalesignSDK
Configure the Example project
Ανοίξτε το LegalesignCsharpSDK.sln και κάντε build το έργο. Θα δείτε τρία έργα να περιλαμβάνονται στη λύση, θα εστιάσουμε στο LegalesignTest που θα σας βοηθήσει να ξεκινήσετε να κάνετε κλήσεις στο REST API.
Για εξοικονόμηση χρόνου, μπορεί να θέλετε να προσθέσετε το όνομα χρήστη, το secret, το όνομα της ομάδας, το email προορισμού, το όνομα και το επώνυμο ως τις ιδιότητες Text για txtUsername, txtSecretKey κ.λπ. στο Form1. Αν όχι, θα πρέπει να τα παρέχετε όταν τρέξετε το έργο Winform (βεβαιωθείτε ότι είναι επιλεγμένο ως startup project). Αν τα κωδικοποιήσετε σε σκληρό κώδικα, θυμηθείτε να αφαιρέσετε αυτές τις πληροφορίες μόλις τελειώσετε το έργο.
Ας δούμε το πρώτο μπλοκ κώδικα στο Form1.cs:
private Configuration makeConfig() {
Configuration c = new Configuration();
c.AddApiKey("Authorization", $"Bearer {txtSecretKey.Text}");
return c;
}
Μπορείτε να δείτε πώς χρησιμοποιεί το όνομα χρήστη και το secret που παρέχετε και το περνά στη διαμόρφωση για κάθε κλήση που θα κάνουμε αργότερα. Έτσι εξουσιοδοτούνται οι κλήσεις API.
Test a GET request
Ας βεβαιωθούμε ότι μπορείτε να κάνετε μια απλή GET αίτηση, για να ελέγξουμε αν έχει διαμορφωθεί σωστά το auth σας.
Ο παρακάτω κώδικας τρέχει όταν κάνετε κλικ στο κουμπί Get Groups. Αφιερώστε χρόνο για να παρατηρήσετε πού περνά η πληροφορία της Configuration μέσω της makeConfig(). Τρέξτε το έργο, εισάγετε το όνομα χρήστη και το κλειδί σας στα κουτιά αν δεν τα έχετε κωδικοποιήσει στην ιδιότητα Text και κάντε κλικ στο κουμπί Get Groups.
private void btnCall_Click(object sender, EventArgs e)
{
GroupApi group = new GroupApi(makeConfig());
GroupListResponse groupList = group.GetGroups();
richTextBox1.Text = groupList.ToJson();
}
Εάν είναι επιτυχές, θα λάβετε μια λίστα JSON με τις ομάδες σας.
Αν όχι, ελέγξτε ξανά αν έχετε σωστή την τιμή του Authorization.
Αυτός ο κώδικας παίρνει τυχόν έγγραφα που περιμένουν υπογραφή, μια κοινή περίπτωση χρήσης. Δοκιμάστε το εξετάζοντας και μετά τρέχοντας το κουμπί Get Documents.
private void button2_Click(object sender, EventArgs e)
{
DocumentApi docs = new DocumentApi(makeConfig());
DocumentListResponse documentList = docs.GetDocuments();
richTextBox1.Text = documentList.ToJson();
}
Οι κλήσεις 'get_statuses()' και 'get_status()' είναι γρηγορότεροι τρόποι για να λάβετε βασικές πληροφορίες εγγράφου.
Θα αρχίζετε να κατανοείτε πώς λειτουργεί το SDK. Επιστρέψτε στο αρχείο Readme του πακέτου, και θα δείτε όλα τα API αντικείμενα για να δοκιμάσετε, και όλες τις μεθόδους τους.
Test a POST request
Στη συνέχεια θα στείλουμε λίγο προσαρμοσμένο HTML για υπογραφή σε μία κλήση API, μετά θα ανεβάσουμε ένα PDF και θα το στείλουμε.
Send an HTML document to get signed
Εδώ είναι μια μικρή ποσότητα HTML για επίδειξη, που περιέχει ένα στοιχείο υπογραφής. Αντικαταστήστε τις τιμές της ομάδας, του ονόματος και του 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;
}
}
Πώς ξέρουμε ότι περάστηκε; Το OpenAPI ρίχνει εξαίρεση για απαντήσεις μη 2XX. Θα θέλετε να βάλετε όλες τις αιτήσεις σας σε ένα μπλοκ try/catch.
Κάθε φορά που κάνετε POST, πιθανότατα θα θέλετε το νέο ID αντικειμένου. Βρίσκεται στην κεφαλίδα Location της απάντησης. Στο επόμενο παράδειγμα μας βλέπουμε πώς να ανεβάσουμε ένα PDF για να το στείλουμε στους υπογράφοντες, και να πάρουμε το ID για το νέο πρότυπο.
Upload and send a PDF
Πιθανότατα θα χρησιμοποιήσετε text-tags εντός των PDFs σας, για να καθορίσετε πού θα υπογράφουν ή θα συμπληρώνουν φόρμες οι άνθρωποι. Η χρήση της παραμέτρου processTags=true ενημερώνει το σύστημα να ψάξει μέσα στο έγγραφό σας και να δημιουργήσει πεδία για πληροφορίες και υπογραφές που πρέπει να υπογράψει ο παραλήπτης. Ένα βασικό παράδειγμα PDF με tags περιλαμβάνεται στη ρίζα του έργου SDK.
Ας ανεβάσουμε ένα PDF χρησιμοποιώντας την έκδοση 'with_http_info' της POST αίτησης για να πάρουμε το 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;
}
}
}
Επειδή βάλαμε το process_tags σε true, όλα τα tags έχουν υποβληθεί σε επεξεργασία, οπότε το PDF σας είναι έτοιμο για αποστολή. Όπως πριν, χρειαζόμαστε το
ID για το PDF ώστε να το στείλουμε. Ευτυχώς το κρατήσαμε στο κουτί κειμένου txtPdfLocation.
Το τελευταίο απόσπασμα κώδικα από το Send with Template δείχνει πώς χρησιμοποιούμε αυτή την τοποθεσία PDF για να στείλουμε ένα ήδη φορτωμένο έγγραφο για υπογραφή.
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
Φροντίστε να ελέγξετε την τεκμηρίωση που παράγεται από το OpenAPI για διάφορους τύπους κλήσεων και επιλογές.
Μερικά συνηθισμένα προβλήματα είναι:
Το όνομα της ομάδας πρέπει να ταιριάζει ακριβώς με μία που έχετε ήδη στην οργάνωσή σας.
Το αίτημά σας θα απορριφθεί αν τα διαπιστευτήριά σας είναι λανθασμένα, παλιά ή κλειδωμένα.
Καλή κωδικοποίηση!