Перейти к основному содержанию
Вебхук API-ді қайта-қайта сұраудан құтқарады: ұйымда бірдеңе болғанда Tungo серверіңіздің мекенжайына JSON бар POST-сұрауды өзі жібереді. Сіз мекенжайды қосасыз, оқиғаларды таңдайсыз және әр сұраудың қолтаңбасын тексеретін құпияны аласыз. Мекенжайларды ұйымның иесі немесе әкімшісі платформа экрандарында қосады. Мұны API арқылы webhooks.manage құқығы бар кілтпен де жасауға болады, ол құқық тек барлық компанияға арналған кілтте бар. Вебхуктарды автоматтандырулардың кіріс хуктарымен шатастырмаңыз. Вебхук — Tungo-дан сізге келетін оқиға. Кіріс хук — сіздің жүйеңізден Tungo-ға келіп, сценарийді іске қосатын оқиға: Автоматтандыру деген не бетін қараңыз.

Мекенжай қосу

1

«Вебхуктар» бөлімін ашыңыз

Кабинет мәзірінде Платформа сілтемесін басыңыз, Вебхуктар бөлімін таңдап, Мекенжай қосу батырмасын басыңыз.
2

Сервердің мекенжайын көрсетіңіз

Тек https:// деп басталатын және интернеттен қолжетімді мекенжай жарайды. Ішкі желі мекенжайларын Tungo қабылдамайды.
3

Оқиғаларды таңдаңыз

Осы мекенжайға керек оқиғаларды белгілеңіз. Ештеңе таңдамасаңыз, бәрі келеді.
4

Қолтаңба құпиясын көшіріп алыңыз

Қосылғаннан кейін экран whsec_… түріндегі құпияны көрсетеді. Оны өз серверіңізде құпиясөз сияқты сақтаңыз.
Сол мекенжайды API арқылы қосу:
Жауапта мекенжайдың id мәні мен secret келеді. Кілтпен құпияны енді еш жерден оқи алмайсыз, оны тек ауыстыруға болады. Кабинетте құпияны кейін де көруге болады: мекенжай мәзірі, Құпияны көрсету тармағы.

Қандай оқиғалар болады

Оқиға атаулары event_types өрісінде беріледі және type өрісінде келеді.
  • 1С үшін құжаттар: proposal.awaiting_approval, proposal.written, proposal.failed, proposal.rejected.
  • ЖИ-бухгалтердің кілт бойынша жауаптары: chat.turn.completed.
  • Үзінділер мен ЭШФ-ларды талдау: bank_statement.received, esf.incoming.received, batch.completed, batch.failed.
  • Автоматтандырулар: automation.run.completed, automation.run.failed, automation.run.notice, automation.write_unknown.
  • Платформа балансы: platform.balance_low, platform.balance_exhausted, platform.cap_threshold_reached.
  • Кілттер: api_key.expiring, api_key.cap_reached.
  • Төлем және 1С-пен байланыс: payment.succeeded, payment.failed, onec.connection.changed.
Барлық оқиғаның денесі бірдей құрылған:
data ішінде тек id-лер, тиынмен берілген сомалар, күйлер және уақыт жатады. Аттар, деректемелер және құжаттардың мәтіні онда жоқ. Толық мәліметті оқиғадағы id бойынша API-ден алыңыз. Әр оқиғаның data өрістері API анықтамасында және «Вебхуктар» бөлімінің «Оқиға түрлері» қойындысында сипатталған. Мекенжайға қосымша channels — сценарий id-лерінің тізімін де беруге болады. Сонда оған тек осы сценарийлердің оқиғалары келеді, мысалы бір сценарийдің қорытындысы өз жүйеңізге. Бұл өріс тек API арқылы қолжетімді.

Сынақ оқиғасын жіберу

Мекенжай мәзірінен Тексеру жіберілімі тармағын таңдаңыз. Мекенжайға түрі ping, ал data өрісі бос оқиға жіберіледі. Оған нақты оқиғалар сияқты қол қойылған, сондықтан сол арқылы қабылдауды да, қолтаңбаны да тексеру ыңғайлы. Нәтижені Жеткізу әрекеттері тармағынан қараңыз: онда серверіңіздің не деп жауап бергені көрінеді. API арқылы сынақ оқиғасын POST /v1/workspaces/{ws}/webhooks/endpoints/{id}/test жібереді.

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

Әр сұрау үш тақырыппен келеді: webhook-id, webhook-timestamp және webhook-signature. Оқиғамен бірдеңе істемес бұрын қолтаңбаны тексеріңіз. Әйтпесе мекенжайды білген кез келген адам сізге жалған оқиға жібере алады. Қол нүктемен бөлінген үш бөліктен тұратын жолға қойылады: webhook-id, webhook-timestamp және сұраудың денесі. Дене дәл келген күйінде, JSON талдауына дейін алынады. Қолтаңба кілті — құпияның whsec_ бөлігінен кейінгі, base64-тен кері кодталған бөлігі. Қолтаңба HMAC-SHA256 ретінде есептеледі және base64 түрінде кодталады.
Қолтаңба сәйкес келмесе, 400 деп жауап беріңіз және ештеңе істемеңіз. Қолтаңба Standard Webhooks ашық келісіміне сай, сондықтан өз кодыңыздың орнына дайын кітапхананы алуға болады, мысалы npm-дегі standardwebhooks. Құпия мекенжай мәзіріндегі Құпияны қайта шығару тармағымен немесе POST …/endpoints/{id}/secret/rotate сұрауымен ауыстырылады. Ауыстырғаннан кейін тағы бір тәулік бойы Tungo тақырыпқа екі қолтаңба қояды: жаңа құпиямен және бұрынғы құпиямен. Жоғарыдағы мысалдағыдай «кем дегенде біреуі сәйкес келді» деп тексеретін қабылдағыш ауысудан оқиғаларды жоғалтпай өтеді.

Қайталаулар мен қосарланған оқиғалар

Серверіңіз 30 секунд ішінде кез келген 2xx кодымен жауап берсе, жеткізу сәтті деп есептеледі. Сондықтан бірден жауап беріңіз, ал ұзақ өңдеуді жауаптан кейін жасаңыз. Жауап жоқ болса немесе ол басқа болса, Tungo жіберуді қайталайды: 5 секундтан, 5 минуттан, 30 минуттан, 2 сағаттан, 5 сағаттан кейін, содан соң алты рет 10 сағат сайын және тағы бір рет 5 сағаттан кейін. Барлығы шамамен үш тәулік ішінде 13 әрекет болады. Одан кейін оқиғаны қолмен жіберуге болады: «Оқиғалар» қойындысы, Қайта жіберу тармағы. Қайталаулардың кесірінен бір оқиға екі рет келуі мүмкін. Қайталанған оқиғаның денесіндегі id сол күйінде болады, қосарланғандарды сол бойынша алып тастаңыз. Рет те кепілдендірілмейді: оқиғалар болған ретімен келмеуі мүмкін. created_at мәнін салыстырыңыз, ал өзекті күйді API арқылы оқыңыз.

Мекенжай жауап бермесе

Бес тәулік қатарынан бірде-бір оқиға қабылдамаған мекенжайды Tungo өзі өшіреді. Тізімде оның күйі «Өшірулі» болады, оған жаңа оқиғалар жіберілмейді. Қабылдағышты жөндеп, мекенжайды қосыңыз: мекенжай мәзірі, Қосу тармағы немесе "enabled": true бар PATCH сұрауы. Мекенжай өшірулі тұрғанда болған оқиғалар өздігінен келеді деп үміттенбеңіз. Жіберіп алғаныңызды API арқылы қалпына келтіріңіз: осы кезеңдегі құжаттар кезегін, автоматтандырулардың іске қосуларын немесе шығынды оқыңыз.

Әрі қарай