Chaindoc logoChaindoc

Chaindoc REST API анықтамасы

Толық endpoint анықтамасы. Аутентификация, құжаттар, қолтаңбалар, медиа жүктеу, embedded сессиялар және блокчейн тексеруі жайлы толық ақпарат.

Жалпы шолу

Бұл API Chaindoc-тың барлық функцияларына бағдарламалық қол жеткізуді береді: құжаттар, қолтаңбалар, блокчейн тексеруі және командалық басқару. Серверден-серверге қолдануға арналған, public және secret API ключтарын қолдайды.

  • Құжаттар — құру, жаңарту және блокчейнде тексеру
  • Қолтаңбалар — қолтаңба сұрауларын жіберу және орындауды бақылау
  • Медиа — PDF, суреттер және бейнелерді жүктеу (бір сұрауға max 10 файл)
  • Embedded сессиялар — frontend үшін қолтаңба сессияларын құру (Embed SDK қолданылады)
  • KYC — Sumsub интеграциясы арқылы жеке мәліметтерді бөлісу және тексеру

Аутентификация

Әр сұрауға Authorization header-де API key қажет. Екі түрі бар:

Key түрлері

  • Public key (`pk_`) — тек оқуға, frontend кодқа қауіпсіз
  • Secret key (`sk_`) — толық оқу/жазу, тек backend. Клиенттік кодта ашпаңыз.

Key-дерді алу

1Business жоспарына жазылуТек Business жоспарының пайдаланушылары API key жасай алады

2API Access-ке өтуDashboard-та Settings → API Access бөліміне өтіңіз

3API key жасауCreate API Key батырмасын басыңыз

4Қауіпсіз сақтауSecret key-ді қауіпсіз сақтаңыз (тек бір рет көрсетіледі)

API key-ді қолдану

API key-ді Authorization header-де Bearer аутентификациясымен енгізіңіз:

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

Rate limiting

API endpoint-тері abuse-тан қорғау үшін rate limit-ке ие. Endpoint түріне қарай шектеулер әртүрлі.

  • Жалпы endpoint-тер: 10 секундта 3 сұрау
  • Медиа жүктеу: 10 секундта 3 сұрау
  • OTP тексеру: 60 секундта 5 сұрау
  • Оқу операциялары: 60 секундта 10 сұрау
  • Қолтаңба жасау: 3 секундта 20 сұрау

Rate limit асып кетсе, 429 Too Many Requests жауабын аласыз. Response-та rate limit header-лері бар:

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

Қателерді өңдеу

HTTP status кодтары

  • 200 — Сәтті
  • 201 — Ресурс сәтті жасалды
  • 400 — Жаман сұрау (validation қатесі)
  • 401 — Unauthorized (жарамсыз немесе жоқ API key)
  • 403 — Forbidden (рұқсаттар жеткіліксіз)
  • 404 — Ресурс табылмады
  • 429 — Too many requests (rate limit асып кетті)
  • 500 — Internal server error

Қате жауабының форматы

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

Жалпы API

API key ақпаратын алу

Ағымдағы API key туралы ақпарат алыңыз.

GET /me

Authorization: Bearer sk_live_xxxxx

Health check

API байланысын және key жарамдылығын тексеріңіз.

GET /health

Authorization: Bearer sk_live_xxxxx

Құжаттар API

Құжат жасау

Блокчейн тексеруімен жаңа құжат жасаңыз. Status 'published' болғанда, құжат автоматты түрде блокчейнде тексеріледі.

POST /documents

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

Құжатты жаңарту

Жаңа нұсқа жасау арқылы құжатты жаңартыңыз. Алдыңғы нұсқалар audit trail үшін сақталады.

PUT /documents/:documentId

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Құжат қолжетімділігін жаңарту

Құжаттың қолжетімділік баптауларын өзгертіңіз.

PUT /documents/:documentId/rights

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Құжатты тексеру

Блокчейн арқылы құжаттың түпнұсқалығын тексеріңіз. Transaction hash және chain ID-мен тексеру статусын қайтарады.

POST /documents/verify

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

Тексеру статусын алу

Құжат нұсқасының блокчейн тексеру статусын алыңыз.

GET /documents/versions/:versionId/verification

Authorization: Bearer sk_live_xxxxx

Қолтаңбалар API

Қолтаңба сұрауын жасау

Бір немесе бірнеше алушыға қолтаңба сұрауын жасаңыз. Frontend интеграциясы үшін embedded flow-ді қосыңыз.

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

Қолтаңба сұрауының статусын алу

Қолтаңба сұрауының статусын тексеріңіз және қай қол қоюшылар аяқтағанын қараңыз.

GET /signatures/requests/:requestId/status

Authorization: Bearer sk_live_xxxxx

Құжатқа қол қою

Құжатқа қол қою (егер API key иесі қол қоюшы болса).

POST /signatures/sign

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Пайдаланушы қолтаңбаларын алу

Аутентификацияланған пайдаланушының барлық қолтаңбаларын алыңыз.

GET /signatures

Authorization: Bearer sk_live_xxxxx

Қолтаңба сұрауларын алу

Аутентификацияланған пайдаланушының барлық қолтаңба сұрауларын pagination қолдауымен алыңыз.

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

Authorization: Bearer sk_live_xxxxx

Медиа жүктеу API

Құжат жасау үшін файлдарды жүктеңіз. PDF, суреттер және бейнелерді қолдайды. Бір сұрауға максимум 10 файл.

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

KYC API

KYC мәліметтерін бөлісу

Жеке басын тексеру үшін KYC (Know Your Customer) мәліметтерін алушылармен бөлісіңіз.

POST /kyc/share

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Embedded сессиялар API

Frontend қолданбада құжатқа қол қою үшін embedded сессиялар жасаңыз. Сессиялар 10 минут жарамды.

POST /embedded/sessions

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Келесі қадамдар

  • API интеграциясы — жалпы үлгілер, best practice және толық workflow мысалдары
  • SDKs — Server SDK және Embed SDK, фреймворк-спецификалық нұсқаулықтар
  • Webhooks — нақты уақыттағы event хабарландыруларын баптау
  • Орнату — барлық қолдайтын фреймворктер үшін npm баптауы
  • Қауіпсіздік — API key басқару және compliance