 API

DiMaker API-ін пайдалана отырып, дербес деректермен файлдар құруға, қажет болған жағдайда оларды алыушыларға беру мүмкіндігіне ие бола аласыз. API сұранымдары басқа серверден немесе браузерден CORS сұранымы арқылы жіберілуі мүмкін.

Қалай бастау керек

«Интеграция» - «API Токендері» бөлімінде Сізге Secure токенін алу және оны пайдалану рұқсат ету қажет. Сонымен қатар, дербес деректер үшін айнымалыларды қамтитын құжат жасау, электрондық поштамен тарату үшін хат үлгісін дайындау және дайын файлдар үшін Дискте қалта құру қажет.

Файлдарды құру

Файлдарды құру үшін көрсетілген деректермен төменде
https://dimaker.app/api/v1/create/
мекен-жайына POST-DATA, POST-JSON немесе GET сұранымдарын жіберу қажет. Сұранымдарды кодтау - UTF-8. Міндетті өрістер жұлдызшамен белгіленген.

• secure*

  Токен (жол, 36 таңба)

• doc_id*

  Файлды құру үшін пайдаланылатын құжаттың ID (жол, 36 таңба). Құжат ашық болған кезде құжаттың ID-сін мекен-жай жолында алуға болады. Құжат себетте болмауы тиіс, бірақ құжаттардағы кез келген қалтада болуы мүмкін.

• mask*

  Айнымалыларды ауыстыру үшін барлық айнымалыларды қамтитын JSON-жол (айнымалы) - мән (ауыстыру үшін мәтін). Бірнеше файлдарды құру үшін деректерді қамтуы мүмкін (сан шектелмеген).
  Бір файл үшін мысал:
  [{"%name": "Иванов", "%баллы":"100"}]
  Бірнеше файлдар үшін мысал:
  [{"%name": "Иванов", "%баллы":"100"}, {"%name": "Петров", "%баллы":"200"}, {"%name": "Сидоров", "%баллы":"300"}]
  Электрондық пошта мекен-жайын көрсету үшін %email, ал файлдың атын көрсету үшін %filename қолдану қажет. Бірнеше электрондық пошта мекен-жайына дайын файлдарды жіберу үшін оларды үтір арқылы көрсету қажет. Мұнда жіберу күйі Дисктегі тек бірінші мекен-жай бойынша көрсетіледі.
  Стандартқа сәйкес тырнақша белгісін ғана пайдалануға болады. Егер мән кілтінде тырнақша белгісі болса, олар шегерілмелі болуы керек.

  Сурет блогына сурет беру үшін http:// немесе https:// тікелей сілтемесін немесе Base64 кодталған суретті пайдалануға болады. Екінші жағдайда жол "data:image/" деген сөзден басталуы керек.

  Балама әдіс
  Егер JSON-жолын жіберу мүмкіндігі болмаса, ауыстыру жолдары сұраныс өрістері ретінде жіберілуі мүмкін. Ауыстыру айнымалысы префикспен mask_ басталу керек, мысалы mask_name және ауыстыру мәнін қамту керек. Мұнда құжатта префикстен кейінгі айнымалды іздеу орындалады. Мысалы, mask_name өрісінің айнымалысы %name сәйкес келеді. Электрондық пошта мекен-жайын көрсету үшін бұл жағдайда mask_email, ал файл атын көрсету үшін - mask_filename қолдану керек.

• mail_id

  Электрондық поштамен жіберу үшін хат үлгісінің ID (жол, 36 таңба). Үлгі ашық болған кезде мекен-жай жолында ID ала аласыз. Егер айнымалы берілмесе, онда хат жіберілмейді.

• email_send

  Файлмен хатты жіберу уақыты. Келесі мәндерге ие болуы мүмкін:
  onfinish - Барлық файлдарды жасағаннан кейін барлық хаттарды жіберу (әдепкі бойынша)
  oncreate - Файлды жасаудан кейін электрондық поштаны бірнеше сәттен кейін жіберіңіз. Бір файл жасаған кезде onfinish және oncreate бірдей.
  timeout - Белгіленген уақытта хаттарды тарату. Бұл жағдайда екі параметрді қосымша беру қажет:
  email_timeout_value - хаттарды жіберу уақыт ұзақтығының сандық мәні, бүтін сан
  email_timeout_unit - уақыт өлшем бірлігі. "m" (минут), "h" (сағат), "d" (күн) мәніне ие болуы мүмкін.
  Немесе нақты жіберу уақытын көрсету үшін, сізге unix уақыт форматында email_timeout_timestamp параметріне уақыт жіберуіңіз керек. Егер email_timeout_value және email_timeout_timestamp ұсынылса, соңғысы басты болады.

• folder_id

  Файлдарды Дискте сақтайтын папканың ID (жол, 36 таңба). Егер папка жоқ болса, онда ол бірінші файлды жасаған кезде автоматты түрде жасалатын болады.

• storage_period

  Дисктегі файлдарды сақтау мерзімі. Егер параметр көрсетілмеген болса, файлдар мәңгілікке, қолмен өшірілгенге дейін сақталады. Белгіленген уақыт аралығында жою үшін мыналарды көрсетуі қажет:
  timeout. Бұл жағдайда қосымша екі параметр білу қажеттігі болады:
     storage_period_timeout_value - файлдарды жою уақыт мерзімінің сандық мәні, бүтін сан
     storage_period_timeout_unit - уақыт өлшем бірлігі. "m" (минут), "h" (сағат), "d" (күн) мәніне ие болуы мүмкін.
  Немесе нақты жою уақытын көрсету үшін unix уақыт форматындағы storage_period_timeout_timestamp уақытын көрсету қажет. Егер storage_period_timeout_value және email_timeout_timestamp берілсе, соңғысы бастысы болады.

• page_id

  Құжатта бірнеше парақтар бар болса, парақтың (сан немесе жол) реттік нөмірі берілуі керек. Бір нөмір (алғашқы парақ - 0) немесе файлды жасау үшін пайдаланылатын парақтардың нөмірлерін (үтір арқылы) беруге болады.

• result

  Нәтиженің қай формада қайтарылатынын анықтайды. Мынадай мәндерді қабылдауы мүмкін:

  • Мән жоқ. Сұраным нәтижесімен JSON-жол қайтарылады (төменде қараңыз)
  • link. Сәтті сұраным болса, бірінші жасалған файлдың сілтемесін қамтитын жол қайтарылады. Нақты файлды алу үшін көрсетілген сілтеме бойынша өту қажет. Файлдарды даярлау уақыты - әр файл үшін 1-5 секунд арасында. Файл жасалғанға дейін осы мекен-жай бойынша сұраным 404 қатесін береді. Егер сұраным файл жасаудың нәтижесі болмаған жағдайда, қате аймағын қамтитын JSON-жол қайтарылады (төменде қараңыз).
  • file. Егер сұраным сәтті болса, онда дайын файлдың өзі қайтарылады (егер сұранымда бірнеше файл жасалған болса, тек бірінші ғана қайтарылады). Файл жасау 1-5 секунд уақытты алады, сондықтан файл жасалғаннан кейін ғана қайтару процесі іске қосылады. Егер API-ға сұранымдар саны көбеюі, онда файлдардың жасалу уақыты артады. Егер файл 30 секунд ішінде даярланбақ болса, онда API 404 қайтады (бірақ файлды жасау сұранымы нәтижесінде дайындалады). Есте сақтаңыз, егер API сұранымдары 5 секундта бір реттен жиі болса, бұл параметрді қолдану ұсынылмайды.

Нәтиже

Нәтижеде сервер сұраным нәтижелерінің келесі мүмкін мәндерін беретін JSON-жолды қайтарады:

• result

  Сұраным нәтижесі. Келесі мәндерге ие болуы мүмкін:
  error - сұранымда қате. Файлдар жасалмады.
  success - файлдарды жасаудағы сәтті сұраным. API қолдану сценарийіне байланысты файлдардың сәтті жасалғаны туралы ақпаратты немесе файлды алу формасын көрсетуге болады.

• create_id

  Жасау идентификаторы. Тек сәтті сұранымда ғана болады. Басқа API сұранымдар үшін пайдалы болуы мүмкін.

• files

  Жасалған файлдардың ID-ын қамтитын массив. Тек сәтті сұранымда ғана. Файлдың өзін JPG форматында алу үшін https://dimaker.app/getfile/{ID}/ мекен-жайына өту керек. PDF файлы қажет болса, pdf/ мекен-жайына қосу керек. API файл ID-ын сол кезде береді, алайда файлдарды даярлау уақыты - әрбір файлға 1-5 секунд. Файл жасалғанға дейін https://dimaker.app/getfile/{ID}/ мекен-жайына сұраным 404 қате береді.

• url

  Файлдарды жүктеу виджетінің URL мекен-жайы. Тек сәтті сұранымда беріледі. Көрсетілген URL-мен Iframe құру қажет. URL-ға жай өтудің ешқандай нәтижесі болмайды. Файл алынатын сайт домені API параметрлерінде дұрыс көрсетілуі керек.
  Әр файл жасау 1 секунд уақытты алады, әсіресе топтағы барлық файлдар үшін тағы бірнеше секунд қажет болады. Сұраным жіберілгеннен кейін бірден көрсетілген URL-мен Iframe-ды ашуға болады. Егер файлдарды әзірлеу әлі аяқталмаса, сәйкесінше хабар беріліп көрсетіледі. Файлдар дайын болғаннан кейін оларды жүктеп алу мүмкіндігі беріледі.
  Сіз жүктеу виджетін парақ бетінде диалог терезесінде көрсетуге болады. Бұл үшін келесі қосымша стильдерді пайдаланғыңыз келетін Iframe жасаңыз: position:fixed; width:100%; height:100%; top:0; bottom:0; right:0; left:0; z-index:10000; background: rgb(0 0 0 / 72%); Адрес жолына ?view=modal қосу қажет. Бұл iframe-ды body-ге орналастырыңыз.

• error_text

  Тек қате жағдайында. Қате мәтіндік сипаттамасы. Мүмкін болатын қателер: күмәнсіз Secure токен, ауыстыру маскасы, құжаттың ID, хат үлгісінің ID, Дисктегі қалта ID, не болмаса ішкі серверлік қате.

Сәтті сұранымда қайтарылатын деректердің үлгісі:
{
"result":"success",
"create_id":"b4caf05b-6757-4d9c-b4bc-1924a9b31796",
"url":"https://embed.dimaker.app/widgets/get/927ebf68-2f55-4b20-a18c-c1171ee113db/b4caf05b-6757-4d9c-b4bc-1924a9b31796/",
"files":[
"369dc61e-40c2-46c0-81f4-e31ca8c33cc2",
"d94c6efb-0076-438b-bb84-fead9c1ae556",
"716e1081-c8ee-442b-b0b0-0681b2ed5d90"
]
}

Бір сұранымда бірнеше файлды жасау

Бір сұранымда әртүрлі құжаттардан бірнеше файлдарды жасауға сұраным жіберуге болады. Мұндай сұраным арқылы, әртүрлі көңіл-күйді ескере отырып, қажетті файлдар санын жасауға болады, мысалы, орыс және ағылшын тілді үлгілерді пайдалану. Бір сұраным жіберілгеннен кейін, сервер қажетті файлдар санын жасайды.

Мұндай сұранымды жіберу үшін, айнымалы doc_id массив болуы керек (айнымалының аты - doc_id[]). Мұндай жағдайда бір сұранымда бірнеше doc_id[] айнымалылары болуы мүмкін - бірнеше файлдарды жасау үшін. Басқа айнымалылар, мысалы, mail_id, email_send, folder_id де массив түрінде жіберілуі мүмкін, осылайша әрбір файл белгілі уақытқа жіберіліп, белгілі қалтаға сақталады. Егер мұндай қажеттілік болмаса, онда массив тек doc_id өрісінде болуы керек.

Мысалы, екі файлды әртүрлі құжаттардан жасай отырып, оларды Дисктегі әртүрлі қалталарға қою керек болса. Ол үшін doc_id[] екі айнымалылары және үшінші параметрі email_send[], біріншіден "manual", содан кейін "oncreate" көрсететін түрде өткізу керек. Осылайша, бір файл жасалады, содан кейін екінші. mail_id хатымен көрсетілгеннен кейін ғана жөнелту жүреді.

Өзіне файлды жіберу

Файл жасалған соң, ол аккаунтыңыздың электрондық поштасына автоматты түрде жіберіледі. «Хат шаблонын» өрісінде қай шаблонды қолданатынын таңдауға болады. Алдын ала Хат шаблондары бөлімінде аккаунт электрондық поштасына хат жіберу үшін бөлек шаблон жасауға болатын. Егер хатта %data айнымалыларын жазса, онда бұл аймаққа барлық файл деректері кесте түрінде қосылатын болады.

Файлдарды жою

Файлдарды жою үшін, төмендегі деректермен POST-DATA, POST-JSON немесе GET сұранымдары арқылы
https://dimaker.app/api/v1/drive/files/delete/
мекен-жайына сұранымдарды жіберу керек. Сұранымдарды кодтау - UTF-8. Міндетті өрістер жұлдызшамен белгіленген.

• secure*

  Токен (жол, 36 таңба)

• file_id

  Жойылатын файлдың ID (жол, 36 таңба). Файлдың ID API арқылы жасалған кезде files массивінде қайтарылады. Файл себетте болмауы керек.

  НЕМЕСЕ

• file_ids

  Бір сұранымда бірнеше файлды жою керек болса, жойылатын файлдардың ID массиві (жол, 36 таңба).

  НЕМЕСЕ

• creater_id

  API арқылы файлдар жасалған кезде, жасау идентификаторын ала аласыз (жол, 36 таңба). Ол файлдың ID немесе file_ids орнына өткізуге болады. Бұл жағдайда осы жасау идентификаторымен барлық файлдар жойылады. API арқылы жасалған кезде create_id өрісінде жасау идентификаторы беріледі.

  delete_forever

  Файлды себетке жылжытпай, түпкілікті жою керек пе. Әдепкіде файл себетке жылжиды. Мәндерге ие болуы мүмкін:

  • 0 - себетке көшіру (әдепкіде)
  • 1 - түпкілікті жою

  Себетке жылжытылғаннан кейін файлдар автоматты түрде 60 күннен кейін жойылады.

Үлгі

Файлдарды жою үшін дұрыс сұранымның үлгісі:
{
"secure":"b4caf05b-6757-4d9c-b4bc-1924a9b31796",
"file_id":"369dc61e-40c2-46c0-81f4-e31ca8c33cc2"
}

Нәтиже

Нәтижеде сервер сұраным нәтижелерінің келесі мүмкін мәндерін беретін JSON-жолды қайтарады:

• result

  Сұраным нәтижесі. Келесі мәндерге ие болуы мүмкін:
  error - сұранымда қате. Файлдар жойылды.
  success - файлдарды жоюдағы сәтті сұраным.

• files

  Жойылған файлдардың ID-ын қамтитын массив. Тек сәтті сұранымда ғана.

• error_text

  Тек қате жағдайында. Қате мәтіндік сипаттамасы. Мүмкін болатын қателер: күмәнсіз Secure токен, файлдың ID, жасау идентификаторы, не болмаса ішкі серверлік қате.

Сәтті сұранымда қайтарылатын деректердің үлгісі:
{
"result":"success",
"files":["369dc61e-40c2-46c0-81f4-e31ca8c33cc2"]
}

Басқа интеграциялар