Құжаттарға қол қою Documentolog API арқылы
Жылдам іске қосу және заңдық күш
Құжат
Қалыптастырылуда
Қол қою
Аяқталды
Интеграция туралы
Сіздің өніміңізге заңдық маңызы бар құжаттарға қол қою
Бұл шешім кімге қолайлы:
Банктер және финтех компаниялар: несиелік шарттар, келісімдер, қосымша келісімдер және т.б.
B2B SaaS жүйелер: шарттар, акттер және NDA
Маркетплейстер: салыстыру акттері, сатушылармен/сатып алушылармен шарттар
Компаниялардың басқа түрлері
Documentolog API мүмкіндіктері:
Құжаттарды жасау және оларды API сұрауы арқылы қол қоюға жіберу
Documentolog-тың заңдық маңызы бар инфрақұрылымын пайдалану
Қол қоюдың бірнеше әдісін қолдау: ЭЦҚ, Egov QR, SMS, Adobe Sign
Қол қою процесін iframe арқылы сіздің интерфейсіңізге енгізу
Webhook арқылы қол қою нәтижесін алу
Процесс сипаттамасы
Құжатты жіберу және қол қою
- Бастамашы шарт файлын жүйеге жүктейді — PDF, Word, Excel және басқа форматтарға қолдау көрсетіледі.
- Бастамашы алушыны көрсетеді — телефон нөмірі, ЖСН, БСН немесе email бойынша.
- Бастамашы жіберу түрін таңдайды: тек көру немесе қол қою.
- Бастамашы «Жіберу» түймесін басады және қажет болса құжатқа өзі қол қояды — одан кейін құжат алушыға жіберіледі.
- Алушы сілтеме немесе хабарлама алып, құжатты өз құрылғысында ашады. Егер алушы Documentolog Business-та тіркелген болса, құжат оның жүйесінде автоматты түрде пайда болады.
- Алушы өзіне ыңғайлы қол қою әдісін таңдап, құжатқа қол қояды.
- Бастамашы қол қойылғаны туралы хабарламаны және дайын файлды алады
Алушы құжатқа қол қойған жоқ
Алушы құжатты өз құрылғысында ашады:
- Егер алушы қол қоймауды шешсе — ол «Қабылдамау» түймесін басады. Бастамашы бірден хабарлама алады және себептерін нақтылау үшін алушымен байланыса алады.
- Егер алушы шешім қабылдамай құжатты жапса — сілтеме 30 күн бойы белсенді болып қалады. Бастамашы «Қол қойылмады» мәртебесін көреді және қайта еске салу жібере алады.
Әзірлеушілерге арналған құжаттама
Бұл құжаттама access token алу және оны iframe-ге енгізу үшін пайдалану процесін сипаттайды.
Бұл құжаттармен жұмыс істеу және оларға API арқылы қол қою үшін қажет
Интеграцияны бастау үшін жүйеде тіркелу қажет:
Сайтта https://documentolog.com/ "Тегін бастау" түймесін басып, Documentolog Business жүйесінде тіркеліңіз.
Documentolog API-ге қол жеткізу үшін Business тарифін сатып алу қажет. Толығырақ: https://documentolog.com/tariffs
Тарифті төлегеннен кейін "Интеграциялар" бөліміне өтіңіз
"API Documentolog" қойындысына өтіңіз
1-бөлім: Access Token алу
1.1 Access Token сұрауы
Access token алу үшін келесі cURL сұрауын орындаңыз:
36 жол
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
curl --location 'https://apibusiness.documentolog.com/json/external/oauth/token' \
--header 'api-key: {{api-key}}' \
--header 'Content-Type: application/json' \
--data '{
"aAttachments": [
"https://business.documentolog.com/rct/sample.pdf"
],
"sSetWebhookUrl": "https://your-server.com/webhook",
"iSendToRecipient": 1,
"mRecipient": [
"000000000000"
],
"mPhonesForSms": [
{
"enableBMG": false,
"phone": "+X (XXX) XXX-XX-XX",
"fio": "Simple name",
"iin": "",
"type": "sms"
}
],
"iRecipientSignatureRequired": 1,
"mAvailableSignatureMethodsForRecipient": [
"eds",
"egov-qr",
"adobe-sign",
"sms"
],
"mAvailableSignatureMethods": [
"eds",
"egov-qr",
"adobe-sign",
"sms"
],
"sSender": "000000000000"
}'
1.2 Сұрау параметрлері
Сұрау денесінің параметрлері:
aAttachments — файлдарға сілтемелер массиві (қолдау көрсетілетін форматтар: docx, doc, xlsx, xls, pptx, ppt, pdf, rar, zip, rtf, tiff, jpeg, jpg, png, gdoc). Кеңейтімсіз файл атауының ұзындығы 32 таңбадан аспауы керек
sSetWebhookUrl — құжат мәртебесі туралы webhook-хабарламаларды алуға арналған URL (жіберу, қол қою, аяқтау)
iSendToRecipient — құжатты алушыға жіберу керек пе (1 = иә, 0 = жоқ)
mRecipient — алушылар тізімі (ЖСН, БСН, телефон нөмірін немесе эл. поштаны пайдалануға болады)
mPhonesForSms — SMS-қолтаңбаларды жіберуге арналған объектілер массиві
enableBMG — SMS жіберу үшін BMG қызметін пайдалану-пайдаланбау
phone — алушының телефон нөмірі +X (XXX) XXX-XX-XX форматында
fio — алушының толық аты-жөні
iin — алушының ЖСН-і
type — жіберу түрі (sms)
iRecipientSignatureRequired — алушының қолтаңбасы қажет пе (1 = иә, 0 = жоқ)
mAvailableSignatureMethodsForRecipient — құжатты ашқан кезде алушыларға қолжетімді қол қою әдістері (eds, egov-qr, adobe-sign, sms)
mAvailableSignatureMethods — iframe-де жіберушіге қолжетімді қол қою әдістері
sSender — жіберушінің сәйкестендіру нөмірі (ЖСН немесе БСН)
1.3 Сұрау нәтижесі
Сәтті сұрауға жауап келесі форматта болады:
8 жол
01
02
03
04
05
06
07
08
{
"status": 1,
"data": {
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"scope": "document-create|document-sign|document-show",
"token_type": "Bearer"
}
}
access_token — ресурстарға қол жеткізу үшін пайдаланылатын токен. Қолданылу мерзімі — 30 күн
scope — құжаттармен қолжетімді әрекеттер
token_type — токен түрі, әдетте "Bearer"
1.4 Авторизация қателерінің кодтары
Авторизацияда мәселелер туындаған кезде API келесі қате кодтарын қайтарады:
| Қате коды | HTTP-мәртебе | Сипаттама және шешім |
|---|---|---|
| invalid_client | 401 Unauthorized | Қате api-key. api-key тақырыбының мәнін жеке кабинетте тексеріңіз. |
| unauthorized | 401 Unauthorized | access_token мерзімі өткен (қолданылу мерзімі 30 күн) немесе берілмеген. Жаңа токенді oauth/token-ге қайта сұрау жіберу арқылы алу қажет. |
| status: 0 | 200 | Сұраудың логикалық қатесі. Толық мәліметтер жауаптың message өрісінде. |
1.5 Токенді сұрауларда беру
access_token алғаннан кейін оны Authorization тақырыбында беріңіз:
1 жол
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
Маңызды: access_token тек Authorization: Bearer тақырыбында беріледі. sParams параметрі тек iframe енгізуге арналған және авторизация тақырыбын алмастырмайды.
2-бөлім: Токенді iframe-ге енгізу
access token алғаннан кейін оны әрі қарай пайдалану үшін iframe-ге енгізуге болады. Бір токен бір құжатқа байланған.
2.1 Енгізуге арналған URL
Алынған access token-ді қойып, келесі URL-ді пайдаланыңыз:
1 жол
01
https://apibusiness.documentolog.com/external/sign/embedded?sParams={{data.access_token}}
Енгізу мысалы:
1 жол
01
<iframe src="https://apibusiness.documentolog.com/external/sign/embedded?sParams=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." width="400px" height="600px"></iframe>
Құжатқа қол қою үшін iframe-нің сыртқы түрі
3-бөлім: postMessage оқиғасы
3.1 Қол қою нәтижесі
Қол қою процесі аяқталғанда, iframe window.parent.postMessage функциясы арқылы ата-аналық терезеге хабарлама жібереді. Хабарлама мысалы:
6 жол
01
02
03
04
05
06
{
isDocumentolog: true,
type: 'sign',
success: true | false,
signType: 'eds' | 'egov_gr'
}
isDocumentolog — Documentolog жүйесінің пайдаланылғанын көрсететін жалау (әрқашан true)
type — оқиға түрі
success — қол қою нәтижесі
signType — қол қою кезінде пайдаланылатын қолтаңба түрі (мысалы, 'eds')
3.2 iframe-ді жабу
Пайдаланушы iframe-ді жабуға тырысқанда, iframe window.parent.postMessage функциясы арқылы ата-аналық терезеге хабарлама жібереді. Хабарлама мысалы:
5 жол
01
02
03
04
05
{
isDocumentolog: true,
type: 'user-close',
success: false,
}
isDocumentolog — Documentolog жүйесінің пайдаланылғанын көрсететін жалау (әрқашан true)
type — оқиға түрі
success — қол қою нәтижесі
3.3 Құжат бұрын қол қойылған
Егер осы токенге арналған құжатқа бұрын қол қойылған болса, iframe жұмысын дереу аяқтап, ата-аналық терезеге оқиға жібереді:
5 жол
01
02
03
04
05
{
isDocumentolog: true,
type: 'already-signed',
success: true,
}
type — оқиға түрі
success — қол қою нәтижесі
4-бөлім: Webhook
4.1 Аралық оқиғалар
Құжаттың өмірлік циклі барысында webhook-мекенжайға аралық оқиғалар келеді.
4 жол
01
02
03
04
{
"event": "document_sent",
"doc_id": "KZ000000000000000001234567"
}
8 жол
01
02
03
04
05
06
07
08
{
"event": "signer_signed"|"signer_declined",
"doc_id": "KZ000000000000000001234567",
"signer": {
"name": "Сейтқали Нұрлан",
"recipient": "000000000000"
}
}
event — оқиға түрі: document_sent — құжат алушыларға жіберілді, signer_signed — қол қойылды, signer_declined — қабылданбады, document_completed — барлық тараптар қол қойды
doc_id — құжаттың бірегей идентификаторы. «Құжаттар» бөліміндегі DOC ID-мен сәйкес келеді. Бір құжаттың барлық оқиғаларында бірдей
signer — қол қоюшы деректері (signer_signed және signer_declined оқиғаларында болады)
name — қол қоюшының толық аты-жөні
recipient — қол қоюшының ЖСН-і, БСН-і, телефоны немесе эл. поштасы
4.2 Құжатты аяқтау
Барлық қатысушы тараптар құжатқа қол қойғанда, қорытынды хабарлама sSetWebhookUrl-ге жіберіледі:
24 жол
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
"event": "document_completed",
"doc_id": "KZ000000000000000001234567",
"document": "https://apibusiness.documentolog.com/external/document/view-document/dcs_universal_type/1234",
"download_all_files": "https://apibusiness.documentolog.com/external/media/download-many?files=4444",
"download_files": [
{
"name": "sample.pdf",
"link": "https://apibusiness.documentolog.com/external/media/download/4444"
}
],
"download_files_with_eds": [
{
"name": "sample.pdf",
"link": "https://apibusiness.documentolog.com/external/media/download-eds/dcs_universal_type/1234/4444"
}
],
"download_files_with_eds_ez": [
{
"name": "sample.pdf",
"link": "https://apibusiness.documentolog.com/external/media/download-eds-ez/dcs_universal_type/1234/4444"
}
]
}
event — оқиға түрі (document_completed)
doc_id — құжаттың бірегей идентификаторы. «Құжаттар» бөліміндегі DOC ID-мен сәйкес келеді. Бір құжаттың барлық оқиғаларында бірдей
document — құжатқа сілтеме
download_all_files — барлық файлдарды жүктеуге арналған сілтеме
download_files — файлдарды жүктеуге арналған сілтемелер тізімі
download_files_with_eds — ЭЦҚ-сы бар файлдарды жүктеуге арналған сілтемелер тізімі
download_files_with_eds_ez — ezSigner үшін файлдарды жүктеуге арналған сілтемелер тізімі
4.3 Жеткізу саясаты (retry)
Жүйе webhook event-ті мынадай мерзімділікпен қайта жібереді: 5, 15, 30, 60, 120, 240, 480, 960, 1440 минут. Соңғы әрекеттен кейін жүйе event-ті failed деп белгілеп, қайта жіберуді тоқтатады.
4.4 Файл сілтемелерінің қолданылу мерзімі
document_completed оқиғасында келетін download_files, download_files_with_eds және download_files_with_eds_ez өрістеріндегі сілтемелер:
| Өріс | Сілтеменің қолданылу мерзімі |
|---|---|
| download_files | Сілтеме тұрақты, құжат жүйеде бар болғанша жарамды. |
| download_files_with_eds | Сілтеме тұрақты, құжат жүйеде бар болғанша жарамды. |
| download_all_files | Сілтеме тұрақты, құжат жүйеде бар болғанша жарамды. |
Маңызды: сілтемелер браузерде тікелей ашылмайды. Сілтемеге өткен кезде браузер логин мен құпия сөзді сұрайды — бұл авторизация тақырыбы болмаған кездегі қалыпты әрекет. Жүктеу үшін құжат жасалған сол access_token-ді беріңіз:
4 жол
01
02
03
04
curl --location \
'{{ссылка из webhook}}' \
--header 'Authorization: Bearer {{access_token}}' \
--output document.pdf
Postman арқылы: Authorization қойындысы → Bearer Token → токенді қою → Send.
5-бөлім: API шектеулері мен жорамалдары
Келесі сценарийлерге API арқылы қолдау көрсетілмейді. Оларды жүзеге асыру талпынысы қатеге немесе күтпеген әрекетке әкеледі.
| Шектеу | Түсіндірме |
|---|---|
| Құжатты жоба ретінде жасау мүмкін емес | Құжат create-document шақырылған кезде алушыға дереу жіберіледі. API арқылы кейінге қалдырып жіберу қарастырылмаған. |
| Жіберуші (sSender) қол қоюшы болуға міндетті | Құжатты жіберушінің қолтаңбасынсыз жіберу мүмкін емес. Жіберушінің қол қоюын API арқылы өшіру мүмкін емес. |
| Қол қою кезектілігін баптау мүмкін емес | API тараптардың құжатқа қол қою ретін белгілеуді қолдамайды. Барлық қатысушылар қолжетімділікті бір уақытта алады. |
| Жіберуші тарапынан қол қоюды өшіру мүмкін емес | mAvailableSignatureMethods өрісі әрқашан жіберушіге қолданылады. Жіберушіні қол қою тізбегінен шығаруға арналған параметр жоқ. |
6-бөлім: Тест ортасы
Жалпыға қолжетімді тест ортасы жоқ. Тестілеу нақты деректерді пайдалана отырып, жұмыс ортасында орындалады.
Тестілеу бойынша ұсынымдар
Сізге берілген есептік жазбалардағы тестілік ЖСН/БСН-ді пайдаланыңыз.
aAttachments ретінде шағын тестілік PDF файлға сілтеме көрсетіңіз.
sSetWebhookUrl үшін оқиғаларды нақты серверсіз қабылдау мақсатында webhook.site сияқты құралдарды пайдаланыңыз.