Аутентификация және API кілттері

Жария тексеру шақыруларына тіркелгі қажет емес. https://app.tanba-ooh.kz/api/v1 астындағы барлығына API кілті немесе консоль сеансы керек.

Кілт жасау

Оператор немесе уәкілетті орган ұйымының әкімшісі консольде «Интеграциялар» бөлімін ашып, кілт жасайды. Құпия мән мына түрде болады

tnbk_<prefix>_<secret>

және бір рет қана көрсетіледі. Платформа оның тек хэшін сақтайды, сондықтан жоғалған кілтті қалпына келтіру мүмкін емес: оны кері қайтарып, жаңасын жасаңыз.

Кілтті жіберу

curl -H 'Authorization: Bearer tnbk_EXAMPLE_secret' https://app.tanba-ooh.kz/api/v1/structures?limit=10

Дәл осы маршруттар консоль сеансының cookie файлымен де жұмыс істейді. Деректерді өзгертетін шақыру онда X-Tanba-CSRF тақырыбын да алып жүруі тиіс.

Рұқсаттар

Рұқсат	Не мүмкіндік береді
`read:approvals`	Келісулер, олардың манифестері, медиа және конверттері, CSV түріндегі келісулер
`read:structures`	Құрылымдар және олардың CSV экспорты
`read:stats`	Операциялық есеп және оның CSV бөлімдері
`read:billing`	Есептеу кезеңдері, ақша есебі және оның CSV бөлімдері
`read:creatives`	Жарнамалық материалдарды хеш бойынша тексеру
`read:inventory`	Нарық экрандары, рұқсат етілген сатушылар және OpenRTB фрагменттері
`write:submissions`	Өтінім жасау және оның медиасын жүктеу, басқа ештеңе емес
`write:plays`	Өз CMS жүйеңізден көрсетілімдерді жіберу; тек оператор әкімшілері үшін. Жарнама платформаларының әкімшілері онымен көрсетілген көрсетілімдер өтінімдерін жібереді және олардың тексеруін оқиды
`relay:commands`	CMS орнатымының қол қойылған командаларын алу және растау; тек оператор әкімшілері үшін

Әр операция бетінде оған қандай рұқсат қажет екені көрсетілген.

Кілт ешқашан не істей алмайды

Кілт тек оны жасаған адамда бар рұқсаттарды ұстай алады және әр шақыруда сол адамның ұйымдағы ағымдағы құқықтарымен әрекет етеді. Адам лауазымынан төмендетілсе немесе кетсе, кілт тарылады немесе тоқтайды.
Кілт кілттерді басқаруға, вебхуктерді басқаруға, пайдаланушыларды басқаруға, модерацияға немесе келісу шешімдеріне ешқашан жете алмайды. Бұлар консольдегі адамдарда қалады.
Кілттер рөлдерді емес, рұқсаттарды ұстайды. API-дегі ештеңе рөл бермейді.

Қателер

Статус	`code`	Мағынасы
401	`invalid_api_key`	Кілт белгісіз, кері қайтарылған немесе дұрыс емес пішімде
401	`unauthenticated`, `session_expired`	Жарамды сеанс жоқ
403	`key_scope_denied`	Кілтте бұл шақыруға қажет рұқсат жоқ
403	`key_route_denied`	Бұл маршрутты ешбір кілт шақыра алмайды
429	`rate_limited`	Сұрау тым көп; `Retry-After` күтіңіз

Кілт жасау, оны кері қайтару және жарамды кілттің әрбір қабылданбаған шақыруы ұйымыңыздың аудит журналына жазылады.