Dokumentacja Chaindoc REST API

Pełna dokumentacja endpointów Chaindoc REST API. Obejmuje autentykację, dokumenty, podpisy, upload mediów, sesje osadzone i weryfikację blockchain.

Przegląd

API daje Ci programistyczny dostęp do wszystkiego w Chaindoc: dokumentów, podpisów, weryfikacji blockchain i zarządzania zespołem. Szczerze mówiąc, zostało zaprojektowane do użytku serwer-serwer i obsługuje zarówno publiczne, jak i tajne klucze API.

• Dokumenty — twórz, aktualizuj i weryfikuj dokumenty na blockchainie
• Podpisy — wysyłaj prośby o podpis i śledź ich realizację
• Media — uploaduj PDFy, obrazy i wideo (max 10 na zapytanie)
• Sesje osadzone — twórz sesje podpisywania dla swojego frontendu (używa Embed SDK)
• KYC — udostępniaj i weryfikuj dane tożsamości przez integrację Sumsub

Autentykacja

Każde zapytanie wymaga klucza API w nagłówku Authorization. Są dwa rodzaje:

Rodzaje kluczy

• Klucz publiczny (`pk_`) — tylko do odczytu, bezpieczny dla kodu frontendowego
• Klucz tajny (`sk_`) — pełny odczyt/zapis, wyłącznie backend. Nigdy nie eksponuj w kodzie client-side.

Jak uzyskać klucze

Używanie kluczy API

Dołącz swój klucz API w nagłówku Authorization z autentykacją Bearer:

curl -X GET https://api.chaindoc.io/api/v1/me \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx"

Limitowanie zapytań

Endpointy API mają limity zapobiegające nadużyciom. Limity różnią się w zależności od typu endpointu. W praktyce warto to mieć na uwadze przy projektowaniu integracji.

• Endpointy ogólne: 3 zapytania na 10 sekund
• Upload mediów: 3 zapytania na 10 sekund
• Weryfikacja OTP: 5 zapytań na 60 sekund
• Operacje odczytu: 10 zapytań na 60 sekund
• Tworzenie podpisów: 20 zapytań na 3 sekundy

Gdy limit zostanie przekroczony, otrzymasz odpowiedź 429 Too Many Requests. Nagłówki limitów są zawarte w odpowiedziach:

X-RateLimit-Limit: 3
X-RateLimit-Remaining: 2
X-RateLimit-Reset: 1640000000

Obsługa błędów

Kody statusu HTTP

• 200 - Sukces
• 201 - Zasób utworzony pomyślnie
• 400 - Nieprawidłowe zapytanie (błąd walidacji)
• 401 - Nieautoryzowany (nieprawidłowy lub brak klucza API)
• 403 - Zabroniony (niewystarczające uprawnienia)
• 404 - Zasób nie znaleziony
• 429 - Zbyt wiele zapytań (przekroczony limit)
• 500 - Wewnętrzny błąd serwera

Format odpowiedzi błędu

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

API ogólne

Pobierz info o kluczu API

Pobierz informacje o aktualnym kluczu API.

GET /me

Authorization: Bearer sk_live_xxxxx

Health check

Zweryfikuj połączenie z API i ważność klucza.

GET /health

Authorization: Bearer sk_live_xxxxx

API Dokumentów

Utwórz dokument

Utwórz nowy dokument z weryfikacją blockchain. Gdy status ustawiony jest na 'published', dokument automatycznie trafia na blockchain.

POST /documents

Headers:
Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Aktualizuj dokument

Aktualizuj dokument tworząc nową wersję. Poprzednie wersje są zachowywane dla audytu.

PUT /documents/:documentId

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Aktualizuj prawa dostępu do dokumentu

Zaktualizuj ustawienia kontroli dostępu do dokumentu.

PUT /documents/:documentId/rights

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Weryfikuj dokument

Zweryfikuj autentyczność dokumentu używając blockchain. Zwraca status weryfikacji z hashem transakcji i ID chaina.

POST /documents/verify

{
  "versionHash": "0x123abc...",
  "certificateHash": "0x456def..."
}

Pobierz status weryfikacji

Sprawdź status weryfikacji blockchain dla wersji dokumentu.

GET /documents/versions/:versionId/verification

Authorization: Bearer sk_live_xxxxx

API Podpisów

Utwórz prośbę o podpis

Utwórz prośbę o podpis dla jednego lub więcej odbiorców. Włącz embedded flow dla integracji frontendowej.

curl -X POST https://api.chaindoc.io/api/v1/signatures/requests \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "versionId": "f0b7721f-0399-4035-9b69-7b95d3a367f0",
    "recipients": [{"email": "signer@example.com"}],
    "deadline": "2024-12-31T23:59:59Z",
    "embeddedFlow": true
  }'

Sprawdź status prośby o podpis

Sprawdź status prośby o podpis i zobacz, którzy sygnatariusze ukończyli podpisywanie.

GET /signatures/requests/:requestId/status

Authorization: Bearer sk_live_xxxxx

Podpisz dokument

Podpisz dokument (jeśli właściciel klucza API jest sygnatariuszem).

POST /signatures/sign

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Pobierz podpisy użytkownika

Pobierz wszystkie podpisy dla zautoryzowanego użytkownika.

GET /signatures

Authorization: Bearer sk_live_xxxxx

Pobierz prośby o podpis

Pobierz wszystkie prośby o podpis dla zautoryzowanego użytkownika z obsługą paginacji.

GET /signatures/requests?pageNumber=1&pageSize=10

Authorization: Bearer sk_live_xxxxx

API Uploadu Mediów

Uploaduj pliki do użycia przy tworzeniu dokumentów. Obsługuje PDF, obrazy i wideo. Maksymalnie 10 plików na zapytanie.

curl -X POST https://api.chaindoc.io/api/v1/media/upload \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -F "media=@contract.pdf"

API KYC

Udostępnij dane KYC

Udostępnij dane KYC (Know Your Customer) odbiorcom do weryfikacji tożsamości.

POST /kyc/share

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

API Sesji Osadzonych

Twórz sesje osadzone do podpisywania dokumentów w aplikacji frontendowej. Sesje są ważne przez 10 minut.

POST /embedded/sessions

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Co dalej

• Integracja API — typowe wzorce, najlepsze praktyki i pełne przykłady workflow
• SDK — Server SDK i Embed SDK z przewodnikami dla konkretnych frameworków
• Webhooki — skonfiguruj powiadomienia o zdarzeniach w czasie rzeczywistym
• Instalacja — setup npm dla wszystkich obsługiwanych frameworków
• Bezpieczeństwo — zarządzanie kluczami API i compliance