API integration

Chaindoc का REST API आपको document workflows को automate करने, signatures collect करने और events को real time में sync करने की सुविधा देता है। यहाँ आपको शुरुआत करने का तरीका, मुख्य concepts और common integration patterns मिलेंगे।

API से क्या कर सकते हैं

यह API आपको Chaindoc की सभी functionalities का programmatic access देता है: documents upload करें, signature requests बनाएं, teams manage करें, और webhooks के through events सुनें। यही API web app को भी power करती है।

Integration के तीन तरीके

अपनी stack के हिसाब से कोई एक चुनें। ज्यादातर production apps backend पर Server SDK और frontend पर Embed SDK use करती हैं।

• REST API — सीधे HTTP requests, किसी भी language में काम करता है। Maximum flexibility।
• Server SDK — type-safe Node.js wrapper जिसमें automatic retries और error handling है (`@chaindoc_io/server-sdk`)
• Embed SDK — आपकी web app में signing interface embed करता है ताकि users आपकी site न छोड़ें (`@chaindoc_io/embed-sdk`)

अगर आपने SDKs install नहीं किए हैं, तो installation guide में React, Vue, Angular और Next.js के लिए npm setup का विवरण है।

Quick example

यहाँ वही "document create" call तीन अलग-अलग तरीकों से। SDK version सबसे concise है, लेकिन raw REST call दिखाता है कि wire पर exactly क्या हो रहा है।

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

Authentication

हर request के लिए Authorization header में API key जरूरी है:

Authorization: Bearer sk_live_xxxxxxxxxxxxx

दो तरह की keys हैं, और इन्हें mix up करना सबसे common integration mistake है:

• Public keys (`pk_`) — read-only, frontend code के लिए safe
• Secret keys (`sk_`) — full read/write, सिर्फ backend। इन्हें कभी client-side code में expose न करें।
• दोनों test (`_test_`) और live (`_live_`) variants में आती हैं। Test keys sandbox में hit करती हैं।

Rate limits

API response headers में rate limit info देती है। Limit hit करने पर 429 response मिलेगा। Back off करें और retry करें।

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

• General endpoints: 10 seconds में 3 requests
• Media upload: 10 seconds में 3 requests
• Read operations: 60 seconds में 10 requests
• Signature creation: 3 seconds में 20 requests

Server SDK exponential backoff के साथ automatic retries handle करता है। अगर आप raw HTTP use कर रहे हैं, तो खुद retry logic implement करें।

Error handling

Errors JSON format में आती हैं, जिसमें status code, message और (validation errors के लिए) specific field issues की list होती है:

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

Common status codes: 400 (bad request), 401 (invalid key), 403 (plan में API नहीं है), 404 (not found), 429 (rate limited), 500 (server error)। 5xx errors के लिए backoff के साथ retry करें।

Common integration patterns

Full signing flow (embedded)

सबसे common pattern: document upload करें, signatures के लिए भेजें, और signing UI अपनी app में दिखाएं।

Quick start guide में इस flow का पूरा code है।

Email-based signing (no embed)

अगर signers आपकी app use नहीं करते, तो `embeddedFlow: false` set करें। Chaindoc उन्हें signing link वाला email भेजेगा। Sign करने पर आपको webhook notifications मिलती रहेंगी।

const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ email: 'signer@example.com' }],
  deadline: new Date('2024-12-31'),
  embeddedFlow: false, // Signers को email links मिलेंगे
  message: 'Please review and sign this document',
});

Bulk document processing

Batch imports के लिए, अपनी files पर loop करें और एक-एक करके upload करें। Rate limits का ध्यान रखें। अगर सैकड़ों documents process कर रहे हैं, तो requests के बीच छोटी delay add करें या SDK की built-in retry logic use करें।

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: 'Batch processed document',
    media: media[0],
    status: 'published',
    hashtags: ['#batch'],
    meta: [{ key: 'batch', value: 'import-2024' }],
  });
}

KYC integration

High-security workflows के लिए, sign करने से पहले identity verification जरूरी करें। Chaindoc Sumsub के साथ KYC integrate करता है। Signature request पर `isKycRequired: true` set करें, और signers sign करने से पहले identity verification से गुजरेंगे।

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

Access control via API

आप programmatically document permissions set कर सकते हैं। Specific emails या team roles तक access restrict करें:

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' },
  ],
});

Best practices

• API keys को environment variables में रखें। कभी version control में commit न करें।
• Development के लिए test keys (`sk_test_`) use करें। Live keys (`sk_live_`) production में hit करती हैं।
• 429 responses के लिए exponential backoff implement करें। SDK यह automatic करता है।
• Replay attacks रोकने के लिए webhook signatures को HMAC से verify करें।
• Documents बनाने से पहले files upload करें। API को upload step से media ID चाहिए।
• Lists return करने वाले endpoints के लिए pagination use करें। सब कुछ एक साथ fetch न करें।
• Live जाने से पहले security guide check करें।

Example use cases

कुछ real-world patterns जो teams API के साथ बनाती हैं:

• E-commerce — high-value orders के लिए purchase agreements auto-generate करें और checkout पर signing के लिए भेजें
• HR onboarding — templates से employment contracts बनाएं और start date पर new hires को भेजें
• CRM integration — Salesforce या HubSpot deal records से signature requests trigger करें
• Document archival — अपनी existing storage system में documents के लिए blockchain verification add करें

आगे क्या करें

• API documentation — request/response examples के साथ full endpoint reference
• SDKs — framework-specific guides के साथ Server SDK और Embed SDK
• Webhooks — real-time event notifications setup करें
• Quick start — 10 minutes में अपनी पहली integration चलाएं
• Installation — सभी supported frameworks के लिए npm setup