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 API

Pełna dokumentacja tego źródła — parametry, przykłady odpowiedzi, limity i semantyka — jest na osobnej stronie: KRS API.

API białej listy VAT

Pełna dokumentacja tego źródła — parametry, przykłady odpowiedzi, limity i semantyka — jest na osobnej stronie: API białej listy VAT.

API REGON / GUS

Pełna dokumentacja tego źródła — parametry, przykłady odpowiedzi, limity i semantyka — jest na osobnej stronie: API REGON / GUS.

CRBR API

Pełna dokumentacja tego źródła — parametry, przykłady odpowiedzi, limity i semantyka — jest na osobnej stronie: CRBR API.

BZP API

Pełna dokumentacja tego źródła — parametry, przykłady odpowiedzi, limity i semantyka — jest na osobnej stronie: BZP API.

SUDOP API

Pełna dokumentacja tego źródła — parametry, przykłady odpowiedzi, limity i semantyka — jest na osobnej stronie: SUDOP API.

Agregat podmiotu

Pełna dokumentacja tego źródła — parametry, przykłady odpowiedzi, limity i semantyka — jest na osobnej stronie: Agregat podmiotu.

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

Cennik

Ceny netto miesięcznie. Wszystkie źródła są w każdym pakiecie — różnicujemy wolumenem, limitem na sekundę i udziałem świeżych pobrań, nigdy dostępem do danych.

Źródła w każdym pakiecie: KRS, biała lista VAT, REGON/GUS, CEIDG, CRBR, BZP, SUDOP.

Cena roczna z rabatem: Starter 2 030 zł/rok (zamiast 2 388) · Pro 5 090 zł/rok (zamiast 5 988).

Zasady rozliczeń

Pełne brzmienie warunków: regulamin usługi.

Certyfikaty zapytań — bez dopłaty, w granicach pakietu

Każdy pakiet obejmuje certyfikaty z odciskiem HMAC — kryptograficzny dowód, że w danym momencie odpytano rejestr i otrzymano taką odpowiedź. Wartość: audyt, compliance, dowód w sporze.

Certyfikat może zostać wystawiony do każdego rozliczonego zapytania. Nie jest osobno płatny i nie zużywa dodatkowej jednostki. Liczba certyfikatów jest z natury ograniczona liczbą zapytań.

Retencja: certyfikaty są poza standardową retencją (90 dni cache, 400 dni audyt). Po rozwiązaniu umowy pozostają dostępne do pobrania przez 12 miesięcy, potem są usuwane — inaczej baza rośnie bez końca i bez podstawy prawnej.

Świeże pobrania — limit udziałowy, nie mnożnik

fresh=true omija cache i odpytuje rejestr źródłowy. To jedyne miejsce, gdzie klient realnie zużywa cudzy limit.

• Udział w pakiecie: FREE 10%, Starter 20%, Pro 30%.
• Po przekroczeniu udziału zapytania z fresh są degradowane do cache z nagłówkiem X-DS-Freshness: degraded — nie odrzucane. Klient dostaje dane, tylko nie najświeższe.
• Enterprise: udział negocjowany; przy wyższych progach wymagany kontakt techniczny po stronie klienta.

Nadwyżka — z dołu, z twardym sufitem

• Przekroczenie pakietu → nadwyżka naliczana i fakturowana z dołu, miesięcznie.
• Twardy sufit: 3× pakiet. Po osiągnięciu API blokuje zapytania i wysyła alert do klienta i do nas.
• Alerty progowe: 80% i 100% pakietu, potem 200% i 300% (sufit).
• FREE: brak nadwyżki, twardy stop na 250 zapytaniach.

Rabat roczny — −15% za płatność z góry

Płatność za rok z góry obniża cenę pakietu o 15%.

Wszystkie źródła w każdym pakiecie

Różnicujemy wolumenem, limitem na sekundę i udziałem świeżych pobrań — nigdy dostępem do danych. Dzielenie źródeł na pakiety zmusza klienta do kalkulacji i zaciera przekaz.

Redystrybucja — dozwolona od Startera

Klient może udostępniać dane swoim klientom (np. producent ERP w kartotece kontrahenta). FREE jest wyłączone: to pakiet ewaluacyjny.

Piaskownica — darmowa, ale z własnym sufitem

Klucze testowe nie zużywają pakietu i mają osobny limit dzienny. Klucz ds_test_* zwraca zamrożone dane z próbki, nie odpytuje rejestrów i nie zdejmuje jednostek (meta.billed: 0). Obowiązują go własne limity: 500 zapytań na dobę (reset o północy UTC, po przekroczeniu 429 quota_exceeded) i 2 zapytania na sekundę. Stan sufitu w nagłówkach RateLimit-Sandbox-Limit / RateLimit-Sandbox-Remaining.

Integrator ma się uczyć za darmo (tak samo jak darmowe są błędy 400), ale bez sufitu dałoby się na kluczu testowym mieszkać produkcyjnie.

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).

Składając wniosek, potwierdzasz zapoznanie się z regulaminem usługi i cennikiem. Warunki wiążące ustala umowa zawierana przy wydaniu klucza produkcyjnego.

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