Broker API inteqrasiyasının hazırlanması yalnız brokerdən sorğu ilə balans və əməliyyatları çəkmək deyil. Etibarlı həll istifadəçi razılığını, tokenlərin təhlükəsiz idarəsini, hesab və alət identifikatorlarının xəritələnməsini, tarixi məlumatların mərhələli idxalını, real vaxt hadisələrini və broker mənbəyi ilə davamlı uzlaşdırmanı birlikdə layihələndirir. Bu yanaşma trading jurnalı, analitika paneli, əməliyyat iş axını və ya investor portalının broker məlumatına əsaslanaraq səhv və ya köhnəlmiş nəticə göstərməsi riskini azaldır.

Əsas qərar budur: məhsulunuz yalnız qiymət məlumatını göstərir, yoxsa istifadəçinin broker hesabını oxuyur və ya əmrlərlə işləyir? Market-data API adətən qiymətlər, şamlar, kotirovkalar və bəzən korporativ hadisələr verir. Brokerage API isə hesablar, nağd vəsait, mövqelər, orderlər, fill-lər, komissiyalar, transferlər və status dəyişiklikləri kimi istifadəçiyə məxsus əməliyyat məlumatına çıxış verir. İkinci kateqoriya daha həssas giriş, fərqli gecikmə və daha çox natamamlıq ssenarisi yaradır.

Broker bağlantısının məhsul sərhədini əvvəlcədən müəyyənləşdirin

İnteqrasiyanın əhatə dairəsini “brokeri qoşuruq” kimi deyil, konkret istifadəçi əməliyyatları kimi yazın. Məsələn, məhsul yeni hesabı bir dəfə qoşacaq, seçilmiş hesablar üzrə son 24 ayın əməliyyatlarını idxal edəcək, açıq mövqeləri gündəlik yeniləyəcək və yeni fill-ləri mümkün qədər tez göstərəcək. Əgər məhsul order göndərəcəksə, oxu və yazı icazələri, order təsdiqi və insident davranışı ayrıca layihələndirilməlidir.

  • Read-only analitika: hesab, mövqe, əməliyyat və fill məlumatlarının gətirilməsi.
  • Əməliyyat iş axını: order yaradılması, ləğvi, status izlənməsi və istifadəçiyə təsdiq ekranları.
  • Müştəri portalı: bir istifadəçiyə bağlı bir neçə hesabın ayrıca göstərilməsi və giriş hüquqlarının idarəsi.
  • Back-office: istisnaların növbəyə alınması, yenidən sinxronizasiya və audit qeydləri.

Məhsulun təhlükəsiz və dəstəklənə bilən arxitekturası üçün FinTech və trading sistemləri xidmətində API inteqrasiyası, məlumat modelləri və əməliyyat iş axınları vahid həll kimi planlaşdırıla bilər. Portal qatının rol və icazə tələbləri varsa, veb platformaların hazırlanması xidməti də inteqrasiyanın istifadəçi təcrübəsi hissəsini dəstəkləyir.

Autentifikasiya, razılıq və token yenilənməsi

Brokerlərin autentifikasiya modeli eyni olmur. Bəziləri server-to-server API açarlarından, bəziləri istifadəçinin broker səhifəsində verdiyi OAuth razılığından, digərləri isə institusional onboarding və imzalı sorğulardan istifadə edir. Məhsul komandası əvvəlcə brokerin hansı məlumatlara, hansı hesab növlərinə, hansı ölkə və istifadəçi kateqoriyalarına çıxış verdiyini təsdiqləməlidir.

İstifadəçi razılığı olan axında tətbiq brokerin giriş səhifəsinə yönləndirir, geri dönüşdə qısaömürlü authorization code alır və onu server tərəfində tokenə dəyişir. Brauzerə access token və refresh token qaytarılmamalı, tokenlər URL-də, mobil tətbiq loqlarında və analitika sistemlərində görünməməlidir. Redirect URI-ləri dəqiq qeydiyyatdan keçməli, state dəyəri istifadəçi sessiyasına bağlanmalı, dəstəklənirsə PKCE ilə authorization code flow istifadə edilməlidir.

Token saxlama qaydaları

  • Refresh tokenləri şifrələnmiş məlumat anbarında saxlayın; tətbiq loqlarına, support biletlərinə və browser storage-a yazmayın.
  • Tokeni konkret istifadəçi, broker connection və icazə dəsti ilə bağlayın. Bir tokenin hansı hesablara aid olduğu ayrıca metadata kimi izlənməlidir.
  • Yenilənmiş refresh token verilirsə, əvvəlkini atomik şəkildə əvəz edin. Köhnə tokeni aktiv saymaq paralel işçilərdə əlaqənin qırılmasına səbəb ola bilər.
  • Invalid grant, revoked consent və ya yenilənməyən token xətasını “yenidən qoşulma tələb olunur” statusuna çevirin; davamlı retry etməyin.
  • İstifadəçiyə qoşulmuş brokeri ayırmaq və saxlanılan tokenləri etibarsızlaşdırmaq imkanı verin.

Yazı icazəsi tələb edən trading execution API development işində “ən az səlahiyyət” prinsipi xüsusilə vacibdir: analitika üçün yalnız oxu icazəsi istəyin; order əməliyyatları üçün ayrıca, açıq razılıq və təsdiqlənən məhsul axını yaradın.

Hesab, simvol və zaman məlumatlarını kanonik modelə çevirin

Brokerdən gələn identifikatorları birbaşa məhsulunuzun əsas açarı kimi qəbul etməyin. Eyni istifadəçidə fərqli account ID, account number maskası, alt-hesab, valyuta, hüquqi sahiblik və trading icazələri ola bilər. Daxili modeldə dəyişməyən connection ID, broker account ID, hesab tipi, əsas valyuta və görünmə statusu saxlanmalıdır.

Eyni prinsip alətlərə aiddir. “AAPL”, “BTC/USD” və ya futures kontrakt adı ekran üçün kifayət edə bilər, lakin düzgün birləşdirmə üçün brokerin instrument ID-si, asset class, exchange/venue, quote currency, kontrakt ölçüsü və expiry kimi atributlar lazım ola bilər. Simvolun yenidən adlandırılması, fractional quantity, option contract və ya korporativ hadisə sadə ticker əsaslı uyğunlaşdırmanı poza bilər.

Hər maliyyə obyektinə iki vaxt damğası ayırın: brokerin bildirdiyi economic/effective time və sisteminizin məlumatı qəbul etdiyi observed time. UTC-də saxlanılan bu iki dəyər gec gələn hadisəni, yenidən göndərilən payload-u və gün sonu hesabat fərqini araşdırmağı xeyli asanlaşdırır.

Tarixi idxal və rate limit: sinxronizasiya işini idarə edin

İlk qoşulmada uzun tarixçə böyük həcm yarada bilər. API-nin səhifələmə üsulunu — cursor, page token, tarix intervalı və ya ardıcıl ID — dəqiqləşdirmədən import dizaynı təsdiqlənməməlidir. Cursor-u hər uğurlu səhifədən sonra checkpoint kimi saxlayın, səhifə emalını idempotent edin və yarımçıq importu eyni nöqtədən davam etdirin.

Tarixi əməliyyatları paralel və nəzarətsiz çəkmək broker limitlərini tez aşır. Sorğu büdcəsini connection və provider səviyyəsində idarə edin; limit başlıqlarını izləyin; 429 cavabında Retry-After və ya reset vaxtına üstünlük verin; eksponensial backoff-a jitter əlavə edin. Ən vacibi, real vaxt hadisələri ilə ağır backfill işlərini eyni prioritet növbəsində saxlamayın. Yeni fill və hesab dəyişiklikləri daha yüksək prioritet almalıdır.

Praktik import qaydası

  1. Əvvəl hesabların siyahısını və istifadəçinin seçimini gətirin.
  2. Son vəziyyət üçün açıq mövqeləri, cash və açıq orderləri ayrıca snapshot kimi alın.
  3. Tarixçəni kiçik zaman pəncərələri və davametmə checkpoint-ləri ilə yükləyin.
  4. Hər səhifəni raw payload, normalizə edilmiş yazılar və əlaqələndirmə açarları ilə saxlayın.
  5. İdxal tamamlandıqdan sonra snapshot və hesablanmış nəticələri müqayisə edin; fərq varsa istisna yaradın.

Webhook və order event processing: hadisə sürətli xəbərdir, yeganə həqiqət deyil

Bəzi brokerlər order, fill, cancellation, rejection, cash və ya non-trading activity dəyişikliklərini WebSocket, SSE və ya webhook vasitəsilə ötürür. Bu kanallar polling yükünü azaldır və yeni məlumatı tez çatdırır. Ancaq etibarlı dizaynda hadisə axını hint rolunu oynayır: hadisə gələndə lokal yazı yenilənir, amma periodik REST snapshot və ya broker statement-i ilə faktiki vəziyyət yenə yoxlanılır.

Hadisə istehlakçısı aşağıdakı hallara davamlı olmalıdır: eyni eventin təkrar gəlməsi, hadisələrin fərqli sırada çatması, qısa bağlantı kəsilməsi, gecikmiş fill, yalnız qismən payload və serverin retry etməsi. Webhook qəbul edən endpoint imzanı və timestamp-i doğrulamalı, payload-u dərhal dayanıqlı növbəyə yazmalı, HTTP cavabını sürətlə qaytarmalıdır. Ağır transformasiya və brokerə əlavə sorğular asinxron worker-də icra edilməlidir.

  • Provider event ID varsa, onu unique açar kimi istifadə edin; yoxdursa provider, connection, obyekt ID-si, event tipi və version/time əsasında deduplication strategiyası qurun.
  • Order statusunu yalnız “son gələn mesaj” ilə dəyişməyin. Mümkün transition-ları və source precedence qaydalarını saxlayın.
  • Hər emal cəhdini correlation ID, raw payload hash, nəticə və xəta ilə audit edin.
  • Bağlantı bərpa olunanda son etibarlı cursor-dan və ya lookback pəncərəsindən yenidən oxuyun.

Uzlaşdırma: görünən məlumatı broker mənbəyi ilə yoxlayın

İnteqrasiyanın keyfiyyəti təkcə “API 200 qaytardı” ilə ölçülmür. Brokerin jurnalınıza və ya portalınıza ötürdüyü nəticənin tam və tutarlı olmasını yoxlamalısınız. Gündəlik və ya risk səviyyəsinə uyğun daha tez-tez işləyən uzlaşdırma işi hesab üzrə cash, mövqe quantity, açıq orderlər, gün içi fill-lər, komissiyalar və transferləri müqayisə edə bilər.

Fərqləri gizlətmək əvəzinə onları idarə olunan istisnaya çevirin: “gözlənən settlement”, “broker tarixçəsi gecikir”, “simvol xəritəsi tapılmadı”, “event buraxılması ehtimalı” və “manual review” kimi səbəb kodları istifadə edin. İstifadəçi ekranında son uğurlu sinxronizasiya vaxtını, connection statusunu və məlumatın müvəqqəti natamam olduğunu aydın göstərin. Bu, səhv rəqəmi dəqiq görünən rəqəm kimi təqdim etməkdən daha doğru məhsul davranışıdır.

Vendor seçimi və texniki qiymətləndirmə checklist-i

  • Sandbox real hesab, real status keçidləri və tarixi məlumat davranışını nə dərəcədə təmsil edir?
  • API hansı account, asset class, ölkə və hüquqi entity məhdudiyyətlərinə malikdir?
  • OAuth, API key, IP allowlist və ya əlavə onboarding tələbi hansıdır?
  • Pagination, tarixçə limiti, data retention və rate-limit başlıqları sənədləşdirilibmi?
  • Order/fill/cash hadisələri hansı kanalla gəlir və reconnect-dən sonra catch-up mexanizmi varmı?
  • Event ID, versiya, imza yoxlaması və replay qoruması mövcuddurmu?
  • Statement və ya snapshot endpoint-i uzlaşdırma üçün kifayətdirmi?
  • İstifadəçi bağlantını ayıranda tokenlərin silinməsi, məlumat retention-u və support prosesi necə olacaq?

POLADO komandası broker seçimindən əvvəl texniki discovery, təhlükəsiz connection arxitekturası, import pipeline, hadisə emalı, operator paneli və uzlaşdırma prosesini planlaşdıra bilər. FinTech və analitika nümunələri üçün ESFX layihəsinə baxın; mövcud məhsulunuzun inteqrasiya risklərini və delivery planını müzakirə etmək üçün texniki dəstək və konsaltinq xidmətinə müraciət edin.