Integracja API

Zintegruj Chaindoc ze swoimi aplikacjami dzięki naszemu potężnemu REST API i SDK. Zautomatyzuj przepływ dokumentów, zbieraj podpisy i synchronizuj wydarzenia w czasie rzeczywistym.

Przegląd

Chaindoc zapewnia kompleksowy interfejs API REST, który umożliwia tworzenie niestandardowych przepływów pracy związanych z podpisywaniem dokumentów, automatyzację procesów i integrację z istniejącymi systemami. Interfejs API jest przeznaczony dla programistów i zapewnia pełną obsługę języka TypeScript oraz automatyczne ponawianie prób.

Pierwsze kroki

1. Uzyskaj dostęp do API

2. Wybierz metodę integracji

Chaindoc oferuje trzy podejścia do integracji:

• REST API — bezpośrednie żądania HTTP zapewniające maksymalną elastyczność
• Server SDK — bezpieczny pod względem typów SDK Node.js z automatycznymi ponownymi próbami (@chaindoc_io/server-sdk)
• Embed SDK — interfejs podpisywania frontendu dla aplikacji internetowych (@chaindoc_io/embed-sdk)

3. Szybki przykład

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": []
  }'

Podstawowe pojęcia API

Uwierzytelnianie

Wszystkie żądania API wymagają uwierzytelnienia za pomocą kluczy API w nagłówku Authorization:

Authorization: Bearer sk_live_xxxxxxxxxxxxx

• Klucze publiczne (pk_) — dostęp tylko do odczytu dla aplikacji frontendowych
• Klucze tajne (sk_) – pełny dostęp do odczytu/zapisu dla serwerów zaplecza
• Klucze testowe (pk_test_, sk_test_) — do celów stagingu/rozwoju
• Klucze Live (pk_live_, sk_live_) — do produkcji

Limity szybkości

Punkty końcowe API mają ograniczenia szybkości, aby zapewnić sprawiedliwe korzystanie:

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

• Ogólne punkty końcowe: 3 żądania na 10 sekund
• Przesyłanie multimediów: 3 żądania na 10 sekund
• Operacje odczytu: 10 żądań na 60 sekund
• Tworzenie podpisów: 20 żądań na 3 sekundy

Obsługa błędów

API zwraca standardowe kody statusu HTTP wraz ze szczegółowymi komunikatami o błędach:

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

Typowe wzorce integracji

Przesyłanie dokumentów i proces podpisywania

Przepływ pracy wyłącznie w backendzie

W przypadku sytuacji, w których podpisujący nie korzystają z twojego interfejsu:

// Create signature request with email notifications
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ email: 'signer@example.com' }],
  deadline: new Date('2024-12-31'),
  embeddedFlow: false, // Signers use Chaindoc email links
  message: 'Please review and sign this document',
});

// Chaindoc sends emails to recipients
// Track status via webhooks or API polling

Przetwarzanie dokumentów zbiorczych

// Process multiple documents in batch
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' }],
  });
}

Funkcje zaawansowane

Webhooki

Otrzymuj powiadomienia w czasie rzeczywistym o zdarzeniach dotyczących dokumentów:

// Configure webhook endpoint
app.post('/webhooks/chaindoc', async (req, res) => {
  const event = req.headers['x-webhook-event'];
  
  switch (event) {
    case 'document.verified':
      await handleBlockchainVerification(req.body);
      break;
    case 'signature.request.completed':
      await notifyAllParties(req.body);
      break;
  }
  
  res.status(200).send('OK');
});

Integracja KYC

Zintegruj weryfikację tożsamości w celu zapewnienia wysokiego poziomu bezpieczeństwa przepływu pracy:

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

Kontrola dostępu

Zarządzaj uprawnieniami do dokumentów dzięki szczegółowej kontroli dostępu:

// Update document access rights
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' }, // Team role
  ],
});

Najlepsze praktyki

• Klucze API przechowuj w zmiennych środowiskowych, nigdy w kodzie
• Używaj kluczy testowych do celów programistycznych, a kluczy produkcyjnych do celów produkcyjnych.
• Wprowadź wykładnicze wycofywanie w celu obsługi limitów szybkości.
• Sprawdź podpisy webhooków, aby zapobiec atakom typu replay.
• W razie potrzeby buforuj odpowiedzi API.
• Aby uzyskać lepszą wydajność, przed utworzeniem dokumentów prześlij pliki.
• W przypadku dużych zbiorów danych używaj paginacji.
• Monitoruj nagłówki limitów szybkości i dostosowuj częstotliwość żądań

Przykładowe integracje

Platforma e-commerce

Automatycznie generuj i podpisuj umowy zakupu dla zamówień o wysokiej wartości.

System HR

Zintegruj z systemem HRIS, aby zautomatyzować podpisywanie umów o pracę podczas procesu wdrażania nowych pracowników.

Integracja CRM

Twórz prośby o podpis bezpośrednio z rekordów klientów w Salesforce, HubSpot lub niestandardowym CRM.

System zarządzania dokumentami

Dodaj weryfikację blockchain do istniejącego systemu zarządzania dokumentami (DMS), aby zapewnić odporne na manipulacje ścieżki audytu.

Zasoby

• Dokumentacja API — kompletna dokumentacja REST API ze wszystkimi punktami końcowymi
• SDK — dokumentacja SDK serwera i SDK osadzania z przykładami frameworków
• Webhooki — przewodnik konfiguracji powiadomień o zdarzeniach w czasie rzeczywistym
• Szybki start — uruchom swoją pierwszą integrację w 10 minut
• Przykłady GitHub — przykładowe integracje i fragmenty kodu