Rejestry API

Jedno API do siedmiu polskich rejestrów publicznych. Jedna koperta odpowiedzi, jedno uwierzytelnianie, jeden sposób obsługi błędów — zamiast siedmiu integracji, siedmiu formatów dat i siedmiu sposobów mówienia „nie wiem”.

Pierwsze zapytanie w 5 minut

1. Klucz

Klucz wydajemy ręcznie — złóż wniosek w sekcji Uzyskaj dostęp (albo napisz na kontakt@debtstrike.eu). Dostajesz dwa: ds_test_… (piaskownica, nie rusza rejestrów, nie zużywa kwoty) i ds_live_… (dane produkcyjne). Sekret pokazujemy raz — u nas w bazie jest tylko jego skrót.

2. Zapytanie

curl -s https://api.debtstrike.eu/v1/vat/5252344078 \
  -H "Authorization: Bearer ds_live_TWOJ_KLUCZ"

3. Odpowiedź

{
  "apiVersion": "v1",
  "requestId": "01KYFPKKTXD5ENZ1Q69TYC6PDK",
  "status": "found",
  "subject": {
    "nip": "5252344078", "regon": "140182840", "krs": "0000240611",
    "countryCode": "PL", "resolvedVia": "direct"
  },
  "source": {
    "id": "vat", "name": "Wykaz podatników VAT (biała lista)",
    "authority": "Ministerstwo Finansów", "official": true,
    "endpoint": "https://wl-api.mf.gov.pl/api", "availability": "ga"
  },
  "data": {
    "nip": "5252344078",
    "name": "GOOGLE POLAND SPÓŁKA Z OGRANICZONĄ ODPOWIEDZIALNOŚCIĄ",
    "statusVat": "Czynny",
    "regon": "140182840",
    "krs": "0000240611",
    "accountNumbers": ["61109000040000000143936780"],
    "registrationLegalDate": "2005-10-06"
  },
  "meta": {
    "cache": { "hit": true, "storedAt": "2026-07-26T16:25:17.000Z",
               "expiresAt": "2026-07-27T16:25:17.000Z" },
    "stale": false,
    "billed": 1,
    "attribution": "Źródło: Wykaz podatników VAT (biała lista) (Ministerstwo Finansów), stan na 2026-07-26, …"
  },
  "timestamps": {
    "requestedAt": "2026-07-26T17:12:19.552Z",
    "sourceFetchedAt": "2026-07-26T16:25:17.000Z",
    "validAsOf": "2026-07-26"
  },
  "warnings": []
}

4. Trzy rzeczy, które warto zrozumieć od razu

Uwierzytelnianie

Klucz w nagłówku Authorization, schemat Bearer:

Authorization: Bearer ds_live_eH9vE1TxL6IrfAqU9Xh8Ja0U

Koperta odpowiedzi

Każde źródło odpowiada tą samą strukturą. Zmienia się wyłącznie zawartość data. Dzięki temu obsługę błędów, cache i audytu piszesz raz, a nie siedem razy.

not_found kontra unavailable

To jest miejsce, w którym różnimy się od proxy na rejestry — i jedyna rzecz z tej dokumentacji, którą naprawdę warto przeczytać uważnie.

Tryb degradacji

Gdy rejestr milczy, a mamy dane w cache, zwracamy je z meta.stale = true i meta.degraded.reason. To świadoma decyzja: lepiej oddać wczorajszy odpis z etykietą „wczorajszy”, niż nie oddać nic. Nie udajemy jednak, że są świeże — timestamps.sourceFetchedAt mówi prawdę.

Jak liczymy zapytania

Jedno zapytanie = jedna jednostka pakietu. Nie ma mnożników: ani za źródło, ani za świeżość, ani za certyfikat. Nie musisz nic przeliczać, żeby wiedzieć, ile Ci zostało — meta.billed w każdej odpowiedzi mówi to wprost.

Zasada, z której wynika cała reszta: płacisz za odpowiedź z rejestru, nie za próbę.

Klucze testowe (piaskownica)

Klucze testowe nie zużywają pakietu i mają osobny limit dzienny. Klucz ds_test_ zwraca stałe dane z próbki, nie rusza rejestrów i nie zdejmuje ani jednej jednostki — w kopercie zobaczysz "billed": 0. Obowiązuje go za to własny sufit: 500 zapytań na dobę (do północy UTC) i 2 zapytania na sekundę. Stan sufitu niosą nagłówki RateLimit-Sandbox-Limit i RateLimit-Sandbox-Remaining; po jego przekroczeniu dostajesz 429 quota_exceeded.

Cel jest prosty: integracja ma być darmowa w nauce, ale na kluczu testowym nie da się pracować produkcyjnie — dane w piaskownicy są zamrożone i nieprawdziwe.

Limity i świeżość

Trzy niezależne warstwy. Dwie pierwsze mogą zakończyć się kodem 429. Trzecia — nigdy.

RateLimit-Limit: 20
RateLimit-Remaining: 18
RateLimit-Reset: 4
RateLimit-Quota-Limit: 4000
RateLimit-Quota-Used: 1182
RateLimit-Quota-Remaining: 2818
RateLimit-Quota-Reset: 388800
RateLimit-Fresh-Limit: 800
RateLimit-Fresh-Remaining: 611

Twardy sufit nadwyżki

Po przekroczeniu pakietu zapytania idą na nadwyżkę, rozliczaną z dołu — ale nie w nieskończoność. Sufit to 3× pakiet, po nim API blokuje i wysyła alert. Blokada jest celowa: chroni Cię przed rachunkiem bez dna po błędzie w pętli. Ostrzegamy wcześniej — przy 80% i 100% pakietu, potem przy 200% i 300%.

Świeżość: ?fresh=true

fresh=true pomija cache i idzie do rejestru. Nie kosztuje więcej — ma za to własny udział w pakiecie. Po jego wyczerpaniu zapytanie nie jest odrzucane: obsługujemy je z cache i mówimy o tym wprost.

HTTP/1.1 200 OK
X-DS-Freshness: degraded
RateLimit-Fresh-Remaining: 0

{
  "status": "found",
  "meta": { "billed": 1, "cache": { "hit": true } },
  "timestamps": { "validAsOf": "2026-07-26" },
  "warnings": [
    { "code": "fresh_degraded",
      "message": "Wyczerpany udział świeżych pobrań w pakiecie — odpowiedź pochodzi z cache." }
  ]
}

Błędy

Błędy transportu i autoryzacji zwracamy w formacie RFC 9457 (application/problem+json). Brak danych w rejestrze nie jest błędem — to 200 z status: not_found.

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json

{
  "type": "https://api.debtstrike.eu/errors/invalid-key",
  "title": "Nieprawidłowy lub odwołany klucz API",
  "status": 401,
  "code": "invalid_key",
  "detail": "Nieprawidłowy format klucza API.",
  "requestId": "01KYFPM6DWBAY31GYT46C8FNEF"
}

Wersjonowanie

Wersja siedzi w ścieżce: /v1/…. W obrębie v1 zobowiązujemy się, że:

• możemy dodać pole w data, nową wartość w warnings[].code, nowe źródło i nowy endpoint;
• nie usuniemy istniejącego pola ani nie zmienimy jego znaczenia;
• nie zmienimy wartości status ani kodów błędów code.

Zmiana łamiąca kontrakt oznacza /v2 wystawione obok /v1, nie podmianę. Twój parser ma ignorować nieznane pola — to jedyne założenie, o które prosimy.

KRS

Odpis z Krajowego Rejestru Sądowego (Ministerstwo Sprawiedliwości).

Zawartość data: krs, nip, regon, name, legalForm, register, address, contact, pkd, shareCapital, representation, flags, registrationDate, lastEntryDate, lastFinancialStatement.

Przykład: podmiotu nie ma w rejestrze

{
  "status": "not_found",
  "subject": { "nip": null, "regon": null, "krs": "1132998955",
               "countryCode": "PL", "resolvedVia": "direct" },
  "data": null,
  "meta": { "cache": { "hit": false }, "stale": false, "billed": 1 },
  "timestamps": { "validAsOf": null },
  "warnings": []
}

Limity: MS nie publikuje limitów ani SLA dla API KRS. Przyjęliśmy własny ostrożny sufit 2000 zapytań na dobę i go mierzymy.

Biała lista VAT

Status podatnika

data: statusVat (Czynny/Zwolniony/Niezarejestrowany), name, regon, krs, accountNumbers[], registrationLegalDate, removalDate, restorationDate, hasVirtualAccounts, adresy.

Weryfikacja rachunku bankowego

Odpowiada na pytanie „czy ten rachunek należał do tego podatnika tego dnia” — czyli na pytanie, które decyduje o odpowiedzialności solidarnej i o kosztach uzyskania przychodu. account to NRB (26 cyfr) albo IBAN.

Limity MF, których nie musisz znać, bo trzymamy je po swojej stronie: 100 zapytań wyszukujących na dobę na adres IP (do 30 podmiotów w zapytaniu) i 5000 podmiotów metodą sprawdzającą. Przekroczenie blokuje adres IP do północy — razem z wyszukiwarką WWW.

REGON / GUS (fallback CEIDG)

Tożsamość, adres i PKD z rejestru REGON (GUS BIR). Dla jednoosobowych działalności, których BIR nie zwraca w komplecie, przewidziany jest fallback na CEIDG.

data: regon, nip, krs, name, entityType, active, address, pkd, endDate, provider (gus_bir albo ceidg).

Kody PKD normalizujemy do jednego formatu (19.20.Z) niezależnie od tego, że GUS oddaje je jako 1920Z, a KRS z kropkami. To jeden z powodów, dla których warto brać dane przez jedno API zamiast z siedmiu.

CRBR — beneficjenci rzeczywiści

Beneficjenci rzeczywiści z oficjalnej bramki SOAP Ministerstwa Finansów — nie z nieoficjalnego backendu portalu.

CRBR jest świadomie poza agregatem /v1/subjects — dane o osobach fizycznych pobieramy tylko wtedy, gdy o nie wprost poprosisz. Agregat mówi o tym jawnie w polu notIncluded.

BZP — zamówienia publiczne

Postępowania, w których podmiot wystąpił jako wykonawca albo zamawiający. Parametr limit (domyślnie 50, maksimum 200) ogranicza liczbę zwróconych ogłoszeń.

{
  "status": "found",
  "data": {
    "summary": { "asContractor": 0, "asOrganization": 2,
                 "latestPublicationDate": "2026-07-02T07:13:35.000Z" },
    "coverage": { "from": "2025-07-26T05:15:20.000Z",
                  "to": "2026-07-26T08:34:58.000Z",
                  "noticesIndexed": 545503 },
    "notices": [
      {
        "noticeNumber": "2026/BZP 00318648/01",
        "noticeType": "ContractNotice",
        "publicationDate": "2026-07-02T07:13:35.000Z",
        "role": "organization",
        "orderObject": "„Przebudowa wraz z modernizacją Szkoły Podstawowej…”",
        "cpvCode": "45000000-7 (Roboty budowlane)",
        "organizationName": "Gmina Pyrzyce"
      }
    ]
  },
  "warnings": [
    { "code": "bzp_coverage",
      "message": "Odpowiedź obejmuje ogłoszenia z zakresu 2025-07-26 – 2026-07-26. Poza tym zakresem nie wiemy…" }
  ]
}

Szukamy po wszystkich znanych identyfikatorach podmiotu (NIP, KRS, REGON), bo zamawiający wpisują je zamiennie w jedno pole — na realnej próbce 19% wykonawców miało tam coś innego niż NIP. Bez tego wyszukiwanie gubiłoby co piątego wykonawcę.

SUDOP — pomoc publiczna i de minimis

Zdarzenia pomocowe zarejestrowane przez UOKiK: kto udzielił, kiedy, w jakiej formie i za ile (PLN oraz EUR według przelicznika organu). Parametr limit (domyślnie 200, maksimum 1000) ogranicza listę events.

{
  "status": "found",
  "data": {
    "totalEvents": 296, "returnedEvents": 2, "truncated": true,
    "summary": {
      "firstAidOn": "2017-01-17", "lastAidOn": "2026-07-20",
      "totalGrossPln": 3106694545.94, "totalGrossEur": 713913825.44,
      "deMinimisEvents": 1
    },
    "deMinimis": {
      "pools": [], "windowFrom": "2023-07-26", "windowTo": "2026-07-26",
      "totalGrantedEur": 0,
      "note": "Wyliczenie ORIENTACYJNE, nie zastępuje zaświadczeń o pomocy de minimis…"
    },
    "events": [
      {
        "grantedOn": "2026-07-20",
        "grantorName": "Polskie Sieci Elektroenergetyczne S.A.",
        "measureName": "Polski mechanizm rynku mocy",
        "legalBasis": "ustawa z dnia 8 grudnia 2017 r. o rynku mocy",
        "formName": "dotacja lub inne bezzwrotne świadczenie",
        "value": { "nominalPln": 108098.97, "grossPln": 108098.97, "grossEur": 24931.15 },
        "isDeMinimis": false, "deMinimisPool": null
      }
    ]
  }
}

De minimis — co liczymy, a czego nie obiecujemy

Sekcja data.deMinimis sumuje pomoc w ruchomym oknie trzech lat, oddzielnie dla każdej puli (e1, e1t, e1c, e2, e2c), bo pule mają różne limity i różne podstawy prawne — od 100 tys. EUR dla transportu drogowego towarów po 750 tys. EUR dla usług w ogólnym interesie gospodarczym.

Sumy zawsze pochodzą z kompletu zdarzeń, także gdy lista events została przycięta parametrem limit — wtedy truncated = true i ostrzeżenie sudop_truncated. Przycięcie listy nigdy nie zafałszuje podsumowania.

Agregat podmiotu

Tożsamość + status VAT + dane KRS jednym zapytaniem. Zwraca „kopertę kopert”: pole sources zawiera pełne koperty poszczególnych źródeł, więc każde z nich ma własny status i własne timestamps.

Pole completeness mówi, ile źródeł odpowiedziało, a notIncluded — które źródła z oferty świadomie pominięto i dlaczego. Dziś są to CRBR (minimalizacja danych osobowych), BZP i SUDOP (osobne, cięższe zapytania).

Zapytania zbiorcze

Status VAT dla wielu NIP-ów

curl -s https://api.debtstrike.eu/v1/batch/vat \
  -H "Authorization: Bearer ds_live_TWOJ_KLUCZ" \
  -H "Content-Type: application/json" \
  -d '{"nips":["5252344078","7740001454"],"date":"2026-07-26"}'

Maksimum 30 NIP-ów. MF liczy to jako jedno zapytanie i my też — koszt 1 jednostki niezależnie od liczby podmiotów. Powyżej 30 pozycji: 413.

Weryfikacja wielu rachunków

{
  "pairs": [
    { "nip": "5252344078", "account": "61109000040000000143936780" }
  ],
  "date": "2026-07-26"
}

Maksimum 200 par. Odpowiada wyłącznie z naszego indeksu pliku płaskiego, więc nie zużywa limitów MF — koszt 1 jednostki.

Gdy indeks nie obejmuje wskazanego dnia, dostajesz 422 index_does_not_cover_date zamiast cichego zgadywania. Aktualny dzień indeksu sprawdzisz w katalogu źródeł.

Certyfikaty zapytań

Dodaj ?certificate=true do dowolnego zapytania, a zamrozimy odpowiedź i policzymy jej odcisk HMAC. Dostajesz identyfikator, adres i sam odcisk w meta.certificate.

Do czego to służy: dowód, że o tej godzinie rejestr odpowiedział dokładnie tak. Przydaje się w audycie, w sporze z kontrahentem i wszędzie tam, gdzie trzeba wykazać należytą staranność — np. że w dniu przelewu rachunek widniał na białej liście.

Certyfikat wystawiamy wyłącznie dla odpowiedzi ze statusem found; przy not_found dostajesz ostrzeżenie certificate_skipped. Wymagany jest zakres certificate przy kluczu.

Jak długo żyją

Certyfikaty są poza retencją, która po 90 dniach czyści cache, a po 400 dniach audyt — w trakcie trwania umowy nie usuwa ich nic. Po jej rozwiązaniu pozostają dostępne do pobrania przez 12 miesięcy, a potem są usuwane. To celowy kompromis: „na zawsze” nie miałoby podstawy prawnej ani końca, a skasowanie ich z dnia na dzień zniszczyłoby dowody, na których klient oparł swój audyt.

Katalog źródeł

Lista źródeł z ich dostępnością, organem prowadzącym, stanem indeksów (m.in. na jaki dzień mamy plik płaski VAT i jaki zakres pokrywa indeks BZP). Pytaj o to zamiast zaszywać stałe w kodzie — dodanie źródła zobaczysz tu pierwszy.

Stan usługi

Pierwszy to liveness. Drugi mówi, na jaki dzień mamy indeks pliku płaskiego i ile wpisów zawiera — 503 oznacza brak indeksu, czyli że weryfikacja rachunków idzie przez API MF (wolniej i za budżetem, ale działa).

Kontrakt OpenAPI

Pełny kontrakt w OpenAPI 3.1, dostępny bez uwierzytelniania — bo klient ma móc wygenerować sobie SDK, nie pytając nas o nic. Przykłady w kontrakcie pochodzą z prawdziwych odpowiedzi produkcji, nie z wyobraźni.

# klient TypeScript
npx openapi-typescript https://api.debtstrike.eu/v1/openapi.json -o registry-api.d.ts

# klient dowolny (Java, C#, Go, Python…)
openapi-generator-cli generate -i https://api.debtstrike.eu/v1/openapi.json \
  -g java -o ./registry-api-client

Uzyskaj dostęp

Klucze wydajemy ręcznie, po rozmowie — ten formularz nie zakłada konta i nie zwraca klucza. Zbieramy z niego dokładnie to, co i tak musielibyśmy dopytać mailem: kto pyta, do czego i w jakiej skali. Dostaniesz parę ds_test_… (piaskownica, darmowa) i ds_live_… (dane produkcyjne).

Wolisz mailem? kontakt@debtstrike.eu — napisz to samo własnymi słowami.