Zarejestruj się

Przypadek użycia · KYB

KYB API dla polskich firm: weryfikacja po KRS i NIP

Zweryfikuj firmy z UE i Wielkiej Brytanii w produkcji w 30 liniach kodu. Numer KRS, NIF, SIREN lub company_number → pełny profil rejestrowy i screening sankcyjny w jednym wywołaniu REST.

Problem

Onboarding kontrahenta B2B w regulowanej branży finansowej w UE wymaga udowodnienia czterech rzeczy przed rozpoczęciem współpracy: że firma legalnie istnieje, że wiesz, kto ją kontroluje, że żadna z zaangażowanych stron nie podlega sankcjom, i że nie ma oczywistego sygnału ostrzegawczego. Standardowe narzędzia do tego są rozproszone — jeden dostawca dla danych hiszpańskich, inny dla francuskich, kolejny dla brytyjskiego Companies House, osobny dla danych z polskiego KRS, jeszcze inny dla sankcji. Każdy kontrakt jest roczny, o nieprzejrzystej cenie, i wymaga rozmowy handlowej.

Dla fintechu onboardującego kilkaset kontrahentów B2B miesięcznie, w tym część polskich, taki stos dostawców jest kosztowny i spowalnia integrację. API Prometiam zastępuje warstwę rejestrową i sankcyjną jednym zestawem endpointów REST z przewidywalną ceną za wywołanie.

Integracja w 30 sekund

Trzy endpointy pokrywają przepływ rejestr-i-sankcje w KYB. Uruchom je w tej kolejności — przykład dla polskiego kontrahenta, którego numer KRS, NIP lub REGON możesz najpierw sprawdzić w wyszukiwarce KRS:

# 1. Znajdz kontrahenta po nazwie lub numerze KRS (parametr company_number)
curl 'https://api.prometiam.com/functions/v1/risk-api/companies/search?name=orlen&country=PL' \
  -H 'Authorization: Bearer rk_live_...'

# 2. Pobierz pełny profil firmy (kapital, status, dane rejestrowe KRS)
curl 'https://api.prometiam.com/functions/v1/risk-api/companies/4000000123456' \
  -H 'Authorization: Bearer rk_live_...'

# 3. Sprawdz nazwe spolki pod katem sankcji
curl 'https://api.prometiam.com/functions/v1/risk-api/sanctions/screen?name=ORLEN&threshold=85' \
  -H 'Authorization: Bearer rk_live_...'

Dla polskich kontrahentów krok 2 nie zwraca członków zarządu — API jest na poziomie firmy, bez danych z CRBR i KRZ. Dlatego krok 3 sprawdza nazwę spółki, a osoby, które chcesz przesiać (na przykład reprezentantów zgłoszonych przez klienta w formularzu onboardingowym), przekazujesz do /sanctions/screen osobno, z entity_type=person. Dla Hiszpanii, Francji, Wielkiej Brytanii i Norwegii ten sam endpoint /companies/{id} zwraca contacts z obecnymi i historycznymi członkami zarządu — dla tych krajów screening obejmuje spółkę i każdego aktualnego dirigenta automatycznie.

Przykład w Pythonie

import os, requests

API = 'https://api.prometiam.com/functions/v1/risk-api'
HEAD = {'Authorization': f'Bearer {os.environ["PROMETIAM_API_KEY"]}'}

def kyb_check_pl(krs: str, provided_names=None):
    # Rozwiaz spolke po numerze KRS (parametr company_number)
    s = requests.get(f'{API}/companies/search',
                      params={'company_number': krs, 'country': 'PL'}, headers=HEAD).json()
    if not s.get('data'): return {'status': 'not_found'}
    company = s['data'][0]

    # Pelny profil - poziom firmy dla Polski: bez zarzadu, bez CRBR, bez KRZ
    detail = requests.get(f'{API}/companies/{company["id"]}', headers=HEAD).json()['data']

    # Sankcje na osobie prawnej
    legal_hits = requests.get(f'{API}/sanctions/screen',
                              params={'name': detail['company_name'], 'threshold': 85},
                              headers=HEAD).json()['data']

    # Polska nie zwraca czlonkow zarzadu przez API -
    # sprawdz nazwiska, ktore przekazuje klient w formularzu onboardingowym
    person_hits = []
    for full_name in (provided_names or []):
        h = requests.get(f'{API}/sanctions/screen',
                         params={'name': full_name, 'threshold': 85, 'entity_type': 'person'},
                         headers=HEAD).json()['data']
        if h: person_hits.append({'person': full_name, 'matches': h})

    return {
        'status': 'verified' if (not legal_hits and not person_hits) else 'review',
        'company': detail,
        'sanctions': {'legal': legal_hits, 'persons': person_hits},
    }

29 linii łącznie z importami. Ta sama funkcja z country='ES', 'FR', 'GB' lub 'NO' automatycznie znajdzie członków zarządu w detail['contacts'] — dla Polski i Irlandii to pole jest puste, dlatego provided_names jest jedynym źródłem osób do sprawdzenia.

Co faktycznie otrzymujesz

Odpowiedź /companies/{id} zawiera to, czego potrzebuje osoba odpowiedzialna za zgodność, aby wypełnić dokumentację onboardingową:

  • Tożsamość: nazwa, numer KRS/NIF/SIREN/company_number, forma prawna, adres, data założenia
  • Dane rejestrowe: numer KRS dla Polski, dokładne tomo/libro/folio/hoja dla Hiszpanii, siedziba sądu rejestrowego dla Francji, numer Companies House dla Wielkiej Brytanii
  • Skład zarządu: dostępny wyłącznie dla Hiszpanii, Francji, Wielkiej Brytanii i Norwegii (obecne i historyczne mandaty — nazwa, funkcja, data powołania, data zakończenia). Dla Polski i Irlandii pole contacts jest puste — API jest na poziomie firmy
  • Status: aktywna, rozwiązana, w likwidacji itd., aktualizowany codziennie
  • Kapitał i przedmiot działalności: kapitał zakładowy (capital_amount + capital_currency) i oficjalny opis działalności (activity_description)

Odpowiedź /sanctions/screen zwraca dopasowania ze wskaźnikiem pewności (0–100), źródłem listy (UE / ONZ / OFAC / UK / Australia (DFAT) / gels FR / US CSL) i ewentualnymi aliasami. Próg dopasowania ustawiasz dla każdego wywołania, aby kontrolować odsetek fałszywych trafień.

Zrzut ekranu panelu klienta: profil firmy z identyfikatorami i sygnałamiZrzut ekranu panelu klienta: profil firmy z identyfikatorami i sygnałami
Ten sam rekord w panelu: identyfikatory, siedziba oraz sygnały niewypłacalności, sankcji (beta) i rejestru na jednej stronie. Pokazano brytyjską firmę. Otwórz w panelu

Dopasowanie cenowe

Dla fintechu onboardującego 500 polskich kontrahentów B2B miesięcznie, typowy przepływ to około 3–4 wywołania API na kontrahenta (wyszukanie + szczegóły + screening spółki + screening nazwisk podanych przez klienta) — bez dodatkowych wywołań na członków zarządu, bo tych API dla Polski nie zwraca. To około 2 000 wywołań miesięcznie, czyli około 4 000 kredytów (wyszukanie i szczegóły po 1 kredycie, każdy screening 3). Pełny screening sankcyjny wymaga planu Professional (29,99 €/miesiąc, 10 000 kredytów miesięcznie), w którym te 4 000 kredytów to 40% limitu. Przy 5 000 kontrahentach miesięcznie (około 40 000 kredytów) potrzebny jest plan Scale (99,99 €/miesiąc, 50 000 kredytów miesięcznie).

Dostawcy danych wyłącznie polskich zwykle nie publikują cennika dla porównywalnego wolumenu — wymaga to kontaktu handlowego i rocznego kontraktu.

Wzorce wdrożenia

Cachuj częste wyszukiwania. Większość fintechów B2B onboarduje wielokrotnie te same spółki matki. Zapisz odpowiedź /companies/{id} w cache na 24 godziny; odśwież na żądanie lub w codziennym zadaniu w tle.

Monitorowanie po onboardingu. POST /monitor obejmuje polskie spółki (i większość pozostałych krajów): subskrybuje spółkę i wysyła podpisane HMAC-SHA256 webhooki (X-Prometiam-Signature) przy zmianach statusu, rozwiązaniu, trafieniach sankcyjnych i zdarzeniach zmian w rejestrze. Endpoint /company-events/timeline, przydatny dla Hiszpanii, Francji i Wielkiej Brytanii, ma dla Polski wyłącznie zdarzenia zmian w rejestrze (nazwa, status, forma prawna, siedziba), od 14 października 2026, bez dziennika urzędowego; do bieżącego nadzoru używaj webhooków z POST /monitor.

KYB a obowiązki AML. KYB (Know Your Business) to weryfikacja kontrahenta firmowego przed nawiązaniem współpracy. Instytucje obowiązane w rozumieniu ustawy o przeciwdziałaniu praniu pieniędzy i finansowaniu terroryzmu stosują środki bezpieczeństwa finansowego wobec klientów; API dostarcza z KRS dane do potwierdzenia istnienia, statusu i formy prawnej spółki, a decyzję o ryzyku nadal podejmuje człowiek. Programiści znajdą szczegóły wyszukiwania w przewodniku po API KRS.

Dostrajanie progu sankcyjnego. Zacznij od 85 (wartość domyślna), potem dostrajaj według kosztu fałszywych trafień. Dla onboardingu wysokiego ryzyka (kredyty, przetwarzanie płatności) bezpieczniejszy jest próg 80. Dla niskiego ryzyka (zapis do newslettera, weryfikacja darmowego planu) próg 90 redukuje szum.

Ograniczenia zakresu, wprost

  • Hiszpania, Francja, Wielka Brytania, Norwegia, Polska i Czechy zwracają członków zarządu przez ten sam endpoint (polskie osoby fizyczne są maskowane przez rejestr; czeskie osoby fizyczne to wyłącznie imię i nazwisko oraz miesiąc i rok urodzenia). Dla pozostałych krajów, bez członków zarządu — Irlandii, Finlandii, Szwecji, Belgii, Chorwacji, Danii, Estonii, Słowacji, Szwajcarii, Łotwy, Cypru, Rumunii, Litwy, Kanady, Australii, Japonii, Izraela, Singapuru, Kolumbii, Tajwanu, Niemiec, Argentyny, Ukrainy, Serbii, Ekwadoru, Chile, Meksyku, Holandii, Brazylii i Stanów Zjednoczonych — API jest na poziomie firmy: brak członków zarządu, brak danych z CRBR, brak danych z KRZ.
  • Beneficjenci rzeczywiści są dostępni wyłącznie z brytyjskiego rejestru PSC. Dla Polski nie ma nawet danych o członkach zarządu, więc nie ma czego mylić z beneficjentem rzeczywistym.
  • Powiadomienia o niewypłacalności obejmują wyłącznie spółki, na szesnastu rynkach (FR, DE, GB, AT, CH, NO, FI, US, NL, DK, HR, SE, ES, LV, EE, SG) — Polska nie jest jednym z nich; dla Hiszpanii (wpisy BORME) dane koncursalne są też na GET /search.
  • Monitorowanie kontrahentów (POST /monitor) obejmuje Polskę i większość pozostałych krajów (nie Francję); alerty zdarzeń zmian w rejestrze dla Polski działają od 14 października 2026.
  • Screening sankcyjny jest w wersji beta.
  • Screening PEP jest w wersji beta i ograniczony do Hiszpanii, bez krewnych i bliskich współpracowników (RCA).
  • Norwegia ma tylko zdarzenia zmian w rejestrze, od 14 października 2026 (bez dziennika urzędowego).

Najczęstsze pytania

Co to jest KYB?
KYB (Know Your Business) to regulowany proces weryfikacji kontrahenta firmowego przed rozpoczęciem współpracy. Zwykle wymaga potwierdzenia istnienia prawnego (rejestr), beneficjentów rzeczywistych, ekspozycji na sankcje i negatywnych informacji medialnych. API Prometiam pokrywa warstwę rejestrową i sankcyjną w jednym zestawie endpointów.

Jakie kraje obejmuje KYB Prometiam?
Hiszpanię (BORME), Francję (BODACC), Wielką Brytanię (Companies House), Irlandię (CRO, poziom firmy), Polskę (KRS, poziom firmy), Norwegię (Brønnøysundregistrene, firmy i osoby), Finlandię (PRH/YTJ), Szwecję (Bolagsverket), Belgię (KBO), Chorwację (Sudski registar), Danię (CVR), Estonię (Äriregister), Słowację (RPO), Szwajcarię (Zefix), Łotwę (Uzņēmumu reģistrs), Cypr (DRCOR), Rumunię (ONRC), Litwę, Kanadę, Australię, Japonię, Izrael, Singapur, Kolumbię, Tajwan, Czechy, Niemcy, Brazylię i Stany Zjednoczone; Finlandia, Szwecja, Belgia, Chorwacja, Dania, Estonia, Słowacja, Szwajcaria, Łotwa, Cypr, Rumunia, Litwa, Kanada, Australia, Japonia, Izrael, Singapur, Kolumbia, Tajwan, Niemcy, Brazylia i Stany Zjednoczone udostępniają wyłącznie dane firm. Użyj ?country=ES|FR|GB|IE|PL|NO|FI|SE|BE|HR|DK|EE|SK|CH|LV|CY|RO|US|LT|CA|AU|JP|IL|SG|CO|TW|BR|CZ|DE|AR|UA|RS|EC|NL|CL|NL|MX na każdym endpoincie.

Czy KYB Prometiam obejmuje screening sankcyjny?
Tak — plan Professional (29,99 €/mies.) obejmuje /sanctions/screen, który porównuje przybliżonym dopasowaniem wobec siedmiu źródeł: skonsolidowanej listy UE, ONZ, OFAC, UK, Australia (DFAT), francuskiego rejestru zamrożeń oraz pełnej US Consolidated Screening List list eksportowych, w jednym wywołaniu. Screening sankcyjny jest w wersji beta.

Czy dla Polski API zwraca zarząd i beneficjentów rzeczywistych (UBO)?
Nie. Dane polskie z KRS są na poziomie firmy: nazwa, numer KRS, adres, forma prawna, status. Prometiam nie udostępnia polskiego składu zarządu, danych z CRBR (Centralny Rejestr Beneficjentów Rzeczywistych) ani z KRZ (Krajowy Rejestr Zadłużonych). Hiszpania, Francja, Wielka Brytania i Norwegia zwracają przez ten sam endpoint obecnych i historycznych członków zarządu; dla brytyjskich spółek dostępny jest też rejestr PSC. Dla polskich kontrahentów screening sankcyjny obejmuje nazwę spółki oraz nazwiska, które poda klient — nie listę oficjalnych członków zarządu. Więcej o strukturze polskiego rejestru: Co to jest KRS?

Czy dane są wystarczająco świeże dla onboardingu w czasie rzeczywistym?
Polski rejestr KRS, hiszpański BORME i francuski BODACC są aktualizowane codziennie z oficjalnych źródeł. Companies House jest aktualizowany comiesięcznym zbiorem plus codzienną aktualizacją delta. /coverage zwraca datę latest_filing dla każdego kraju.

Powiązane