Integracja API

REST API od Chaindoc pozwala zautomatyzować obieg dokumentów, zbierać podpisy i synchronizować zdarzenia na żywo. Oto rzecz - w praktyce działa to dokładnie tak samo jak interfejs webowy, tylko programistycznie.

Co możesz zrobić z API

API daje programistyczny dostęp do wszystkiego, co oferuje Chaindoc: wgrywanie dokumentów, tworzenie żądań podpisu, zarządzanie zespołami i nasłuchiwanie zdarzeń przez webhooki. To ten sam interfejs, który napędza aplikację webową.

Trzy sposoby integracji

Wybierz ten, który pasuje do Twojego stacku. Szczerze mówiąc, większość aplikacji produkcyjnych używa Server SDK na backendzie i Embed SDK na frontendzie.

• REST API — bezpośrednie zapytania HTTP, działa z każdym językiem. Maksymalna elastyczność.
• Server SDK — type-safe wrapper dla Node.js z automatycznymi retryami i obsługą błędów (`@chaindoc_io/server-sdk`)
• Embed SDK — wstawia interfejs podpisywania do Twojej aplikacji, więc użytkownicy nie opuszczają strony (`@chaindoc_io/embed-sdk`)

Jeśli jeszcze nie zainstalowałeś SDK, przewodnik instalacji opisuje konfigurację npm dla React, Vue, Angular i Next.js.

Szybki przykład

Ten sam kod tworzący dokument w trzech wersjach. Wersja SDK jest najzwięźlejsza, ale surowe wywołanie REST pokazuje dokładnie, co dzieje się w sieci.

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

Autentykacja

Każde zapytanie wymaga klucza API w nagłówku Authorization:

Authorization: Bearer sk_live_xxxxxxxxxxxxx

Są dwa rodzaje kluczy, a pomylenie ich to najczęstszy błąd integracyjny:

• Klucze publiczne (`pk_`) — tylko do odczytu, bezpieczne dla kodu frontend
• Klucze sekretne (`sk_`) — pełen dostęp read/write, wyłącznie backend. Nigdy nie eksponuj ich w kodzie klienckim.
• Oba rodzaje występują w wersji testowej (`_test_`) i produkcyjnej (`_live_`). Klucze testowe trafiają do sandboxa.

Limity zapytań

API zwraca informacje o limitach w nagłówkach odpowiedzi. Jeśli przekroczysz limit, dostaniesz kod 429. Poczekaj i spróbuj ponownie.

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

• Ogólne endpointy: 3 zapytania na 10 sekund
• Wgrywanie mediów: 3 zapytania na 10 sekund
• Operacje odczytu: 10 zapytań na 60 sekund
• Tworzenie podpisów: 20 zapytań na 3 sekundy

Server SDK obsługuje retrye automatycznie z wykładniczym wycofaniem. Jeśli używasz surowego HTTP, zaimplementuj logikę retry samodzielnie.

Obsługa błędów

Błędy wracają jako JSON z kodem statusu, komunikatem i (dla błędów walidacji) listą konkretnych problemów z polami:

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

Najważniejsze kody statusu: 400 (złe zapytanie), 401 (nieprawidłowy klucz), 403 (plan nie obejmuje API), 404 (nie znaleziono), 429 (limit przekroczony), 500 (błąd serwera). Dla błędów 5xx spróbuj ponownie z wycofaniem.

Typowe wzorce integracyjne

Pełny proces podpisywania (embedded)

Najpopularniejszy wzorzec: wgraj dokument, wyślij go do podpisania i pokaż UI podpisywania wewnątrz aplikacji.

Przewodnik quick start zawiera pełny kod dla tego procesu.

Podpisywanie emailowe (bez embeda)

Jeśli podpisujący nie używają Twojej aplikacji, ustaw `embeddedFlow: false`. Chaindoc wyśle im email z linkiem do podpisu. Wciąż dostaniesz powiadomienia webhooka, gdy podpiszą.

// Tworzenie żądania podpisu z linkiem email
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ email: 'signer@example.com' }],
  deadline: new Date('2024-12-31'),
  embeddedFlow: false, // Podpisujący dostają linki email
  message: 'Proszę o przegląd i podpis dokumentu',
});

Przetwarzanie masowe dokumentów

Dla importów wsadowych przeiteruj przez swoje pliki i wgraj każdy. Uważaj na limity. Jeśli przetwarzasz setki dokumentów, dodaj małe opóźnienie między zapytaniami lub użyj wbudowanej logiki retry z SDK.

// Przetwarzanie wsadowe
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: 'Dokument przetworzony wsadowo',
    media: media[0],
    status: 'published',
    hashtags: ['#batch'],
    meta: [{ key: 'batch', value: 'import-2024' }],
  });
}

Integracja KYC

Dla procesów o wysokim poziomie bezpieczeństwa, wymagaj weryfikacji tożsamości przed podpisaniem. Chaindoc integruje się z Sumsub dla KYC. Ustaw `isKycRequired: true` w żądaniu podpisu, a podpisujący przejdą weryfikację tożsamości zanim będą mogli podpisać.

// Żądanie podpisu z wymaganym KYC
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ 
    email: 'signer@example.com',
    shareToken: 'sumsub_token_here' // Opcjonalnie: pre-weryfikowany
  }],
  deadline: new Date('2024-12-31'),
  isKycRequired: true,
});

Kontrola dostępu przez API

Możesz ustawiać uprawnienia do dokumentów programistycznie. Ogranicz dostęp do konkretnych emaili lub ról zespołowych:

// Ustawianie ograniczonych uprawnień
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' },
  ],
});

Najlepsze praktyki

• Trzymaj klucze API w zmiennych środowiskowych. Nigdy nie commituj ich do kontroli wersji.
• Używaj kluczy testowych (`sk_test_`) podczas developmentu. Klucze live (`sk_live_`) trafiają do produkcji.
• Implementuj wykładnicze wycofywanie dla odpowiedzi 429. SDK robi to automatycznie.
• Weryfikuj podpisy webhooków z HMAC, aby zapobiec atakom replay.
• Wgrywaj pliki przed tworzeniem dokumentów. API potrzebuje ID mediów z kroku upload.
• Używaj paginacji dla endpointów zwracających listy. Nie pobieraj wszystkiego naraz.
• Sprawdź przewodnik bezpieczeństwa przed uruchomieniem produkcyjnym.

Przykładowe zastosowania

Kilka realnych wzorców, które zespoły budują z API:

• E-commerce — automatycznie generuj umowy zakupu dla zamówień o wysokiej wartości i wysyłaj do podpisu przy checkout
• HR onboarding — twórz umowy o pracę z szablonów i wysyłaj do nowych pracowników w dniu rozpoczęcia
• Integracja CRM — wywołuj żądania podpisu z rekordów deala w Salesforce lub HubSpot
• Archiwizacja dokumentów — dodawaj weryfikację blockchain do dokumentów w istniejącym systemie storage

Co zrobić dalej

• Dokumentacja API — pełna referencja endpointów z przykładami request/response
• SDK — Server SDK i Embed SDK z przewodnikami dla konkretnych frameworków
• Webhooki — skonfiguruj powiadomienia o zdarzeniach w czasie rzeczywistym
• Quick start — uruchom pierwszą integrację w 10 minut
• Instalacja — konfiguracja npm dla wszystkich wspieranych frameworków