API inteqrasiyası üçün tələblər sənədi: şablon və checklist

Qısa cavab

API inteqrasiyası üçün tələblər sənədi iki tərəfin — biznesin və texniki komandanın, və ya şirkətin və provayderin — eyni şeyi qurduğuna əmin olmaq üçün yazılır. Yaxşı sənəd on iki bölmədən ibarətdir: məqsəd və əhatə, biznes ssenariləri, sistemlər və sahiblər, data, interfeyslər, autentifikasiya və təhlükəsizlik, həcm və sürət tələbləri, xətalar və təkrar cəhdlər, jurnal və audit, test və qəbul meyarları, işə salma və geri çəkilmə, əlaqə və dəstək. Sənəd uzun olmaq məcburiyyətində deyil — 6–10 səhifə kifayətdir — amma hər bölmədə bir qərar yazılmalıdır, ümumi niyyət yox.

Sənədsiz inteqrasiya niyə uzanır

Sənəd olmadan inteqrasiya çox vaxt belə gedir: biznes «lead-lər CRM-ə düşsün» deyir, developer bir gündə webhook qurur, test zamanı məlum olur ki, satış komandası statusların da geri gəlməsini gözləyirdi, IT təhlükəsizlik şöbəsi isə açarların harada saxlandığını soruşur. Hər yeni sual bir həftə əlavə edir və sonda heç kim layihənin nə vaxt «bitdiyini» deyə bilmir, çünki qəbul meyarı yazılmayıb.

Tələblər sənədi bu sualları kod yazılmazdan əvvəl verdirir və hər iki tərəfin imzası ilə bağlayır.

On iki bölmə

1. 11. Məqsəd və əhatəNə üçün, hansı nəticə gözlənilir və nə bu layihəyə daxil deyil.
2. 22. Biznes ssenariləri«Müştəri WhatsApp-da nömrə yazır → lead CRM-də yaranır → menecerə təyin olunur.»
3. 33. Sistemlər və sahiblərHər sistem, onun texniki və biznes sahibi.
4. 44. DataObyektlər, sahələr, formatlar və sahə xəritəsinə istinad.
5. 55. İnterfeyslərEndpoint-lər, metodlar, hadisələr, nümunə sorğu və cavab.
6. 66. Autentifikasiya və təhlükəsizlikAçar növü, saxlanma yeri, yenilənmə, IP məhdudiyyəti, səlahiyyət həddi.
7. 77. Həcm və sürətGündəlik sorğu sayı, pik, gözlənilən cavab müddəti, rate limit.
8. 88. Xətalar və təkrar cəhdlərHansı xəta nə deməkdir, nə vaxt təkrar cəhd edilir, kim xəbər alır.
9. 99. Jurnal və auditNə yazılır, nə qədər saxlanılır, kim baxa bilər.
10. 1010. Test və qəbulTest mühiti, test ssenariləri, «hazırdır» meyarları.
11. 1111. İşə salma və geri çəkilməMərhələlər, keçid tarixi, problem olanda necə dayandırılır.
12. 1212. Əlaqə və dəstəkKimə yazmaq, cavab müddəti, növbətçilik.

Biznes ssenarisini necə yazmaq

Ssenari texniki dil olmadan, addım-addım yazılır və hər addımda «kim» və «nə» aydın olur. Hər ssenari üçün üç variant yazın: normal hal, alternativ hal (məsələn, müştəri artıq CRM-də var) və xəta halı (CRM cavab vermir). Xəta halı ən çox unudulan və sonra ən çox problem yaradan variantdır.

İnterfeys bölməsi: nümunə vacibdir

Endpoint-in adını yazmaq kifayət deyil. Hər interfeys üçün real (anonimləşdirilmiş) nümunə sorğu və cavab əlavə edin: hansı sahələr göndərilir, hansılar məcburidir, cavab hansı formatdadır, xəta necə görünür. Nümunəsiz sənəd iki komandanın eyni sözü fərqli başa düşməsinə aparır. Sahələrin özünün xəritəsini ayrıca sənəddə saxlayın — formatını CRM data mapping checklisti yazısında göstərmişik.

Təhlükəsizlik bölməsi

• Açar və ya token: harada saxlanılır (kodda yox), kim görür, nə qədər müddətdən bir yenilənir.
• Ən az səlahiyyət: inteqrasiya istifadəçisi yalnız lazım olan obyektlərə və əməliyyatlara girişə malikdir.
• Şəbəkə: IP məhdudiyyəti, yalnız HTTPS.
• Şəxsi məlumat: hansı sahələr ötürülür və niyə lazımdır; lazım olmayan göndərilmir.
• AI aləti çağırırsa: hansı URL-lərə müraciət edə bilər, nəyi dəyişə bilər.

Həcm, sürət və limitlər

Gündəlik sorğu sayını, pik saatını və kampaniya günlərindəki artımı yazın. Qarşı tərəfin API limitlərini də yazın: dəqiqədə neçə sorğu qəbul edir, aşanda nə baş verir. Bu bölmə olmadan inteqrasiya testdə işləyir, ilk kampaniya günü isə limitə dirənir və lead-lər növbədə qalır.

Test və qəbul

1. 1Test mühitiCanlı data olmadan, real quruluşla.
2. 2Ssenari siyahısıHər biznes ssenarisinin normal, alternativ və xəta variantı.
3. 3Qəbul meyarlarıÖlçülə bilən: müddət, nəticə, xəta halında davranış.
4. 4İmzaBiznes sahibi və texniki sahib qəbulu yazılı təsdiqləyir.

Doldurulmuş nümunə: bir ssenari

Bu, illüstrativ nümunədir. Ssenari: «Müştəri çatda sifariş statusunu soruşur.» Normal hal: AI sifariş nömrəsini soruşur, sifariş sisteminin oxuma endpoint-ini çağırır və statusu müştəriyə deyir. Alternativ hal: nömrə tapılmır — AI nömrəni yenidən yoxlamağı xahiş edir, ikinci uğursuzluqda operatora ötürür. Xəta halı: API 5 saniyədə cavab vermir — AI müştəriyə statusu indi yoxlaya bilmədiyini deyir və operatora bildiriş gedir. Qəbul meyarı: test mühitində 20 sorğunun hamısında gözlənilən davranış.

Tipik səhvlər

• Yalnız «xoşbəxt yol»u yazmaq — xəta halları yoxdur.
• Qəbul meyarı yazmamaq — layihə heç vaxt «bitmir».
• Açarların saxlanmasını sonraya saxlamaq.
• Həcm və limitləri yazmamaq.
• Sənədi bir dəfə yazıb dəyişiklikləri qeyd etməmək.

Məhdudiyyətlər

Tələblər sənədi hər sürprizin qarşısını almır: qarşı tərəfin API-si dəyişə, gözlənilməyən data formatı gələ bilər. Ona görə sənəd canlı saxlanılmalı və dəyişikliklər tarixlə yazılmalıdır. Şəxsi məlumatın ötürülməsi və təhlükəsizlik tələbləri şirkətin öz siyasəti və yerli qanunvericilik ilə ayrıca yoxlanmalıdır.

Vexvon ilə inteqrasiyada

Vexvon ilə inteqrasiyada şirkət öz API-sini AI-yə alət kimi təqdim edir və nə vaxt çağırılacağını özü yazır — məsələn, «müştəri sifariş statusunu soruşanda»; alət çağırışlarında SSRF-ə qarşı qoruma var. Əks istiqamətdə yeni lead, tamamlanmış zəng və dəyişən status kimi hadisələr webhook ilə şirkətin sisteminə göndərilir. Kanallar rəsmi API ilə, parol paylaşmadan qoşulur. Böyük şirkətlər üçün təhlükəsizlik sorğu formasını doldurur və NDA imzalayırıq. Ətraflı: inteqrasiyalar və təhlükəsizlik.

Növbəti addım

On iki bölməni boş şablon kimi açın və biznes sahibi ilə birlikdə ilk iki bölməni — məqsəd və ssenariləri — doldurun. Qalanları texniki komanda bu iki bölmədən çıxaracaq. Ümumi anlayış üçün enterprise AI inteqrasiyası yazısına, çatbot arxitekturası üçün isə çatbot API və webhook inteqrasiyası yazısına baxın. Digər yazılar enterprise inteqrasiya bölməsindədir; sənədinizi demo zamanı birlikdə nəzərdən keçirə bilərik.