Operațiuni API

(Secțiunea: Operațiuni și Management)

1) Scop și principii

API-ul este „stratul operațional” al ecosistemului: orice nu este automatizat printr-un contract se transformă în muncă manuală și risc.

• Primul contract: prima specificație (OpenAPI/JSON Schema/AsyncAPI), apoi implementarea.
• Secure-by-default: scopuri minime, TTL scurt, mutual-TLS/semnături.
• Observabil: urmărire end-to-end și măsurători SLA.
• Idempotent: Reluarea în condiții de siguranță.
• Compatibil invers: evoluția fără modificări de „rupere”.
• Auditabil: fapte confirmate criptografic (chitanțe).

2) Contract și modele (de referință)

OpenAPI pentru cereri de sincronizare; AsyncAPI pentru evenimente/webhooks.
Câmpurile necesare în fiecare resursă sunt „id',” versiune „,” creat _ at „,” actualizat _ at „,” chiriaș „,” regiune „,” trace _ id'.

Exemplu de fragment de contract

yaml paths:
/payments/payouts:
post:
operationId: createPayout requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutRequest'
responses:
"202": { $ref: '#/components/responses/AcceptedWithReceipt' }
headers:
Idempotency-Key:
schema: { type: string }
required: true components:
responses:
AcceptedWithReceipt:
description: Accepted, processing asynchronously headers:
Receipt-Hash: { schema: { type: string } }

3) Autentificare, autorizare, scopuri

OAuth2/OIDC pentru utilizatori/parteneri client-acreditări/JWT для S2S.
Scopuri/roluri de resurse: "plăți. scrie „,” catalog. citi „,” audit. export ".
ReBAC: acces „prin proprietate” (chiriaș/cont/sub-cont).
Secretele JIT: jetoane de scurtă durată, dispozitiv/subrețea/regiune de legare.
Postură dispozitiv & mTLS pentru operațiuni critice (plăți, chei).

4) Idempotența și „exact o dată”

Idempotency-Key (header) + dedup by '(cheie, cont, rută)' în fereastra TTL.
Outbox/CDC pentru a posta evenimente - livrare garantată.
Exact-o dată-efecte: efectele secundare sunt capturate printr-un jurnal de tranzacție; repetarea duce la aceeași „chitanță” („chitanță _ hash”).
Politici de retractare: back-off exponențial, jitter, ferestre maxime.

5) Limite, cote, prioritizare

Limite tarifare: per cheie/chiriaș/rută/regiune; „moale” (429) și „tare” (tăiere).
Cote/bugete: plafoane lunare/zilnice, carti web 'CotaCapAtins'.
Utilizarea corectă: prioritatea chiriașilor în funcție de nivelul serviciilor (Aur/Argint/Bronz).
Tampoane de explozie: explozii scurte fără degradarea vecinilor.

6) Paginare, filtre, probe

Bazat pe cursor (comandă stabilă по "creat _ at, id')," page _ size "≤ 1000.
Eșantioane feliate în timp („de la”, „la”, „filigran”) pentru jurnale/tranzacții.
Filtrarea DSL: whitelisted поля, '? status =... & chiriaș =... & region =...'.
Sugestii de consistență: 'instantaneu _ la '/' as _ of' pentru raportarea API-urilor.

7) Versioning și compatibilitate

SemVer: 'v1', 'v1. 1 '(extensii),' v2 '- numai pe căi/namespace-uri noi.
Reguli de evoluție: adăugați doar câmpuri/valori, „depreciați → eliminați” prin fereastră.
Teste de compatibilitate: „contracte ca teste” (bazate pe consumatori).

8) Evenimente, carti web si chitante

AsyncAPI descrie temele/sarcina utilă/semnături.

Legendă: HMAC/EdDSA, anteturile „X-Signature”, „X-Nonce”, „X-Timestamp” (fereastră îngustă)

Chitanțe: 'chitanță _ hash' și semnătură DSSE pe evenimente critice (plăți, modificări RTP/limită, liste de prețuri).
Retrai și dedup: idempotență în conformitate cu 'idempotency _ key '/' event _ id'.
DLQ/carantină: rapoarte invalide/repetate cu cauze.

9) Observabilitate și calitate

Urme: obligatoriu 'trace _ id/span _ id' prin gateway/business events/webhooks.
Valori: disponibilitate, p50/p95/p99, rata de eroare, rata de încercare, costul per 1k.
Busteni: structurat, fara secrete/PII; etichetele „tent/region/version”.
SLO/alerte: condiții orientate spre SLO și auto-rune (pauză/re-rută/rollback).

10) Erori și semantică de stare

2xx - succes (202 pentru operații asincrone).
4xx - vina clientului (422 - validare, 409 - conflict/idempotenta, 429 - limite).
5xx - probleme temporare.
Corpul de eroare: 'cod', 'mesaj', 'trace _ id',' indiciu ',' retry _ after? '.
UX pentru parteneri: un tabel de „ce să faci” pentru fiecare eroare.

11) Policies-as-code (OPA/ABAC)

Autorizație centralizată: „cine/ce/unde/când/de ce”.
Politici în Git, revizuirea codului, teste CI (pre-zbor: "va permite politica? »).
Verificare SoD: „creați plata” ≠ „aprobați”.

12) Securitate, confidențialitate, conformitate

PII minimizare: tokenizare/măști, acces la primar numai prin jabs aprobate.
Secrete: Vault/KMS, TTL scurt, rotații; interzicerea secretelor comune.
Criptare: mTLS/TLS 1. 3, AES-GCM în repaus, HSTS/PKP, după caz.
Conștient de jurisdicție - Localizarea datelor/cheilor pe regiune.
Jurnale de audit: WORM, Merkle-felii, DSSE-semnături.

13) Funcționare: SLI/SLO și tablouri de bord

• Disponibilitate pe traseu/regiune.
• p95 latență (citire/scriere).
• Succesul de webhooks (chitanțe), lag de livrare.
• Rata de eroare/Rata de reîncercare.
• Cost pe 1k cereri și ieșire.

SLO (exemplu): 99. 95% disponibilitate; p95 ≤ 120/250 ms; cârlige ≥ 99. 5 %/5-min; P1 MTTR ≤ 60 min.

14) Managementul schimbării (versiuni/rollback-uri)

Blue-Green/Canare pentru gateway-uri și rute critice.
Ficheflags pentru comportament fără eliberare.
Expand→Migrate→Contract pentru scheme și sarcină utilă.
Руны: Rollback Release, Disable Flag, Re-route, Flush Cache.
Artefacte: imagini/manifeste semnate, registru versiune.

15) SDK, clienți, cutii de nisip

SDK-uri oficiale (TS/Java/Python/Go) cu aceeași eroare și semantică retray.
Medii Sandbox cu chei de testare/certificate și simulatoare PSP/KYC/furnizor de conținut.
Testele contractuale sunt incluse în CI SDK, compatibilitate nocturnă.

16) Modelul de date (simplificat)

'api _ key' '{id, chiriaş, scopes [], ttl, created_by}'

'rate _ plan' '{chiriaș, quotas{route→cap}, izbucnire, prioritate}'

'request _ log' '{trace _ id, route, actor, idempotency_key?, status, latency_ms, region, cost_unit}'

'webhook _ chitanţă' '{event _ id, endpoint, status, încercări, receipt_hash, semnătură}'

'politicy' '{versiune, reguli, semnatar, dsse}'

17) RACI

18) Măsurători ale calității

Contract Drift: 0 „rupere” modificări fără depreciere.
Idempotency Error Rate: ≤ 0. 01%.
Succes prin broşură web: ≥ 99. 5%, lag p95 ≤ 60 s.
Auth Fail vs Abuz: cota de blocuri rău intenționate, nivelul de zgomot ≤ țintă.
Cost/1k: controlul pe rute și regiuni (bugete/alerte de plafonare).
Adoptarea SDK: ponderea traficului prin SDK-uri oficiale.

19) Registrele de redare incidente

Spike 429/limite: ridicați capacul pentru aur, strângeți cheile „zgomotoase”, conectați-vă cu un partener.
WebhookLag: creșteți lucrătorii/loturile, prioritizați cozile, dezactivați temporar cărțile web opționale.
PriceMismatch (catalog/FX/Tax): reconciliere versiune, invaliditate forță cache, rollback artefact, compensare.
PSP Outage: comutarea traseului, carantinarea tranzacțiilor „gri”, reluarea.
Compromite API-cheie: rechemare imediată, rotație, auditul ultimelor 30 de zile.

20) Specificitatea iGaming/fintech

RTP/Limite API: numai agregate și versiuni de profil; modificări - cu chitanțe.
Plăți/plăți: 202 + webhook-uri semnate; comanda idempotenta cheie.
Afiliați: dedup de conversie, escrow pentru litigii, rapoarte semnate.
Joc responsabil: Expune „parapete API” pentru limite și evenimente RG.

21) Lista de verificare a implementării

• Contract descris (OpenAPI/AsyncAPI), validare CI și teste de consum.
• Configurate OAuth2/OIDC, scopuri, secrete JIT și mTLS pentru rute critice.
• Idempotența, retrai, DLQ și carantina introduse.
• Capace/cote/priorități și alerte.
• Paginare cursor, „as _ of” probe consistente.
• Politica de versionare și depreciere.
• Webhooks cu semnături/chitanțe, reluare și dedup.
• Urme/metrici/busteni, SLO și rune.
• jurnale WORM, semnături DSSE, felii Merkle.
• SDK, sandbox, simulatoare, mostre de cod și cum să.

22) ÎNTREBĂRI FRECVENTE

De ce 202 pentru operațiuni lungi?
Pentru a nu menține conexiunea și pentru a oferi o retray/chitanță fiabilă prin webhook.

Aveți nevoie atât de OpenAPI, cât și de AsyncAPI?
Da: sincronizare pentru comenzi/cereri, async pentru evenimente/negociere de stat.

Cum să evitați schimbările de rupere?
Regula add-only, depreciați → respectați → eliminați, contractul de testare a clienților.

Unde se stochează chitanțele?
Într-o zonă WORM cu semnături; 'receipt _ hash' este returnat clientului și verificat la cerere.

Rezumat: Operațiunile prin API sunt disciplina contractului și a funcționării: model strict de acces și idempotență, limite și versiuni, observabilitate și SLO, semnături și chitanțe. Adăugați cutii de nisip și SDK-uri - iar partenerii se vor integra rapid, sigur și previzibil, iar întreprinderile se vor extinde fără pierderi de calitate sau conformitate.