Wdrożenie API: technika i format danych dla Ministerstwa Finansów

Integracja API między kasynem a dostawcą gier wygląda na prostą wymianę danych, dopóki nie trafi się na wymóg raportowania do Ministerstwa Finansów. Wtedy okazuje się, że kasyno bez weryfikacji to hasło marketingowe, a nie stan techniczny: każdy podmiot operujący na polskim rynku musi mieć policzalny, audytowalny strumień danych o transakcjach. Ten artykuł prowadzi krok po kroku przez wdrożenie, które da się obronić przed regulatorem i nie rozsypie się przy pierwszym szczycie ruchu.

Zaczynamy od architektury: uwierzytelnianie, endpointy transakcyjne i gry, webhooki, kolejność prac. Potem przechodzimy do payloadów i mapowania pól między systemem kasyna a silnikiem dostawcy, bo to tam giną najczęściej pieniądze i rekordy. Trzeci etap to najczęściej pomijany punkt całego projektu: uzgodnienie zakresu i formatu danych AML z Ministerstwem Finansów jeszcze przed pierwszym commitem do produkcji. Jeśli ten krok wypadnie na końcu, wdrożenie cofa się o tygodnie, a czasem o miesiące.

Na końcu zostają testy end-to-end, weryfikacja kompletności raportów, audyt i utrzymanie. Kontekst regulacyjny jest tu tłem, nie ozdobnikiem: kasyno bez polskiej licencji działa poza tym obiegiem, ale jego integracje i tak muszą spełniać wymogi dostawcy oraz jurysdykcji, z której pochodzi licencja (Malta Gaming Authority, Curacao). Poniższe kroki zakładają, że masz już wybranego partnera i chcesz zbudować integrację, która przetrwa kontrolę. Warto czytać je po kolei, bo każdy etap zależy od poprzedniego.

Architektura integracji API między kasynem a dostawcą gier

Integracja API między kasynem a dostawcą gier to najczęściej kilka osobnych kanałów komunikacji, a nie jedno uniwersalne łącze. Operator musi obsłużyć katalog gier, uruchamianie sesji gracza, pojedyncze zakłady, wypłaty i raportowanie zdarzeń AML. Każdy z tych obszarów ma inny model uwierzytelniania, inne limity zapytań i inne wymagania co do czasu odpowiedzi. W praktyce wdrożenie zaczyna się od rozrysowania, które endpointy są synchroniczne (gracz czeka na wynik), a które mogą działać asynchronicznie przez webhooki.

Warstwa uwierzytelniania jest pierwszym punktem spornym. Dostawcy gier najczęściej wymagają podpisu HMAC na każdym żądaniu, z kluczem per operator i znacznikiem czasu w nagłówku. Podpis liczy się z surowego body, więc każda zmiana kolejności pól w payloadzie unieważnia sygnaturę. Drugi wariant to OAuth2 z tokenem ważnym 15 do 60 minut i odświeżaniem przez refresh token. Trzeci, spotykany u mniejszych agregatorów z licencją Curacao, to statyczny klucz API w nagłówku bez podpisu. Ten ostatni model jest najprostszy we wdrożeniu, ale przy audycie AML trudno wykazać integralność żądań, dlatego warto go traktować jako tymczasowy.

Endpointy transakcyjne dzielą się na trzy grupy. Pierwsza to launch: kasyno wysyła identyfikator gracza, kod gry i walutę, a dostawca zwraca URL sesji z tokenem. Druga to debet i kredyt: pojedynczy zakład i rozliczenie wygranej, często w jednym wywołaniu z idempotencją po transaction_id. Trzecia to rollback i korekty, potrzebne gdy gra przerwie się w połowie rundy. Idempotencja nie jest opcją. Bez niej retry po timeoucie podwaja zakład, a przy wypłacie środków generuje reklamację, której nie da się rozstrzygnąć bez logów po obu stronach.

Webhooki obsługują to, czego nie da się zrobić synchronicznie: zmiany statusu sesji, zakończenie rundy bonusowej, blokady gracza i zdarzenia wymagane przez AML. Każdy webhook powinien mieć podpis, kolejkę retry z backoffem i deduplikację po identyfikatorze zdarzenia. Kolejność dostarczania nie jest gwarantowana, więc system kasyna musi być odporny na zdarzenie przychodzące przed tym, które je poprzedza. Standardowa praktyka to bufor i sortowanie po znaczniku czasu po stronie odbiorcy.

Kolejność prac wdrożeniowych krok po kroku

1. Ustalenie zakresu: lista gier, waluty, limity zakładów i kanały wypłat. Na tym etapie wychodzi, czy dostawca obsługuje PLN natywnie, czy wymaga przeliczeń.
2. Środowisko testowe: sandbox z osobnymi kluczami, osobnymi grami i sztucznymi graczami. Bez sandboxa testy idą na produkcji, co przy kasynie bez polskiej licencji oznacza realne pieniądze w obiegu.
3. Implementacja uwierzytelniania i launch: najpierw uruchomienie sesji, bo to najprostszy test end-to-end.
4. Transakcje i idempotencja: debet, kredyt, rollback, obsługa timeoutów i błędów 5xx.
5. Webhooki i kolejka zdarzeń: podpisy, retry, deduplikacja, monitoring zaległości.
6. Raportowanie: eksport rekordów zakładów i wypłat w formacie uzgodnionym z dostawcą, z polami wymaganymi później przy raportach AML.

Realistyczny harmonogram dla jednego dostawcy to 3 do 6 tygodni przy zespole, który ma już doświadczenie z podobnymi integracjami. Najwięcej czasu pochłania nie kod, a uzgodnienie formatu danych i zachowania w sytuacjach brzegowych. Warto od razu zaprojektować warstwę mapowania, która oddziela wewnętrzny model kasyna od payloadów dostawcy. Dzięki temu kolejny dostawca, czy to z licencją Malta Gaming Authority, czy offshore, podłącza się bez przepisywania logiki transakcyjnej.

Osobna kwestia to zgodność z wymogami rynkowymi. Podmioty obsługujące polskich graczy muszą liczyć się z Rejestrem Domen Zakazanych prowadzonym przez Ministerstwo Finansów oraz z monopolem Total Casino na hazard online w Polsce. Integracja API tego nie zmienia, ale wpływa na to, jakie dane trzeba rejestrować i jak szybko da się je wyeksportować. Strona promuje odpowiedzialną grę i linkuje do Anonimowi Hazardziści oraz Uzależnienia Behawioralne, gdzie gracze znajdą wsparcie.

Format danych i raportowanie transakcji w standardzie API dostawcy

Kiedy handshake i autoryzacja z poprzedniego etapu działają, zaczyna się właściwa robota: ustalenie, co dokładnie leci w payloadzie i jak te dane trafiają do bazy kasyna. W praktyce integracja z dostawcą gier sprowadza się do trzech typów rekordów: zakładu (bet), rozliczenia (settlement) i wypłaty (payout). Każdy z nich ma własny zestaw pól i własne pułapki przy mapowaniu.

Standardowy payload zakładu z API dostawcy zawiera co najmniej: unikalny identyfikator transakcji nadany przez dostawcę, identyfikator sesji gracza, identyfikator gry i jej wersję, znacznik czasu w UTC z dokładnością do milisekund, kwotę zakładu, walutę, mnożnik i wynik rozliczenia. Do tego dochodzą pola techniczne, które łatwo pominąć: numer rundy (round_id), identyfikator jackpotu, jeśli gra go obsługuje, oraz flagę trybu demo. Bez round_id nie zmapujesz poprawnie zakładów w grach z wieloma rundami w jednej sesji, a bez flagi demo możesz wciągnąć do raportu ruch testowy.

Rekord wypłaty wygląda inaczej, bo dotyczy przepływu pieniędzy, nie wyniku gry. Tu liczą się: identyfikator wypłaty, powiązany identyfikator transakcji źródłowej, kwota netto i brutto, prowizja, status (pending, approved, rejected, reversed) oraz znacznik czasu zmiany statusu. Dostawcy często wysyłają wypłatę w osobnym webhooku niż zakład, więc kolejność zdarzeń w kolejce musi być zachowana. Jeśli webhook wypłaty dotrze przed webhookiem zakładu, system kasyna musi poczekać albo odrzucić zdarzenie i poprosić o retry.

Mapowanie danych między systemami kasyna i dostawcy

Mapowanie to najczęstsze źródło rozjazdów w raportach. System kasyna ma własne identyfikatory graczy, gier i sesji, a dostawca swoje. Potrzebna jest tabela translacji, która w obie strony zamienia klucze i zapisuje historię zmian. Praktyczna kolejność prac przy mapowaniu wygląda tak:

• Zbierz słownik pól od dostawcy i porównaj z modelem danych kasyna, pole po polu, z typem i dopuszczalnym zakresem.
• Ustal jeden identyfikator transakcji nadrzędny (najczęściej ten od dostawcy) i traktuj go jako klucz idempotencji przy zapisie.
• Zdefiniuj mapowanie walut i zaokrągleń: kwoty w groszach jako liczby całkowite, bez float, z jawnym zaokrąglaniem przy przewalutowaniu.
• Ustal strefę czasową i format czasu: wszystko w UTC, konwersja na czas lokalny dopiero w warstwie raportowej.
• Przygotuj tabelę kodów błędów dostawcy i przypisz każdemu kodowi akcję: retry, odrzucenie, korekta ręczna.

Dane, które trafiają do raportów AML, muszą być kompletne na poziomie pojedynczej transakcji, bo późniejsza agregacja nie odtworzy brakujących pól. Dlatego już na etapie mapowania warto ustalić, które pola są obowiązkowe dla Ministerstwa Finansów, a które tylko pomocnicze. W praktyce oznacza to, że rekord zakładu i wypłaty musi nieść identyfikator gracza, kwotę, walutę, czas i typ operacji w formacie, który da się bezpośrednio przenieść do raportu. Jeśli dostawca nie wysyła któregoś pola, trzeba je uzupełnić po stronie kasyna i udokumentować źródło.

Osobna kwestia to bonusy. Bonus bez depozytu i środki bonusowe mają inny cykl życia niż depozyt, więc w payloadzie muszą być oznaczone osobnym typem transakcji. Bez tego raport pokaże zawyżone obroty, a kontrola AML zwróci uwagę na kwoty, które nigdy nie były prawdziwą gotówką. Warto też ustalić, czy dostawca raportuje zakłady anulowane i jak je oznacza, bo pojedynczy błędny status potrafi zafałszować sumę wypłat w danym dniu.

Na koniec: każdy payload zapisuj w formie surowej (raw log) obok znormalizowanego rekordu. Przy sporze z dostawcą albo przy audycie masz wtedy dowód, co przyszło w oryginale, a co zostało przeliczone po stronie kasyna. To drobiazg, który ratuje godziny pracy przy rekoncyliacji.

Uzgodnienie formatu raportowania AML z wymogami Ministerstwa Finansów

Najczęstszy powód opóźnień we wdrożeniach API, z jakim się spotykam, nie leży w kodzie. Leży w tym, że zespół techniczny buduje integrację transakcyjną, a dopiero na koniec orientuje się, że zakres danych AML wymagany przez Ministerstwo Finansów nie został uzgodniony z nikim po stronie zgodności. Nawet jeśli w dokumentacji pojawia się hasło https://stonevegas-bonus.pl/kasyno-bez-weryfikacji/, to kasyno bez weryfikacji na poziomie rejestracji nadal musi raportować operacje podejrzane, a format tych raportów nie wynika z dokumentacji API dostawcy gier. To trzeba ustalić osobno i zrobić to przed pierwszym commitem, nie po go-live.

Co dokładnie trzeba uzgodnić przed wdrożeniem

Integracja API z dostawcą gier przekazuje strumień zdarzeń: depozyt, zakład, wygrana, wypłata środków. System AML operatora potrzebuje z tego strumienia kilku pól, których dostawca często nie wystawia domyślnie. Chodzi o identyfikator gracza w systemie kasyna, znacznik czasu w UTC z dokładnością do sekundy, kwotę i walutę, kierunek przepływu, kanał płatności oraz identyfikator transakcji nadrzędnej przy korektach i zwrotach. Do tego dochodzi status weryfikacji KYC w momencie transakcji, bo bez niego nie da się ocenić, czy dana operacja podlega wzmocnionym środkom bezpieczeństwa.

Praktyczna kolejność prac wygląda tak:

1. Zbierz od działu zgodności listę pól wymaganych w raportach okresowych i w zgłoszeniach pojedynczych operacji. Zapisz to jako schemat, nie jako opis w mailu.
2. Zestaw ten schemat z payloadem, który realnie zwraca API dostawcy. Różnice wypisz w tabeli mapowania.
3. Ustal z dostawcą, czy brakujące pola dostarczy w webhooku, w endpoincie historii transakcji, czy przez eksport plikowy po stronie kasyna.
4. Uzgodnij z Ministerstwem Finansów zakres i format przekazywanych danych. To krok, który najczęściej wypada z harmonogramu.
5. Dopiero potem zamroź kontrakt API i przejdź do implementacji.

Punkt czwarty bywa pomijany z prostego powodu: zespoły traktują raportowanie AML jako funkcję wewnętrzną. Tymczasem zakres danych, częstotliwość przekazywania i sposób identyfikacji podmiotu muszą być spójne z tym, czego oczekuje resort finansów. Jeśli kasyno działa na licencji Malta Gaming Authority albo Curacao, dochodzi jeszcze warstwa raportowania do regulatora zagranicznego, a formaty się różnią. Kasyno bez polskiej licencji nie jest zwolnione z obowiązków AML, jeśli obsługuje graczy z Polski.

Osobna sprawa to pranie pieniędzy przez strukturyzowanie wpłat. Żeby je wykryć, system musi widzieć transakcje w oknie czasowym, a nie pojedyncze rekordy. To oznacza, że API musi udostępniać paginowaną historię z filtrem po graczu i dacie, inaczej analityk dostaje wyrywki. Warto wymóc na dostawcy endpoint historii z zakresem dat i limitem strony, zanim podpisze się umowę.

Reguła z praktyki: jeśli schemat raportu AML nie jest zamrożony przed startem implementacji, każde wdrożenie integracji API przesuwa się o dwa do czterech tygodni. Nie z powodu błędów, tylko z powodu przepisywania warstwy mapowania.

Ostatnia rzecz, którą warto zapisać w kontrakcie: dostawca musi zagwarantować retencję danych transakcyjnych przez okres wymagany przepisami oraz możliwość ponownego eksportu po zmianie formatu raportowania. Bez tego każda nowelizacja wymogów oznacza ręczne odtwarzanie historii z logów, a to zajmuje dni i generuje ryzyko niezgodności.

Testy, audyt i utrzymanie integracji w środowisku regulacyjnym

Wdrożenie integracji to dopiero początek. Najwięcej pracy pochłania etap testów i późniejsze utrzymanie, zwłaszcza gdy system ma raportować dane AML do Ministerstwa Finansów. Poniżej kolejność działań, którą stosuje się w praktyce przy podłączeniu kasyna do dostawcy gier.

Etap 1: testy jednostkowe na payloadach. Zanim ruszy jakikolwiek ruch, warto przygotować zestaw przykładowych rekordów zakładów i wypłat i przepuścić je przez walidator schematu. Sprawdzamy typy pól, wymagalność identyfikatorów sesji, poprawność kodów walut i znaczników czasu w UTC. Każdy odrzucony payload to potencjalna luka w raportowaniu, którą później trudno wykryć.

Etap 2: testy end-to-end w środowisku sandbox. Dostawca udostępnia zwykle piaskownicę z osobnymi kluczami API. Symulujemy pełny cykl: rejestracja gracza po stronie kasyna, depozyt, seria zakładów, wypłata środków i wygenerowanie rekordów do raportu. Kluczowe jest porównanie liczby transakcji po obu stronach. Jeśli kasyno wykazało 10 000 zakładów, a dostawca 9 987, mamy 13 rekordów do wyjaśnienia. Tolerancja powinna wynosić zero.

Etap 3: weryfikacja kompletności raportów AML. To etap najczęściej pomijany. Test polega na tym, że do systemu wprowadzamy celowo nietypowe scenariusze: wiele szybkich depozytów poniżej progu, wypłaty na rachunek w jurysdykcji wysokiego ryzyka, zmiany danych osobowych tuż przed wypłatą. Następnie sprawdzamy, czy każdy z tych przypadków trafił do raportu w uzgodnionym formacie i z wymaganymi polami. Rekord bez znacznika ryzyka lub bez identyfikatora dokumentu tożsamości jest błędem, który przy audycie wychodzi natychmiast.

Etap 4: audyt wewnętrzny i zewnętrzny. Przed uruchomieniem produkcyjnym przygotowujemy pakiet dowodowy: logi uwierzytelniania, próbki payloadów, raport rozbieżności i opis procedury ich rozwiązywania. Audytor sprawdza nie tylko, czy dane są kompletne, ale czy da się je odtworzyć po fakcie. Retencja logów na poziomie 5 lat to standard, który warto ustalić z dostawcą w umowie SLA, a nie dopiero po pierwszym wezwaniu.

Etap 5: monitorowanie po wdrożeniu. Utrzymanie integracji to codzienna obserwacja kilku metryk: odsetka odrzuconych webhooków, opóźnienia w dostarczaniu rekordów transakcyjnych, liczby nieudanych wypłat i czasu odpowiedzi endpointów. Progi alarmowe ustawiamy tak, by ostrzeżenie pojawiało się, zanim problem zauważy gracz. Przykładowo: jeśli webhook o wypłacie nie dotrze w ciągu 60 sekund, system powinien automatycznie ponowić próbę i oznaczyć transakcję do ręcznej weryfikacji.

Etap 6: zmiany i wersjonowanie. Dostawcy gier aktualizują API średnio dwa razy w roku. Każda zmiana schematu wymaga przejścia przez kroki 1-3 w środowisku testowym i ponownej weryfikacji raportów AML. Wersjonowanie endpointów z okresem przejściowym (najlepiej 90 dni) pozwala uniknąć sytuacji, w której stary format przestaje być przyjmowany z dnia na dzień.

Warto pamiętać, że strona promuje odpowiedzialną grę i linkuje do materiałów pomocowych, takich jak Anonimowi Hazardziści oraz Uzależnienia Behawioralne. Integracja techniczna nie zwalnia z obowiązku monitorowania zachowań graczy, a dane z API są do tego jednym z najlepszych źródeł. Dobre wdrożenie to takie, w którym raport AML generuje się sam, a zespół compliance zajmuje się analizą, nie rekonstrukcją brakujących rekordów.

Praktyczny krok na jutro: zrób mapę przepływu danych AML na jednej kartce. Po lewej wypisz źródła (system kasyna, API dostawcy, logi webhooków), po prawej pola wymagane przez Ministerstwo Finansów, a pomiędzy narysuj strzałki z nazwami pól i typami. Jeśli któraś strzałka nie ma pokrycia w payloadzie, to jest twoje pierwsze zadanie wdrożeniowe, nie dokumentacja po fakcie. W praktyce najczęściej brakuje identyfikatora sesji gry, znacznika czasu w UTC z dokładnością do sekund oraz powiązania depozytu z konkretną rundą. Ustal też od razu, kto odpowiada za rekonsyliację: operator czy dostawca. Zapis w umowie, że rozbieżność powyżej 0,5 proc. w dziennym saldzie uruchamia wspólne dochodzenie w ciągu 24 godzin, oszczędza tygodnie sporów podczas audytu.

Drugi krok to test na małą skalę przed pełnym ruchem. Puść przez integrację jeden dzień transakcji w trybie shadow, porównaj sumy zakładów, wypłat i depozytów z raportem dostawcy i dopiero potem przełącz ruch produkcyjny. Przy okazji sprawdź, czy webhooki po retry nie dublują rekordów, bo to najczęstsza przyczyna zawyżonych raportów AML. Pamiętaj o kontekście: kasyno bez polskiej licencji i tak musi mieć porządek w danych, jeśli chce wypłacać środki bez tarć, a kasyno bez weryfikacji na starcie nadal wymaga KYC przy wypłacie wygranych. Strona promuje odpowiedzialną grę i linkuje do Anonimowi Hazardziści oraz Uzależnienia Behawioralne, bo techniczna sprawność integracji nie zastąpi kontroli nad własnym budżetem. Ustaw monitoring alertów na opóźnienia webhooków powyżej 60 sekund i przeglądaj logi raz w tygodniu. To wystarczy, żeby złapać większość problemów, zanim zobaczy je regulator.