Neidio i’r prif gynnwys

Tiwtorial Cychwyn Cyflym

cyngor

Ydych chi'n defnyddio Cursor, Claude, neu offeryn codio AI arall? Cysylltwch ef â dogfennau Legalesign i gael cymorth cyd-destunol wrth ddilyn y tiwtorial hwn.

Yn y tiwtorial hwn fe gwblhewch y galwadau API allweddol y mae’r rhan fwyaf o ddatblygwyr eu hangen o integreiddiad eLlofnodi - uwchlwytho dogfen a'i hanfon allan i'w llofnodi.

Mae API Legalesign yn rymus, amlbwrpas, a phrofiad cynhyrchu ym systemau ein cwsmeriaid ers blynyddoedd lawer. Gallwch ei ddefnyddio ar gyfer dogfen gydag un llofnodiwr yn unig, neu anfon dogfennau ar gyfer ardystio neu gymeradwyaethau, wedi’i optimeiddio ar gyfer swmpiau, gyda ffurflenni a mwy. Gallwch ei integreiddio at un pwrpas neu fewnosod efo’ch meddalwedd ar gyfer eich cwsmeriaid - gweler integreiddiadau.

Mae'r API REST yn cyflawni’r mwyafrif o swyddogaethau ac yn y ffordd hawsaf i ddechrau. Os oes angen mwy arnoch edrychwch ar y rhyngwyneb GraphQL. Mae Legalesign yn API gyntaf gyda GraphQL. Gallwch ddefnyddio un neu'r llall, yn ôl eich dewis.

Byddwn yn dilyn y camau hyn:

  1. Creu cyfrif + Allwedd API (gweler Sicrhau gael mynediad API).
  2. Cadarnhau bod eich credydau’n gweithio a chael eich ID tîm.
  3. Uwchlwytho dogfen drwy’r ap gwe.
  4. Anfon y dogfen i’w llofnodi drwy’r API.
  5. Lawrlwytho’r dogfen wedi’i llofnodi.
  6. Uwchlwytho dogfen drwy’r API.

Mae API REST Legalesign yn hawdd i'w ddefnyddio. Mae’r cyfeirlyfr technegol yn cynnwys golygydd cod. Gallwch wneud ceisiadau yn union o'r cyfeirlyfr technegol gyda’ch allwedd API, ond fel arall dim ond copïo a gludo’n uniongyrchol i’ch cod.

Delwedd Generator Cod Ffigur 1: Golygydd Cod API REST.

Llyfrgelloedd cwsmer​

Neu ar gyfer y rhyngwyneb GraphQL Node.js

cyngor

Rydym yn argymell bod datblygwyr yn gweithio'n uniongyrchol gyda'r API yn hytrach na’r SDKs. I helpu, mae gennym beiriant cod 'torri a gludo' yn y manylion technegol, a gall eich AI gynhyrchu enghreifftiau’n gyflym gan ddefnyddio'r [maniffest OpenAPI] (https://raw.githubusercontent.com/legalesign/Legalesign-V1-OpenAPI3/refs/heads/master/legalesign-api-v1.yaml). Pam? Mae mwy o nodweddion yn y ffynhonnell API na’r SDKs, byddwch am wybod am y penlinellau rydych yn eu defnyddio beth bynnag, byddwch yn osgoi gorffeniad a dibyniaethau, ac -- yn ôl ein profiad -- byddwch yn gwneud y gwaith yn gynt hefyd.

1. Creu cyfrif​

Ewch i [cofrestriad legalesign] (https://legalesign.com/landing/free-trial/) a dilynwch y broses i greu cyfrif.

Fe ofynnir i chi greu tîm. Mae timau yn seiliau Legalesign. Mae pob prosesu dogfen yn digwydd mewn tîm. Mae angen i chi gyfeirio at eich tîm mewn y rhan fwyaf o alwadau API.

gwybodaeth

Mae 'tîm' neu 'grŵp' yn yr un peth. Yn yr ap gwe rydym yn siarad am 'dimau', ond yn y schema API mae'n grŵp.

Gosodiadau API​

Ewch i’r Dangosfwrdd API. Cynhyrchwch eich credydau API yn adran Allwedd API.

Cymerwch funud i adolygu'r Porth Datblygwr.

Sandbox​

Yn yr adran Amgylchedd, mae rhybudd yn dangos a ydych mewn modd sandbox neu gynhyrchu.

Mae modd sandbox yn gosod cyfyngiad o 100 o alwadau yr awr. Nid oes cyfyngiadau ar gyfeiriadau e-bost derbynwyr.

Pan fydd eich integreiddiad yn barod: symud i fodd cynhyrchu.

cyngor

Creu ail dîm. Defnyddiwch eich tîm cyntaf ar gyfer datblygiad a’r tîm(au) arall(au) ar gyfer cynhyrchu. Dywedwch i gefnogaeth enw eich tîm datblygu i’w eithrio o daliadau.

Allwedd API​

Yn adran Allwedd API byddwch yn gweld manylion eich allweddi API. Yn unig y dangosir y allwedd wrth i chi greu un.

Mae Porth Datblygwr yn cynnwys enghreifftiau torri a gludo i brofi eich allwedd.

Screenshot Adran Allwedd API

Webhooks a Logiau​

Ychwanegu webhooks (eich gwrandawyr ar ddigwyddiadau Legalesign), ac adolygwch eich logiau.

Screenshot Adran Webhooks

2. Cais GET llwyddiannus​

Y URL gwraidd yw bob amser: https://eu-api.legalesign.com/

Dechreuwch gydag cais GET i gadarnhau bod eich credydau’n gweithio. Disodli your_api_key efo’ch allwedd o’r Porth Datblygwr.

Defnyddir Curl yn yr enghreifftiau, a gallwch newid rhwng cURL, Node.js, Python, C#, a Go gan ddefnyddio'r tabiau isod.

curl -H "Authorization: Bearer your_api_key" -H "Content-Type: application/json" -X GET https://eu-api.legalesign.com/api/v1/group/

Dogfennaeth API: Cyfeirlyfr API GET grŵp.

Pan fyddwch yn gweithredu’r ymholiad uchod, fe welwch eich grwpiau’n cael eu dychwelyd mewn JSON. Llwyddiant. 👏

Mae data’r ymateb yn cynnwys 'resource uri' ar gyfer eich grŵp ac mae'n edrych fel /api/v1/group/:groupId/. Nodwch hwn, bydd ei angen arnoch ar gyfer y rhan fwyaf o alwadau API.

cyngor

Bydd 'resource uri' bob amser yn cael ei ffurfweddu’r un fath. Ar gyfer PDF byddai’n '/api/v1/templatepdf/:pdfId/', ar gyfer dogfen anfon bydd yn '/api/v1/document/:documentId/'. Sylwch fod pob URI yn gorffen gyda slais. Mae hynny’n wir hefyd am URLau eich alwadau API, gorffenwch nhw bob amser gyda slais.

Os bydd y cais GET yn methu gwiriwch fod:

  • eich penawd Authorization wedi cael ei fformatio'n gywir (yn dechrau gyda Bearer ),
  • bod gennych benawd Content-Type ar gyfer application/json, a
  • bod eich url yn gorffen gyda slais.

Gweler hefyd datrys problemau.

3. Uwchlwytho dogfen trwy’r ap gwe​

I ddechrau, byddwn yn uwchlwytho dogfen trwy’r ap gwe a’i hanfon yna trwy'r API. Byddwn yn cwmpasu sut i uwchlwytho dogfen trwy'r API yn ddiweddarach.

Ewch i’r ap gwe a uwchlwythwch eich dogfen. Ychwanegwch rôl llofnodiwr sengl a llusgwch faes llofnod arno. Bydd y dudalen golygydd yn nodi a yw'r ddogfen yn 'ddilys' (enghraifft o 'annu' fyddai pan ychwanegwch rôl llofnodiwr heb faes llofnod cysylltiedig).

Ar y golygydd ffurflen, copïwch y cyfrifiad ID alffa-numerig hir o'r URL, dadgodwch base64 a gwnewch anghofio'r 3 llythyren gyntaf (a ddylai fod yn 'tpl'). Y gweddill yw UUID sy'n eich ID. Dysgwch fwy am IDs gwe ac API.

Y ID API REST ar gyfer y ddogfen hon yw /api/v1/templatepdf/UUID/.

Ein terminoleg ni yw bod dogfen a uwchlwythwyd yn 'deilen' a phan anfonwch un rydych yn creu 'dogfen'.

cyngor

Os ydych eisiau archifo deilen wrth i’r ddogfen gael ei hanfon, gosodwch 'archive_upon_send' fel priodoledd yn y cais uwchlwytho. Os nad ydych am i’r deilen byth ymddangos ac eisiau ei dileu ar ôl anfon, rhowch y teitl '[deleted]' - bydd ein systemau glanhau yn ei ganfod ac yn ei ddileu ar ôl diwrnod neu ddau. Mae hefyd modd gosod amseroedd cadw data byr ar lefel grŵp - dysgwch fwy.

4. Anfon dogfen i’w llofnodi​

Nawr byddwn yn anfon hwn drwy’r API. Defnyddiwch y tabiau isod i ddewis y cais yn eich iaith a ddewisoch.

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/

Diweddarwch yr holl fymplenni cornel sgwâr. Cyfeirlyfr API i anfon dogfen.

cyngor

Pan fyddwch yn ymweld â dogfenwaith cyfeirlyfr anfon dogfen edrychwch yn dda drwy’r holl briodweddau posib. Fe welwch lawer a fydd o gymorth wrth ymarferoldeb integreiddiad - tagiau i’ch cyfeiriadau a’ch IDs eich hun (sy’n dychwelyd atoch mewn webhooks), ailgyfeirio ar gyfer llofnodiwyr, gosod testun personol yn y PDF, a mwy.

Bydd alwad llwyddiannus yn dychwelyd cod statws 201. ✨

Cael ID dogfen anfon newydd​

Y rhan bwysicaf o'r ymateb yw’r penawd location. Mae hwn yn cynnwys ID newydd eich dogfen.

cyngor

Defnyddiwch briodweddau 'tag' dogfen a ychwanegwch eich cyfeiriadau eich hun i wneud cysylltu gyda’ch cronfa ddata yn haws.

Bydd y penawd location yn edrych fel /api/v1/status/:documentId/.

Mae URI 'status' yn dychwelyd set fer (a chyflym i'w holi) o briodweddau dogfen.

I ofyn am bopeth o ddogfen defnyddiwch /api/v1/document/:documentId/.

gwybodaeth

Os na fydd cais yn llwyddiannus, bydd corff (BODY) yr ymateb fel arfer yn cynnwys gwybodaeth am y gwall. Os na gewch statws llwyddiant, gwiriwch y corff am destun esboniadol. Gweler hefyd datrys problemau.

Dysgwch fwy am alwad API Anfon Dogfen.

5. Lawrlwytho’r dogfen wedi’i llofnodi​

Gyda ID y ddogfen anfon a gawsoch uchod, gwnewch gais lawrlwytho PDF yn yr iaith a ddewiswch:

curl -H "Authorization: Bearer your_api_key" -o download.pdf -X GET https://eu-api.legalesign.com/api/v1/pdf/:documentId/

Cyfeirlyfr API lawrlwytho PDF.

Mae'r ffeil PDF fodernol yn y corff (BODY) o'r ymateb. Mae'r gorchymyn curl '-o' yn rhoi corff yr ymateb yn uniongyrchol i ffeil.

Mae llawer o lyfrgelloedd REST neu HTTP yn trin gwrthrychau ymateb HTTP fel pe baent yn ffeiliau ac felly gallwch arbed eich gwrthrych ymateb fel ffeil arferol.

cyngor

Defnyddiwch webhooks i gael hysbysiad o ddigwyddiad llofnodi ac yna lawrlwythwch y ddogfen. Gweler webhooks.

6. Uwchlwytho dogfen drwy'r API​

[Cliciwch yma i lawrlwytho PDF sampl wedi'i nodi â thagiau testun] (https://static.legalesign.com/tutorialQuickstartPdf.pdf), bydd mwy am feysydd ffurflen PDF yn dilyn.

Ar gyfer y galwad hon, troswch eich PDF yn llinyn codiedig base64. Nid yw hyn yn cael ei wneud yn iawn o fewn y peiriant cod dogfennaeth. Copïwch y psewdocôd hwn a bydd AI yn ei drosi i’ch iaith a ddewiswyd:

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

Cyfeirlyfr API uwchlwytho PDF.

Bydd ymateb POST llwyddiannus yn dychwelyd statws 201 a bydd y ID newydd yn y penawd ymateb location.

Bydd URI adnodd PDF yn edrych fel /api/v1/templatepdf/:pdfId/.

Fformatau ffeil eraill​

Mae Word, HTML, testun plaen, XLSX, a ffeiliau delwedd i gyd yn cael eu cefnogi. Uwchlwythwch nhw gan ddefnyddio yr uwchlwythwr ffeil GraphQL, sy’n canfod y fformat yn awtomatig ac yn ei drawsnewid yn PDF. Cael yr ID a’i anfon trwy'r API REST fel arfer. Gweler hefyd deall REST a GraphQL IDs. Bydd tagiau testun yn cael eu deall fel arfer.

Anfon y PDF newydd​

Dywedwch yn ôl i’r cod a ddefnyddiwyd i anfon eich dogfen gyntaf, a disodli gwerth templatepdf.

Rhedwch y cais eto a dyna chi, rydych wedi anfon eich PDF allan i’w lofnodi.

Cyn i chi ddechrau codio, fodd bynnag, darllenwch ymlaen i ddysgu mwy am feysydd PDF.

Beth am feysydd PDF?​

Sut mae Legalesign yn gwybod lle mae angen i’r person lofnodi ar y PDF, neu adrannau i’w newid wrth anfon? Ymateb yw ein bod wedi paratoi ein PDF ymlaen llaw gyda thagiau: rydym yn rhoi tag testun Legalesign yn y PDF a sefydlu 'process_tags' i wir yn y cais uwchlwytho PDF.

[Llwythwch i lawr PDF sampl wedi’i nodi â thag testun] (https://static.legalesign.com/tutorialQuickstartPdf.pdf).

Mae tagiau testun yn destun wedi’i fformatio’n arbennig i’w roi mewn PDF. Bydd Legalesign yn dadansoddi’r testun yn eich ffeil, gan ddisodli’r tagiau gyda meysydd llofnod a ffurflen. Ar gyfer un llofnodiwr mae’r unig beth sydd ei angen yw ychwanegu: <<t=signature>>. Bydd Legalesign yn ei adnabod a lleoli’r llofnod yno. Dysgwch am dagiau testun.

Mae dulliau eraill i leoli eich meysydd wedi’u rhestru isod, ond gyda thagiau testun cewch y gallu llawn o system ffurflenni Legalesign. Defnyddiwch yr ap gwe i brofi’ch tagiau. Cysylltwch â [chefnogaeth] (https://support.legalesign.com) am gymorth ac enghreifftiau.

Dyma 4 ffordd arall i sefydlu meysydd:

1. Fersiwn hawddaf/cyflymaf. Sefydlu eich PDF gan ddefnyddio ap gwe Legalesign.​

Ar ôl i chi uwchlwytho PDF fe gewch y rhyngwyneb golygydd lle gallwch lusgo a gollwng meysydd ffurflen.

Llusgwch a gollwng llofnod, yna nodwch yr ID codiedig yn y cyfeiriad gwe. Bydd hyn yn edrych fel 'dHBsMTRlZTQ0ZWUtZGE0Ni0xMWVmLTllZmUtMDI5ZGQ0ODkzZGRk'.

Dadgodwch base64 yr ID hwn a byddwch yn gweld ei fod yn UUID a ragflaenwyd gan 'tpl'. Y rhan UUID (tynnwch 'tpl') yw'ch pdfID. Dysgwch fwy am IDs Legalesign.

Bydd URI adnodd API PDF yn - /api/v1/templatepdf/:pdfId/.

Rhowch hynny i briodwedd 'templatepdf' y galwad anfon dogfen.

gwybodaeth

Os bwriwch anfon y PDF hwn fwy nag unwaith, sicrhewch fod 'Auto archive' wedi’i ddiffodd. Gweler sut

2. Defnyddiwch gydlyniant x/y ar gyfer meysydd.​

Y ffordd symlaf i ddechrau gyda chyfsylltiadau x/y yw sefydlu PDF yn yr ap gwe ac yna holi API am y meysydd hynny (GET PDF Fields - /api/v1/templatepdf/:pdfId/fields/).

Mae’r gwrthrych JSON a gewch yn ôl yn union yr un schema JSON sydd ei angen i greu meysydd hefyd.

Defnyddiwch ef fel deilen. Addaswch unrhyw werthoedd a POSTiwch yn ôl at yr un penlinell (gan addasu’r ID PDF yn briodol). Penlinell Creu Meysydd PDF.

3. Mewnosodwch ein tudalen golygydd PDF. NEWYDD!​

Defnyddiwch ein cydran golygydd i fewnosod ein golygydd PDF yn uniongyrchol yn eich ap eich hun. Dysgwch fwy am y cydran golygydd Dogfen.

4. Meysydd Ffurflen PDF NEWYDD!​

Os yw eich PDF yn cynnwys Meysydd Ffurflen PDF arferol, gall Legalesign eu mewnforio yn awtomatig.

Codio hapus!​

Yn y tiwtorial hwn cawsant gredydau API, holiad llwyddiannus am eich grŵp(iau), anfon dogfen allan ar gyfer llofnodi gan ddefnyddio PDF, a lawrlwytho dogfen wedi’i llofnodi.

Rydym yma i helpu, cysylltwch â [chefnogaeth] (https://support.legalesign.com) am unrhyw gymorth.

cyngor

Adolygwch y dewisiadau anfon sydd ar gael i chi. Cymerwch funud i ddarllen trwy’r holl briodweddau ar y penlinell creu dogfen, yn arbennig briodweddau ’llofnodiwr’, ‘pdftext’ a ‘signertext’. Creu dogfen llofnodi.

Camau nesaf:​