Серіктестерге арналған OAuth қосымшалар

Partner-меншігіндегі OAuth қолданбасы бірнеше Planfix есептік жазбаларын байланыстыратын интеграцияға арналған. Барлық клиенттік есептік жазбалар үшін бірдей қолданба тіркелгі деректері пайдаланылады, алайда әрбір есептік жазба қабылдауды бөлек бақылайды және әрбір пайдаланушы өз атынан қосылуға келісім береді.

Егер интеграция тек бір есептік жазбаға арналған болса, account-owned application жасау оңайырақ.

Қолданбаны құру

Өз partner есептік жазбаңызды ашыңыз.
OAuth applications бөліміне өтіңіз.
Create application таңдаңыз.
Пайдаланушылар мен әкімшілер көретін атау мен сипаттаманы енгізіңіз.
OAuth клиент түрін таңдаңыз.
Redirect URI-ларды қосыңыз.
REST API үшін ең аз қажетті рұқсаттарды (scopes) таңдаңыз.
Қолданбаны сақтап, оның тіркелгі деректерін көшіріп алыңыз.

Жаңа қолданба жеке болып табылады және оған қосылатын әрбір есептік жазбада нақты мақұлдау қажет.

OAuth клиент түрі

Type	Intended applications	Credentials
Public	Мобильді, десктоп және браузерлік қолданбалар, сонымен қатар жергілікті MCP клиенттері.	Тек бір `client_id`. Клиенттік құпия жоқ; PKCE S256 міндетті.
Confidential	Құпия сервер жағында сақталатын және клиент жағындағы кодта сақталмауы мүмкін қолданбалар.	`client_id` және `client_secret`.

OAuth клиент түрі қолданбаның жарияланған-жарияланбаған болуынан бөлек. Мысалы, жеке мобильді қолданба — құпиясы жоқ public OAuth клиенті.

Redirect URI-лар

Planfix пайдаланушыны жүйеге кіруден кейін қайтаруы мүмкін әрбір URL-ды көрсетіңіз.

Веб қызмет үшін https қолданыңыз.
http тек localhost және 127.0.0.1 сияқты loopback мекенжайлар үшін рұқсат етіледі.
Loopback мекенжайы үшін клиент динамикалық порт қолдана алады, бірақ схема, хост, жол және сұрау жолы дәл сәйкес болуы тиіс.
Wildcard-тар, URL фрагменттері немесе сіз бақыламайтын redirect URI-ларды қолданбаңыз.

Scopes

Scopes қолданбаның максималды рұқсаттарын анықтайды. Тек қана REST API scope list-тен қажетті рұқсаттарды сұраңыз.

Қолданба scopes-пері пайдаланушының қалыпты рұқсаттарын алмастырмайды. Scope берілген жағдайда да қолданба тек сол пайдаланушыға қолжетімді деректермен ғана жұмыс істей алады.

Redirect URI-ларды немесе scopes-ты өзгерткенде жаңа мақұлдау нұсқасы пайда болады. Бұрын қосылған есептік жазбалар жаңа нұсқаны қарап, мақұлдауы қажет, ал пайдаланушылар қайтадан қосылулары тиіс.

Клиент есептік жазбасын қосу

Жеке partner-меншігіндегі қолданба әрбір есептік жазбада әкімші тарапынан нақты мақұлдауды талап етеді.

Partner есептік жазбаңызда қолданбаны ашыңыз.
Approval link аймағына клиент есептік жазба атауын енгізіңіз.
Генерацияланған сілтемені көшіріп, сол есептік жазбаның әкімшісіне жіберіңіз.
Әкімшіден иесін, redirect URI-ларды және scopes-ты тексеріп, қолданбаны мақұлдауын сұраңыз.
Мақұлдаудан кейін есептік жазбадағы пайдаланушылар OAuth авторизациясын аяқтай алады. Әр пайдаланушы өз атынан бөлек келісім береді.

Бұл сілтеме Account management → API → OAuth and MCP applications бетін ашады және сұралатын қолданбаны көрсетеді.

Қосумен бірге әкімші қолданбаны таңдағанда Approve and connect опциясын таңдай алады.

Жеке және жария қолданбалар

Status	How it is admitted to an account
Private	Кез келген есептік жазбаның әкімшісінен әрдайым нақты мақұлдау талап етіледі.
Published	Егер есептік жазба саясаты Allow published applications болса, бөлек мақұлдау талап етілмейді. Ол әлі де Approved applications only саясаты кезінде мақұлдауды талап етуі мүмкін.

Публикация — Planfix тарапынан бөлек тексеріс. Қолданбаны жібермес бұрын айқын атау мен сипаттама, минималды scopes жиыны, жұмыс істейтін redirect URI-лар және интеграцияны қосу мен жою бойынша пайдаланушы құжаттамасын дайындаңыз. Публикация процедурасы туралы Planfix қолдау қызметімен хабарласыңыз.

Қосылу мекенжайлары

Глобал OAuth эндпойнттарын пайдаланыңыз:

Purpose	Address
Authorization	`https://auth.planfix.com/oauth/authorize`
Token	`https://auth.planfix.com/oauth/token`
Userinfo	`https://auth.planfix.com/oauth/userinfo`
MCP	`https://mcp.planfix.com/mcp`

Глобал URL-ға есептік жазба атауын қоспаңыз. Пайдаланушы есептік жазбаны Planfix бетіндегі таңдаудан таңдайды. Толық протокол, соның ішінде resource, PKCE, token refresh және revocation туралы мәлімет Қосымшалар үшін OAuth 2.0-те сипатталған.

Қолданбаны басқару

Partner төмендегі әрекеттерді орындай алады:

Атау мен сипаттаманы өңдеу;
Redirect URI-ларды және scopes-ты өзгерту;
Қолданбаны өшіру және қайта қосу;
Confidential қолданба үшін client secret-ті айналдыру (rotate);
Белгілі бір есептік жазба үшін қолданба мақұлдау сілтемесін генерациялау.

Secret-ті айналдырғаннан кейін ескі client secret дереу жұмыс істемейді. Secret-ті интеграция серверінде жаңартыңыз және оны пайдаланушыларға ешқашан жібермеңіз.

Қолданбаны өшіру OAuth авторизацияны және шығарылған токендерді барлық есептік жазбаларда бұғаттайды. Бұл әрекет қолданбаны пайдаланатын барлық клиенттерге әсер етеді.

Іске қосуға дейінгі ұсыныстар

Authorization Code with PKCE S256 қолданыңыз және state-ті тексеріңіз.
Тек қажет scopes-тарды сұраңыз.
Кіруден кейін пайдаланушыға таңдалған есептік жазбаны көрсетіңіз.
Refresh token айналдыруын (rotation) өңдеңіз: сәтті refresh-тен кейін алдыңғы refresh token жарамсыз болады.
Токендерді, авторизация кодтарын, code_verifier немесе client secret-терді журналдарға жазбаңыз.
Пайдаланушылар интеграциядан қалай ажыратуға және деректерін жоюды қалай сұрауға болатынын құжаттаңыз.
Мақұлдау кері қайтару, қолданбаны өшіру және қайта қосу сценарийлерін тексеріңіз.