API бол техникийн нарийн ширийн биш, бүтээгдэхүүний чиг үүрэг

Нээлттэй REST татгалзсан нийтийн даалгаврын хөдөлгүүрийг орлоно. Түүнд холбогдох нь хэдий хямд байна, бүтээгдэхүүн дамжсан нэгдсэн ажлын жагсаалт төдий чинээ бодит болно.

Гэрээнд юу тавигдсан бэ

Замаар хувилбарлах

Бүх контроллер /api/v1 дор байрлана. Эвдэх өөрчлөлт шилжилтийн үед өмнөх хувилбарын дэмжлэгийг шаардана, хуучин замууд хоёр хувилбарын турш alias хэвээр үлдэнэ.

Бичилтийн идемпотент байдал

Бичих үйлдэл идемпотент түлхүүр хүлээн авна. Сүлжээ тасрахад давтан дуудлага хоёр дахийг үүсгэхгүй, бичлэгийг шинэчилнэ. Ийм интеграци дахь хамгийн түгээмэл алдаа нь энэ.

Эрх нь интерфэйсийнхтэй адил

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-ээр орох цэг болно. Агент хэрэглэгчийн нэрийн өмнөөс, яг тэр хандалтын шалгалттайгаар ажиллана.

Эрхээр татгалзах нь хоосон жагсаалт биш, хэрэгслийн алдаа болж буцна. Эс бөгөөс агент даалгавар зүгээр харагдахгүй байгаа газар «танд даалгавар байхгүй» гэх байсан.

Гэрээ нээлттэй

Схем, хүсэлтийн жишээ, алдааны код нийтлэгдсэн. Туршилтын орчин эхний жишиг интеграцийн дараа гарна: эхний хэрэглэгчгүйгээр энэ нь зохиомол хувилбарт үйлчлэх байсан.

Холбогдох Интеграц