Integracja ekosystemu partnerskiego
1) Role i modele uczestnictwa
Operatorzy/marki: sklepy, osiedla, KYC/AML, odpowiedzialność za doświadczenie użytkownika.
Studios/RGS/Agregatory treści: gry/strumienie, katalogi, narzędzia promocyjne.
Dostawcy płatności/portfele: PSP, APM, krypta, obciążenia zwrotne.
KYC/AML/Antifraud: weryfikacja, zatonęła lista, ocena ryzyka.
Oddziały/sieci marketingowe: ruch, postbacks, przypisanie.
ISV/integratory: dodatkowe moduły, aplikacje rynkowe.
Modele: referral/resell, white-label/OEM, marketplace/app-store, hub & spoken (federacja).
2) „paszport partnerski” i pakiet startowy
Dlaczego: Pojedyncze źródło prawdy o prawach, strefach, wersjach, SLO, klawiszach i procesach.
yaml partner_passport. v1:
partner_id: "kyc-omega"
type: "KYC/AML"
regions: ["EU","TR","LATAM"]
contracts: { msa: "2025-01-10", dpa: "2025-01-10", sla: "99. 9/30d" }
api_versions: ["identity. v1","events. v1","webhook. v1"]
auth: { oidc_client_id: "p_omega", scopes: ["kyc:read","kyc:write"] }
webhooks: { signature: "Ed25519", retry: "exp", dedupe: true, ttl_s: 300 }
rate_limits: { rps: 100, burst: 300 }
pii_policy: { minimization: true, retention: "180d", geo_pinning: ["EU"] }
recon: { window_days: 7, epsilon: 0. 002 }
owners: { biz: "ecosystem-biz", tech: "integrations" }
status: "sandbox"3) Wejście na pokład: Zastosowanie do procesu produkcyjnego
1. Badanie przesiewowe: kwestionariusz, partner KYC, źródła danych/ruchu, kontrola zatonęła.
2. Umowy: MSA/DPA/SLA/OLA, handel (CPA/RevShare/Hybrid/net-base).
3. Początek technologii: klucz OIDC/wydanie klienta, dostęp do piaskownicy, pakiet testowy.
4. Testy zgodności: schematy zdarzeń, haki internetowe, limity, idempotencja.
5. Przegląd bezpieczeństwa: podpis artefaktów, SBOM/SLSA (jeśli SDK/klient).
6. Pilot/kanarka: ograniczona objętość/geo, wzmocniony monitoring.
7. Go-live: transfer statusu, SLO-deski rozdzielcze, plan odpowiedzi.
8. QBR/MBR: regularne opinie KPI, incydenty, mapy drogowe.
4) Umowy o dane i schematy wydarzeń
Zasady: minimalizacja, wersje (semver), kompatybilność 'vN/vN + 1', podpisy.
yaml event. common. v1:
id: uuid occurred_at_utc: timestamp source_partner_id: string trace_id: uuid type: enum # e. g., "kyc. approved. v1"
payload: object signature: ed25519 version: "1. 0. x"Katalogi i raporty: JSON Schema/Avro, obowiązkowa kontrola pola, TTL/retencja, Legal Hold.
Stabilność: przełamywanie zmian tylko poprzez nowe typy/wersje z oknem deprecacji.
5) Uwierzytelnianie, autoryzacja, tajemnice
OAuth2/OIDC: żetony krótkotrwałe, PoP/DPoP, jeśli to możliwe.
mTLS dla serwera-serwera.
Podpisane haki internetowe: Ed25519/HMAC; anty-powtórka („X-Timestamp”, okno 5 min).
PoLP/ABAC: zakresy/atrybuty: 'partner', 'region', 'zestaw danych', 'na'.
Obrót klucza: dwustronny, z oknem kompatybilności i ścieżką audytu.
python def verify(req):
if abs(now()-req. h["X-Timestamp"])>300: return 401 if not sig_ok(req. body, req. h["X-Signature"], partner_pubkey): return 401 if seen(req. json["event_id"]): return 200 store(req. json); mark_seen(req. json["event_id"]); return 2006) Idempotencja, granice, trwałość
Idempotency-Key: 'partner _ id + external_id + op_type'.
Ograniczenie tempa/kwoty: RPS, wybuch, ciepły start, współczynniki redukcji degradacji.
Politycy retry: wystawca + jitter, dziadek w recepcji.
Wzory skrzynki odbiorczej: gwarantowana dostawa, dedup, audyt.
Backpressure: kolejki, DLQ z osobnym zatrzymaniem.
7) Obserwowalność i SLO
Метка: 'partner', 'region', 'api _ version', 'route', ''.
SLI: dostępność, opóźnienie p95/99, szybkość błędów, dostawa wewnątrz okna, recon-diff.
SLO & szybkość spalania: na partnera/węzeł; alerty przez nadmiar.
Ślady: end-to-end 'trace _ id'; pobieranie próbek ogonowych i pobieranie próbek błędów.
Syntetyka: zewnętrzne kontrole punktów końcowych/podpisów/TTL.
rego package partner. release deny["SLO at risk"] { input. slo_forecast. error_burn > 1. 0 }
deny["Missing schema tests"] { input. tests. schemas_passed == false }8) Zgodność i prywatność
Geosiatka: wrażliwe dane domeny nie pozostawiają dozwolonych regionów.
Minimalizacja i pseudonimizacja PII: 'user _ pseudo _ id' zamiast bezpośrednich PD.
Okres trwałości: TTL/ILM; crypto-erasure by key (per-partner/per-region).
Prawa przedmiotowe: routing DSAR do źródła, dziennik wykonania.
Dzienniki dostępu i audyty: kto widział kiedy, dlaczego; niezmienne kłody.
9) Obliczenia, przypisanie i pojednanie
Podstawa obliczeniowa: netto vs brutto, kursy wymiany walut, podatki, premie.
Przypisanie: windows (click/view), channel priority, dedup by 'event _ id/click _ id'.
Pojednanie: raporty dwustronne, z tolerancją, SLA dla zamknięcia rozbieżności (≤ 5 dni roboczych).
sql
SELECT a. event_id
FROM partner_report a
LEFT JOIN internal_events b ON a. event_id=b. event_id
WHERE a. date BETWEEN:from AND:to AND b. event_id IS NULL;10) Weryfikacja API i zarządzanie zmianami
Semver: 'v1' jest stabilną gałęzią; łamanie → 'v2' z podwójnym ≥ 90-dniowym wsparciem.
Proces odrzucenia: ogłoszenie → flaga w paszporcie → syntetyka/wpisy → wyłączenie.
SDK/złącza: podpis wydania, SBOM, kompatybilność, przewodniki migracji.
11) Routing i federacja (jeśli kilku partnerów tego samego typu)
SOR (Smart Order Routing): cena/jakość/opóźnienie/zgodność/reputacja.
Sprawiedliwość: limity udziału w obrotach, zerwanie przez SLA/reputację.
Degradacja: uczciwa awaria, przejrzysta degradacja (powiadomienia/banery).
12) Playbooks incydentu
12. 1 „Diagram haka sieci Web Drift”
yaml detect: "schema_validation_error_rate>0. 5%"
steps:
- "auto-pause partner webhooks"
- "fallback to cached/default behavior"
- "notify partner; open war-room"
- "provide diff & test vectors; hotfix window 24h"
kpi: ["RTA<=1h","residual_errors<0. 1%"]12. 2 "Awaria SLO w PSP/KYC'
1. Redystrybucja za pośrednictwem SOR →
2. Włącz graceful-degradacji w → strumień
3. Stosować limity/kontyngenty →
4. Utwórz kredyt SLA i po incydencie.
12. 3 „Rozbieżność w obliczeniach”
1. Zamrażanie płatności według → zakres
2. Ponowne napędzenie zdarzeń z outbox →
3. Korekty uzgadniania/
4. Wspólne działanie i rozmrażanie.
13) Rynek/Portal Partnerski
Certyfikacja integracji: listy kontrolne, odznaki jakości (Gold/Silver/Bronze).
Katalog złącza: wyszukiwanie/filtry według rynku/typu/wersji API.
Autogen-SDK/specs: OpenAPI/AsyncAPI, przykłady, kolekcje listonoszy.
Samoobsługa: klucze, webhaki, limity, czasopisma, ramki testowe.
14) Wskaźniki dojrzałości integracji
Czas do integracji (TTI) -Median dni do prod.
Zasięg: Udział rynków/funkcji wspieranych przez partnera.
Tempo przejazdu SLO: miesięcznie według partnera/regionu.
Zdrowie zwiadowcze: szybkość zamykania rozbieżności, resztki
Postawa bezpieczeństwa: częstotliwość rotacji klucza, zasięg SBOM.
Koszt/egress: $/req i $/GB według partnera, wydajność SOR.
15) Anty-wzory
„Najpierw połączyć, a następnie standardy” → integracje zoo.
Unikalne schematy dla każdego partnera → eksplozja złożoności.
Tylko przypisywanie plików cookie bez S2S → utrata i spory.
Brak idempotencji/limitów → duplikaty/burza retray.
PII w logach/hakach → ryzyko regulacyjne.
Jedna „super-integracja” bez alternatyw → ryzyko koncentracji.
API zmienia się bez okna deprecacji i syntetyki → wypadki w produkcie.
16) Lista kontrolna architekta integracji
1. Wypełniony paszport partnerski (umowy, regiony, wersje, klucze, SLO)?
2. Schematy zdarzeń i raportów są zatwierdzane przez pakiet testowy, czy istnieje piaskownica?
3. OAuth/OIDC, obowiązkowy podpis i anty-replay?
4. Idempotence, limits, outbox/inbox i DLQ wdrożone?
5. Deski rozdzielcze SLO/SLA, ślady, alerty, szybkość spalania skonfigurowane?
6. Uzgodnienie i obliczanie/przypisywanie okien sformalizowane?
7. Geosiatka/TTL/crypto-erasure i routing DSAR na miejscu?
8. Semver, proces deprecacji i podwójne wsparcie wersji udokumentowane?
9. Sprawdzone playbooks incydent (dryf obwodu, SLO nie działa, recon diff)?
10. Plan wyjścia: wyłączyć klucze, eksportować dane, migrować do drugiego źródła?
Wniosek
Integracja partnerska to rurociąg produkcyjny: normy → weryfikacja → obserwowalność → poprawa. Gdy paszport partnera jest pełny, wpisywane są zdarzenia i umowy, wymagane jest uwierzytelnianie i podpisy, mierzone są SLO, obliczenia są uzgadniane, a zmiany są zarządzane za pomocą wersji i bram - ekosystem rozwija się szybko i bezpiecznie, a każdy nowy partner dodaje wartości do sieci.