API integratsioon

Chaindoc-i REST API võimaldab sul dokumentide voogusid automatiseerida, allkirju koguda ja sündmusi reaalajas sünkroonida. Siin lehel on põhiteadmised, peamised mõisted ja levinud integratsioonimustrid.

Mida API-ga teha saab

API annab programmeeritava juurdepääsu kõigele, mida Chaindoc teeb: laadi üles dokumente, loo allkirjapäringuid, halda meeskondi ja kuula sündmusi webhookide kaudu. Tegemist on täpselt sama API-ga, mis toidab veebirakendust.

Kolm viisi integratsiooniks

Vali see, mis sinu virnaga kõige paremini sobivad. Enamik tootmisrakendusi kasutab Server SDK-d backendis ja Embed SDK-d frontendis.

• REST API — otsested HTTP päringud, töötab iga keelega. Maksimaalne paindlikkus.
• Server SDK — tüübikindel Node.js wrapper automaatsete retry-de ja veahaldusega (`@chaindoc_io/server-sdk`)
• Embed SDK — manab allkirjastamise liidese sinu veebiäppi, et kasutajad ei peaks saiti lahkuma (`@chaindoc_io/embed-sdk`)

Kui pole veel SDK-sid installinud, siis paigaldusjuhend käsitleb npm seadistust Reacti, Vue, Angulari ja Next.js jaoks.

Kiire näide

Siin on sama "loo dokument" päring kolmes variandis. SDK versioon on kõige kompaktsem, aga REST näitab täpselt, mis juhtme üle toimub.

curl -X POST https://api.chaindoc.io/api/v1/documents \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Leping",
    "description": "Teenuse leping",
    "status": "published",
    "hashtags": ["#leping"],
    "meta": []
  }'

Autentimine

Iga päring vajab API võtit Authorization päises:

Authorization: Bearer sk_live_xxxxxxxxxxxxx

On olemas kaks võtmetüüpi ja nende segamine on kõige levinum integratsiooniviga:

• Avalikud võtmed (`pk_`) — ainult lugemiseks, ohutu frontendis kasutada
• Salajased võtmed (`sk_`) — täielik lugemine/kirjutamine, ainult backendis. Ära kunagi tee neid kliendipoolses koodis avalikuks.
• Mõlemad tulevad test (`_test_`) ja live (`_live_`) variantides. Test võtmed suunavad sandbox-i.

Päringulimiidid

API tagastab limiidi info vastuse päistes. Kui limiit täitub, saad 429 vastuse. Oota natuke ja proovi uuesti.

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 1640000000

• Üldised endpointid: 3 päringut 10 sekundi jooksul
• Meedia üleslaadimine: 3 päringut 10 sekundi jooksul
• Lugemistoimingud: 10 päringut 60 sekundi jooksul
• Allkirja loomine: 20 päringut 3 sekundi jooksul

Server SDK käsitleb retry-sid automaatselt eksponentsiaalse backoff-iga. Kui kasutad otsest HTTP-d, pead retry loogika ise implementeerima.

Vigade käsitlemine

Vead tulevad JSON-ina koos staatuskoodi, sõnumi ja (valideerimisvigade puhul) väljaspetsiifiliste probleemide nimekirjaga:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request",
  "details": [
    {
      "field": "name",
      "message": "name must be a string"
    }
  ]
}

Levinud staatuskoodid: 400 (vale päring), 401 (kehtetu võti), 403 (pakett ei sisalda API-d), 404 (ei leitud), 429 (limiit täis), 500 (serveri viga). 5xx vigade puhul proovi backoff-iga uuesti.

Levinud integratsioonimustrid

Täielik allkirjastamise voog (manatud)

Kõige levinum muster: laadi dokument üles, saada allkirjadeks ja näita allkirjastamise liidest oma äpi sees.

Kiire alustamise juhendis on selle voo täielik kood.

E-posti põhine allkirjastamine (ilma manamiseta)

Kui allkirjastajad ei kasuta sinu äppi, sea `embeddedFlow: false`. Chaindoc saadab neile e-kirja allkirjastamise lingiga. Saad ikka webhook teavitusi, kui nad allkirjastavad.

const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ email: 'signer@example.com' }],
  deadline: new Date('2024-12-31'),
  embeddedFlow: false, // Allkirjastajad saavad e-posti lingid
  message: 'Palun vaata üle ja allkirjasta see dokument',
});

Hulgi dokumenditöötlus

Partii importide puhul tsükli oma failide läbi ja laadi igaüks üles. Jälgi päringulimiite. Kui töötled sadu dokumente, lisa väike viivitus päringute vahele või kasuta SDK sisseehitatud retry loogikat.

const documents = ['doc1.pdf', 'doc2.pdf', 'doc3.pdf'];

for (const file of documents) {
  const buffer = await readFile(file);
  const blob = new Blob([buffer], { type: 'application/pdf' });
  
  const { media } = await chaindoc.media.upload([blob]);
  
  await chaindoc.documents.create({
    name: file,
    description: 'Partii töödeldud dokument',
    media: media[0],
    status: 'published',
    hashtags: ['#partii'],
    meta: [{ key: 'batch', value: 'import-2024' }],
  });
}

KYC integratsioon

Kõrge turvalisusega voogude puhul nõua enne allkirjastamist isikutuvastust. Chaindoc integreerub Sumsub-ga KYC jaoks. Sea `isKycRequired: true` allkirjapäringul ja allkirjastajad läbivad isikutuvastuse enne allkirjastamist.

const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ 
    email: 'signer@example.com',
    shareToken: 'sumsub_token_here' // Valikuline: eelverifitseeritud
  }],
  deadline: new Date('2024-12-31'),
  isKycRequired: true,
});

Juurdepääsu kontroll API kaudu

Saad dokumendi õigusi programmeeritavalt seada. Piira juurdepääsu konkreetsetele e-postidele või meeskonna rollidele:

await chaindoc.documents.updateRights(documentId, {
  accessType: 'restricted',
  accessEmails: [
    { email: 'viewer@company.com', level: 'read' },
    { email: 'editor@company.com', level: 'write' },
  ],
  accessRoles: [
    { roleId: 1, level: 'read' },
  ],
});

Parimad tavad

• Hoia API võtmeid keskkonnamuutujates. Ära kunagi commit-i neid versioonihaldusse.
• Kasuta test võtmeid (`sk_test_`) arenduseks. Live võtmed (`sk_live_`) suunavad tootesse.
• Implementeeri eksponentsiaalne backoff 429 vastuste jaoks. SDK teeb seda automaatselt.
• Kontrolli webhook allkirju HMAC-iga, et vältida kordusrünnakuid.
• Lae failid üles enne dokumentide loomist. API vajab meedia ID-d üleslaadimisest.
• Kasuta lehekülgede jagamist endpointide jaoks, mis tagastavad nimekirju. Ära tõmba kõike korraga.
• Vaata turvajuhendit enne live minekut.

Näidis kasutusjuhtud

Mõned reaalsed mustrid, mida meeskonnad API-ga ehitavad:

• E-kaubandus — genereeri automaatselt ostulepingud suure väärtusega tellimuste jaoks ja saada allkirjastamiseks kassas
• HR onboardimine — loo töölepingud mallidest ja saada uutele töötajatele nende esimesel päeval
• CRM integratsioon — käivita allkirjapäringuid Salesforce või HubSpot tehingukirjetest
• Dokumendi arhiveerimine — lisa blockchain verifitseerimine dokumentidele sinu olemasolevas salvestussüsteemis

Mis edasi saab

• API dokumentatsioon — täielik endpoint viide päringu/vastuse näidetega
• SDK-d — Server SDK ja Embed SDK raamistikuspetsiifiliste juhenditega
• Webhookid — seadista reaalajas sündmuste teavitused
• Kiire algus — käivita oma esimene integratsioon 10 minutiga
• Paigaldamine — npm seadistus kõigile toetatud raamistikele