Tehnologiýalar we infrastruktura → Integrasiýa gurallary

Integrasiýa gurallary

1) Näme üçin ýöriteleşdirilen gurallar gerek?

Integrasiýa platformalaryň "gan aýlanyş ulgamy" bolup durýar: tölegler, KYC/AML, mazmun üpjün edijileri, antifrod, hasabat, marketing kanallary. Ulgamlaýyn gurallar bolmasa töwekgelçilikler artýar: döwük şertnamalar, el taýaklary, hyzmatdaşlaryň uzaga çeken onbordingleri we önümdäki hadysalar. Maksat time-to-integrate çaltlaşdyrmak, üýtgeşmeleriň ygtybarlylygyny we dolandyrylyşyny ýokarlandyrmak.

2) Integrasiýa gurallarynyň kartasy (gatlaklar boýunça)

2. 1 Taslama we aýratynlyklar

OpenAPI/Swagger (REST), gRPC/Protobuf, GraphQL SDL - şertnamalar boýunça hakykatyň ýeke-täk çeşmesi.
JSON-Schema/Euro/Proto - maglumatlaryň we wakalaryň modelleriniň beýany.
API Style Guide - neýming düzgünleri, ýalňyşlyk kodlary, paginasiýa, idempotentlik, çäkler.

2. 2 SDK we dokumentleri döretmek

Meşhur diller üçin müşderi/serwer generatorlary.
Postman/Insomnia kolleksiýalary + üýtgeýän gurşaw.
Portalyň awto-ýygnamak: interaktiw mysallar, try-it-out, changelog, Deprecation/Sunset.

2. 3 API şlýuzy we traffigi dolandyrmak

Routing: '/v1/' wersiýasynyň prefiksi boýunça, sözbaşylar/mediatipler boýunça.
Policies: Autentification (OAuth2/OIDC, HMAC, mTLS), rate limits/quotas, WAF.
Transform: başlyklar/meýdanlar, ýalňyşlyklaryň kadalaşmagy.

2. 4 Integrasiýa gatlagy (adapterler)

Çalt baglanyşyklar we orkestr üçin iPaaS/ESB.
Workflow/Orchestration: prosesleriň hereketlendirijileri (mysal üçin, çagyryş kaskady üçin state machines).
Mapping/Validation: wizual/kod mappingleri, shema tassyklaýjylary.

2. 5 Wakalaryň şinasy we shemalaryň registrleri

Waka integrasiýalary we asinxron webhook üçin Message broker/Streaming.
Schema Registry: gabat gelmek gözegçiligi (backward/forward), wakalaryň wersiýasy.

2. 6 Maglumatlar: ETL/ELT we CDC

DWH/analitikany köpeltmek üçin CDC (Change Data Capture).
ETL/ELT maglumat hili (DQ), de-duplikasiýa we PII-gözegçilik bilen paýlanylýar.

2. 7 Synag we hil

Contract Testing: OpenAPI-diff, CDC/Pact; buf breaking для protobuf.
PSP/KYC/oýun üpjün edijileriniň mok-hyzmatlary we simulýatorlary; Payload gaýtalamalary üçin replay gurallary.
Integrasiýa derejesinde ýüklemek ssenarileri (webhuklary hem goşmak bilen).

2. 8 Açarlaryň we syrlaryň howpsuzlygy

Syrlary saklamak, açarlary aýlamak, syzdyryş skany.
Partnýor hasaplaryny we açarlaryny devportal arkaly dolandyrmak.

2. 9 Integrasiýalaryň observability

'partner', 'api _ version', 'endpoint', 'error _ code' bellikli metrikler/loglar/söwdalar.
DLQ (dead-letter) we webhuklary/habarlary şowsuz eltip bermek üçin retraýlaryň nobatlary.
Integration Health Dashboard: Eltip bermek we gijikdirmek boýunça SLO.

2. 10 Hyzmatdaş operasiýa

Developer Portal: hasaba alynmak, açarlary bermek, Self-Service synaglary, arzalaryň ýagdaýy.
Release Center: integrasiýa boýunça changelog, Deprecation/EOL, bellikler.
Sandbox & Test Data: ssenariler, fiksturalar, öňünden düzülen ýalňyşlyk ýagdaýlary.

3) Integrasiýalaryň salgylanma arhitekturasy

[Partner/Client]
↕ (DevPortal: keys, docs, sandbox)
[API Gateway/WAF] — rate limits, auth, routing
↘               ↙
[Integration Layer / Adapters] ←→ [Workflow Engine]
↘               ↙
[Event Bus / Broker] ←→ [Schema Registry]
↘
[Core Microservices] ←→ [DWH/Analytics via CDC/ELT]
↘
[Webhook Delivery Service] — signer, retries, DLQ, replay

Esasy häsiýetleri: adapterleri ýadrodan anyk izolirlemek, shemalara gözegçilik etmek bilen waka şertnamalary, webhuklary gaýtadan ibermek we yzarlamak bilen eltip bermek kepilligi.

4) Integrasiýalaryň ygtybarlylygynyň nusgalary

Idempotentlik: 'Idempotency-Key '/' Request-Id' + açar ýazgysy.
Retry + Backoff + Jitter: semantikany göz öňünde tutup (iki esse hasaplamazdan).
Circuit Breaker/Timeouts/Bulkhead: partnýoryň asylmagyndan goramak.
Exactly-once (praktiki): kabul edilişde de-duplikasiýa + geleşik outbox/inbox şablonlary.
Webhook goly: HMAC-goly we wagt penjiresi.
Wersiýa: URI/mediatip boýunça vN we köne şertnamalarda Deprecation/Sunset.

5) Onbording we üýtgetmeleri dolandyrmak prosesi

1. Discovery: partnýor devportalda hasaba alynýar, sandbox açarlaryny alýar.
2. Contract Alignment: spesifikasiýalaryň utgaşdyrylmagy, tölegleriň mysallary, negative-кейslar.
3. Test Plan: funksional, şowsuzlyga çydamlylyk, webhuk ýükleri.
4. Go-Live Checklist: çäklendirmeler, alertler, dashboard, önümdäki açarlar, aragatnaşyk adamlarynyň sanawy 24/7.
5. Change Management: RFC/ADR bozýan üýtgeşmelere, habarnamalara, migrasiýa penjirelerine, Sunset-data.

6) Integrasiýa saglygynyň metrikleri (SLO/SLA)

T2I (Time-to-Integrate): arzadan ilkinji üstünlikli prod-çagyryşa çenli.
Amallar/webhuk boýunça "Success Rate", gijikdirmeler P50/P95/P99.
Retry Rate / DLQ Size, Schema-Validation Failure Rate.
Old-Version Traffic (T-senesinden soň v1%), Partner Error Mix (4xx/5xx).
Cost-per-Integration: demir, ygtyýarnamalar, goldaw.

7) Durmuş sikliniň tapgyrlary boýunça gurallar

7. 1 Design

Konwensiýalar, aýratynlyklaryň şablonlary, awtolinting.
Şertnamalaryň mysallary: success/decline/fraud/timeout.

7. 2 Build

Serwerleri/müşderileri döretmek, belli bir PSP/KYC/mazmun üpjün edijilerine adapterler.
Gurlan orta barlar: gol, idempotentlik, korrelasiýa 'trace _ id'.

7. 3 Test

Şertnama-synaglar, mok-hub, negatiw jogaplaryň ssenarileri.
Ýükleýiş profilleri: partlamalar (mahabat, ýaryşlar), kadalaşdyryjy hasabatlar.

7. 4 Launch

Canaries, Shadow-traffic, netijeleri deňeşdirmek.
Hyzmatdaşyň "gyzgyn liniýasy", ilkinji 24-72 sagat üçin war-room skript.

7. 5 Operate

Integrasiýa SLO-lary, retraýlaryň ösüşi üçin awto-triggerler.
Şowsuz webhook/kollbekler üçin çalt replay konsoly.

8) Integrasiýalaryň howpsuzlygy

Tassyklamak: Serwer üçin OAuth2 Client Credentials; Webhook üçin HMAC/mTLS.
Awtorizasiýa: end pointleri boýunça skope/roly.
PII/PCI: tokenizasiýa, ýazgylary gizlemek, traffigi segmentlemek, şifrlemek açarlary.
Syrlar: aýlaw, iň az artykmaçlyklar ýörelgesi, audit.

9) Integrasiýa maglumatlary & Analytics

CDC → DWH: integrasiýa penjireleri (üstünlik, şowsuzlyklar, gijikdirmeler, sebäpler).
Antifrod signallary: wakalaryň enrichment, alamatlaryň akym agregasiýasy.
Maglumat katalogy: shemalaryň/wakalaryň lineage, şertnamalaryň wersiýalary.

10) iGaming/fintech üçin aýratynlyklar

Tölegler/netijeler: birnäçe PSP-e adapterler, akylly marşrut, SLA zonallyk, kanallaryň ileri tutulmagy.
KYC/AML: paralel barlaglar (resminamalar, PEP/Sanctions), jogaplaryň jemlenmegi.
Oýun/mazmun üpjün edijileri: katalogyň sinhronlaşdyrylmagy, tapgyrlaryň wakalary, çäkler we jogapkär oýunlar.
Marketing/CRM: segmentasiýa webhuklary, kuponlary/mahabatlary, gijikdirilen gowşuryşlar.
Düzgünleşdiriji hasabat: shemalaryň we eksport penjireleriniň durnukly görnüşleri, hil gözegçiligi.

11) Mysallar (shemalar we bölekler)

11. 1 Idempotent REST çagyryşy

POST /v2/payouts
Idempotency-Key: 7c8d-…-a1

Gaýtalananda jogaplar - şol bir 'payout _ id' bilen 200/201.

11. 2 Webhuk goly (HMAC, psevdokod)

signature = HMAC_SHA256(secret, timestamp + "." + payload)
header: X-Signature: t=1730738400,v1=<signature>

Barlamak: penjire ± 5 minut, 5xx-da DLQ-den gaýtadan eltip bermek.

11. 3 Waka şertnamasy (JSON-Shema, bölek)

json
{
"$id": "com. company. wallet. v2. balance. changed",
"type": "object",
"required": ["event_id","occurred_at","account_id","delta","balance_after"],
"properties": {
"event_id": {"type":"string","format":"uuid"},
"occurred_at": {"type":"string","format":"date-time"},
"account_id": {"type":"string"},
"delta": {"type":"number"},
"balance_after": {"type":"number"}
}
}

12) Gurallary ornaşdyrmagyň çek-sanawy

1. Linting we breaking-checks bilen ammardaky şertnamalaryň aýratynlyklary.
2. Her neşir üçin SDK we Postman-kolleksiýalarynyň awtogenerasiýasy.
3. auth, limit, transformasiýa we wersiýa syýasatlary bilen API-şlýuzy.
4. Mok-hub we kritiki kontragentleriň simulýatorlary (PSP, KYC, mazmun).
5. Schema Registry + wakalar üçin laýyklyk düzgünleri.
6. HMAC-gol, retraýlar, DLQ we replay-konsol bilen webhuk-eltip bermek.
7. Integrasiýa dashbordlary, SLO aladalary, açarlaryň we syrlaryň barlagy.
8. Devportal: onbording, açarlar, sandbox-ssenariler, release-merkezi.
9. Seneler we aragatnaşyklar bilen Deprecation/EOL prosesi.
10. DWH-de CDC/ELT, integrasiýa hiliniň penjireleri.

13) Anti-patternler

Gözegçilik bilen adapterleriň we paýlaryň ýerine el bilen ýazylan "skriptikler".
Webhuklarda idempotentligiň we goluň ýoklugy.
Birnäçe hyzmatdaşlaryň şertnamalaryny bir "ähliumumy" we dolandyrylmaýan endpointde garyşdyrmak.
Shemalara nol gözegçilik etmek: "kompýuteri döwdüler - Twitterden öwrendiler".
Ösüş portaly we goýberiş-aragatnaşyk ýok: hyzmatdaşlar üýtgeşmeleri "gulak asýarlar".

14) Jemleýji

Integrasiýa gurallary ekosistema: aýratynlyklar, şlýuz, adapterler, wakalar we shemalar, synaglar we mok-hyzmatlar, webhuklary eltip bermek, gözegçilik etmek we devportal. Bu "howpsuzlyk guşagyny" ýygnaň we integrasiýa öňünden aýdyp boljak, çalt we ulalyp boljak bolar - we işewürlik üýtgeşmelerden we täze hyzmatdaşlardan gorkmaz.