Referencja REST API Chaindoc

Kompletne odniesienie dotyczące integracji interfejsu API REST Chaindoc z twoimi aplikacjami. Zarządzaj dokumentami, podpisami, weryfikacją łańcucha bloków i wbudowanymi procesami podpisywania.

Przegląd

Chaindoc REST API zapewnia programowy dostęp do funkcji zarządzania dokumentami, weryfikacji łańcucha bloków i podpisu cyfrowego. API jest przeznaczone do integracji między serwerami i obsługuje zarówno publiczne, jak i tajne klucze API.

Najważniejsze cechy

• Zarządzanie dokumentami — twórz, aktualizuj i zarządzaj dokumentami z weryfikacją blockchain
• Podpisy cyfrowe — żądaj i zbieraj podpisy cyfrowe od wielu stron
• Weryfikacja łańcucha bloków — weryfikuj autentyczność dokumentów w sieciach łańcucha bloków
• Sesje osadzone — twórz bezpieczne sesje dla procesów podpisywania frontendu
• Przesyłanie multimediów — przesyłaj pliki (PDF, obrazy, filmy) w celu tworzenia dokumentów
• Integracja KYC — udostępniaj i weryfikuj dane tożsamości za pomocą Sumsub

Uwierzytelnianie

Chaindoc API wykorzystuje klucze API do uwierzytelniania. Istnieją dwa rodzaje kluczy o różnych poziomach dostępu.

Typy kluczy API

• Klucz publiczny (pk_) – dostęp tylko do odczytu dla aplikacji frontendowych i weryfikacji
• Klucz tajny (sk_) – pełny dostęp do odczytu i zapisu dla serwerów zaplecza

Uzyskiwanie kluczy API

Korzystanie z kluczy API

Dodaj swój klucz API w nagłówku autoryzacji z uwierzytelnieniem Bearer:

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

Ograniczanie szybkości

Punkty końcowe API mają ograniczenia szybkości, aby zapobiec nadużyciom. Ograniczenia szybkości różnią się w zależności od typu punktu końcowego.

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

W przypadku przekroczenia limitu szybkości otrzymasz odpowiedź 429 Too Many Requests. Nagłówki limitu szybkości 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 został pomyślnie utworzony
• 400 – Nieprawidłowe żądanie (błąd walidacji)
• 401 – Nieautoryzowany (nieprawidłowy lub brakujący klucz API)
• 403 – Niedozwolone (niewystarczające uprawnienia)
• 404 – Nie znaleziono zasobu
• 429 – Zbyt wiele żądań (przekroczono 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"
    }
  ]
}

Ogólne API

Uzyskaj informacje o kluczu API

Uzyskaj informacje o aktualnym kluczu API.

GET /me

Authorization: Bearer sk_live_xxxxx

Kontrola stanu

Sprawdź łączność API i ważność klucza.

GET /health

Authorization: Bearer sk_live_xxxxx

Dokumenty API

Utwórz dokument

Utwórz nowy dokument z weryfikacją blockchain. Gdy status zostanie ustawiony na „opublikowany”, dokument zostanie automatycznie zweryfikowany w 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 na potrzeby ścieżki audytu.

PUT /documents/:documentId

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Zaktualizuj prawa dostępu do dokumentów

Zaktualizuj ustawienia kontroli dostępu do dokumentów.

PUT /documents/:documentId/rights

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Sprawdź dokument

Weryfikuj autentyczność dokumentów za pomocą technologii blockchain. Zwraca status weryfikacji wraz z skrótem transakcji i identyfikatorem łańcucha.

POST /documents/verify

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

Uzyskaj status weryfikacji

Uzyskaj status weryfikacji blockchain dla wersji dokumentu.

GET /documents/versions/:versionId/verification

Authorization: Bearer sk_live_xxxxx

Podpisy API

Utwórz prośbę o podpis

Utwórz żądanie podpisu dla jednego lub kilku odbiorców. Włącz wbudowany przepływ dla integracji frontendu.

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
  }'

Uzyskaj status żądania podpisu

Sprawdź status wniosku o podpisanie i zobacz, którzy sygnatariusze zakoń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żytkowników

Pobierz wszystkie podpisy dla uwierzytelnionego użytkownika.

GET /signatures

Authorization: Bearer sk_live_xxxxx

Otrzymuj prośby o podpisy

Pobierz wszystkie żądania podpisu dla uwierzytelnionego użytkownika z obsługą paginacji.

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

Authorization: Bearer sk_live_xxxxx

API przesyłania multimediów

Prześlij pliki do wykorzystania podczas tworzenia dokumentu. Obsługiwane formaty to PDF, obrazy i filmy. Maksymalnie 10 plików na jedno żądanie.

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

KYC API

Udostępniaj dane KYC

Udostępniaj dane KYC (Know Your Customer) odbiorcom w celu weryfikacji tożsamości.

POST /kyc/share

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Wbudowane API sesji

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

POST /embedded/sessions

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json