API техникалык деталь эмес, продукт функциясы

Ачык REST четке кагылган жалпы тапшырма кыймылдаткычын алмаштырат. Ага кошулуу канчалык арзан болсо, продукттар аркылуу өтүүчү жалпы жумуш тизмеси ошончолук чыныгы болот.

Келишимге эмне салынган

Жол боюнча версиялоо

Бардык контроллер /api/v1 астында жайгашкан. Бузуучу өзгөрүү өтмө мезгилде мурунку версиянын колдоосун талап кылат, эски жолдор эки чыгарылым бою алиас бойдон калат.

Жазуунун идемпоттуулугу

Жазуу операциялары идемпоттуулук ачкычын кабыл алат. Тармак үзүлгөндөгү кайталанган чакырык экинчисин түзбөй, жазууну жаңыртат. Мындай интеграциялардагы эң көп кездешкен ката ушул.

Укуктар интерфейстегидей

A3.ID аркылуу аутентификация, кирүү текшерүүлөрү интерфейстегидей эле. Тышкы катышуучуга экономикалык талаалар кардарда жашырылбайт, таптакыр берилбейт.

Экосистема үчүн өзүнчө чектөө

Интеграциялык трафик табияты боюнча чокулуу, кардардык трафик бир калыпта. Экөөнө бир чектөө коюу же интеграцияларды муунтмак, же кыянаттыктан коргой албай калмак.

Метод топтору

GET/api/v1/tasksБарактоосу, чыпкалары жана иргөөсү бар тапшырмалар тизмеси
POST/api/v1/tasksТапшырма түзүү, статус алмаштыруу, дайындоо, топтук операциялар
POST/api/v1/assignmentsИдемпоттуулук ачкычы бар тышкы тапшырма
PUT/api/v1/assignments/{key}Тышкы ачкыч боюнча жаңыртуу жана жабуу
GET/api/v1/projectsДолбоорлор, катышуучулар, чектер жана бюджет
POST/api/v1/time-entriesУбакыт жазуу, окуу жана бекитүү
GET/api/v1/views/overdueДаяр кесиндилер: менин тапшырмаларым, мөөнөтү өткөндөр, долбоор боюнча
POST/api/v1/exportЧакыруучунун укугу менен уюмдун маалыматын чыгаруу

Тышкы тапшырма

Продукт-булак өз объектисин жана ага шилтемени берет. Ошол эле externalKey менен кайталанган чакырык экинчисин түзбөй, тапшырманы жаңыртат.

POST /api/v1/assignments

{
  "externalKey": "legal-case-8421",
  "sourceProduct": "lawyer",
  "sourceEntityType": "LegalCase",
  "sourceEntityId": "8421",
  "deepLink": "https://app.lawyer.a3.solutions/cases/8421",
  "title": "Подготовить исковое заявление",
  "assigneeId": "u-2f9c",
  "dueDate": "2026-10-02"
}

Вебхуктар

Продукт-булак A3.Projects-ти график боюнча сурамжылабашы үчүн окуяларга жазылуу.

task.createdТапшырма интерфейсте же API аркылуу түзүлдү

task.status_changedТапшырма абалын алмаштырды, кайра иштөөгө кайтарууну кошо

task.closedТапшырма аяктады же себеби көрсөтүлүп жокко чыгарылды

time_entry.loggedУбакыт жазылды, киргизилген виджет аркылуу да

project.status_changedДолбоор токтотулду, аяктады же жокко чыгарылды

budget.threshold_reachedБюджеттин чегине жетти, ар бир чекке бир жолу иштейт

Жеке кирүү токендери

Токен конкреттүү интеграцияга түзүлөт жана ээсинин укугунан кеңири эмес ачык тизме менен чектелет. Базада хеш гана сакталат, жарактуулук мөөнөтү 180 күндөн ашпайт.

Аймактар толугу менен эмес, ачык тизме менен чектелген
Базада SHA-256 гана, токенди кайра көрсөтүүгө болбойт
Жарактуулук мөөнөтү 180 күндөн ашпайт, узартуу жаңы токенди талап кылат
Токендер токендин өзү менен эмес, сессия аркылуу башкарылат

ИИ агентине кирүү

Ошол эле ачык API экосистеманын агентине MCP аркылуу кирүү чекити болот. Агент колдонуучунун атынан жана ошол эле кирүү текшерүүлөрү менен иштейт.

Укук боюнча четке кагуу бош тизме эмес, курал катасы болуп кайтат. Антпесе агент тапшырмалар жөн эле көрүнбөгөн жерде «сизде тапшырма жок» демек.

Келишим ачык

Схема, сурам мисалдары жана ката коддору жарыяланган. Кум куржуну биринчи эталондук интеграциядан кийин пайда болот: биринчи керектөөчүсүз ал ойдон чыгарылган сценарийге кызмат кылмак.

Кошулуу Интеграциялар