{ "openapi": "3.1.0", "info": { "title": "DebtStrike Rejestry API", "version": "1.0.0", "description": "Jedno API do polskich rejestrów publicznych: **KRS**, **biała lista VAT**, **REGON/GUS** (z fallbackiem CEIDG), **CRBR**, **BZP** i **SUDOP**. Jedna koperta odpowiedzi dla wszystkich źródeł, limity rejestrów trzymane po naszej stronie, audytowalne znaczniki czasu i gotowa atrybucja wymagana ustawą o otwartych danych.\n\n### Czym to się różni od proxy na rejestry\n\n**Rozróżniamy „rejestr odpowiedział, że nie ma” od „rejestr nie odpowiedział”.** Pierwsze to `status: not_found` — fakt, na którym możesz oprzeć decyzję. Drugie to `status: unavailable` — brak wiedzy, na którym opierać decyzji NIE WOLNO. Zwykłe proxy zwraca w obu przypadkach pustkę i zostawia klienta z pytaniem, co ona znaczy.\n\nDlatego HTTP `200` opisuje wyłącznie transport: „zapytanie dotarło i zostało obsłużone”. O danych mówi pole `status` w kopercie.\n\n### Jak liczymy zapytania\n\n**Jedno zapytanie = jedna jednostka pakietu.** Bez mnożników — za źródło, za świeżość, za certyfikat. Płacisz za ODPOWIEDŹ REJESTRU, nie za próbę:\n\n- `found` i `not_found` → **1** (brak wpisu to też informacja, i to kosztowała nas tak samo),\n- `unavailable` → **0** (nie obciążamy za cudzą awarię),\n- błędy `4xx`, `5xx` i `429` → **0** (nauka integracji jest darmowa),\n- zapytanie o N źródeł (agregat, paczka) → **N**,\n- certyfikat → **0** dodatkowo,\n- zapytanie kluczem testowym `ds_test_` → **0** (klucze testowe nie zużywają pakietu i mają osobny limit dzienny: 500/dobę, 2 zapytania/s).\n\nKażda odpowiedź niesie `meta.billed` i nagłówki `RateLimit-Quota-*`, więc stanu pakietu nie trzeba nigdzie doliczać ani zgadywać.\n\n### Wersjonowanie\n\nWersja siedzi w ścieżce (`/v1`). W obrębie `v1` **dodajemy** pola i wartości `warnings`, ale nie usuwamy pól ani nie zmieniamy znaczenia istniejących. Kody błędów (`code`) są stabilne. Zmiana łamiąca kontrakt = `/v2` obok, nie podmiana `/v1`.", "contact": { "name": "DebtStrike", "email": "kontakt@debtstrike.eu" }, "license": { "name": "Warunki korzystania z Rejestry API", "url": "https://debtstrike.eu/regulamin-api" } }, "servers": [ { "url": "https://api.debtstrike.eu" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Podmiot", "description": "Agregat i katalog źródeł — punkt wejścia dla większości integracji." }, { "name": "KRS", "description": "Krajowy Rejestr Sądowy (Ministerstwo Sprawiedliwości)." }, { "name": "VAT", "description": "Biała lista podatników VAT (Ministerstwo Finansów) — status podmiotu i weryfikacja rachunków." }, { "name": "REGON", "description": "Rejestr REGON / GUS BIR, z fallbackiem na CEIDG dla JDG." }, { "name": "CRBR", "description": "Centralny Rejestr Beneficjentów Rzeczywistych." }, { "name": "BZP", "description": "Biuletyn Zamówień Publicznych — własny indeks ogłoszeń." }, { "name": "SUDOP", "description": "Pomoc publiczna i de minimis (UOKiK)." }, { "name": "Certyfikaty", "description": "Dowód treści odpowiedzi (płatny dodatek)." }, { "name": "Stan usługi", "description": "Endpointy bez klucza — do monitoringu." }, { "name": "Dostęp", "description": "Wniosek o klucz. Bez uwierzytelnienia — z definicji składa go ktoś, kto klucza nie ma." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Klucz API: `Authorization: Bearer ds_live_…`" } }, "schemas": { "RegistryEnvelope": { "type": "object", "required": [ "apiVersion", "requestId", "status", "subject", "source", "data", "meta", "timestamps", "warnings" ], "properties": { "apiVersion": { "type": "string", "enum": ["v1"] }, "requestId": { "type": "string", "description": "Identyfikator zapytania — do reklamacji i audytu." }, "status": { "type": "string", "enum": [ "found", "not_found", "unavailable", "forbidden", "invalid_input" ], "description": "Stan DANYCH, nie transportu. `not_found` = rejestr odpowiedział, że podmiotu nie ma. `unavailable` = rejestr nie odpowiedział (nie wiemy)." }, "subject": { "type": "object", "properties": { "nip": { "type": ["string", "null"] }, "regon": { "type": ["string", "null"] }, "krs": { "type": ["string", "null"] }, "countryCode": { "type": "string", "enum": ["PL"] }, "resolvedVia": { "type": ["string", "null"], "enum": ["direct", "mf_whitelist", "gus_bir", null] } } }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "authority": { "type": "string" }, "official": { "type": "boolean" }, "endpoint": { "type": "string" }, "availability": { "type": "string", "enum": ["ga", "beta", "planned"] } } }, "data": { "type": ["object", "null"], "description": "Dane źródła; `null` zawsze, gdy `status` ≠ `found`." }, "meta": { "type": "object", "properties": { "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "storedAt": { "type": ["string", "null"], "format": "date-time" }, "expiresAt": { "type": ["string", "null"], "format": "date-time" } } }, "stale": { "type": "boolean", "description": "true = rejestr niedostępny, zwrócono ostatnie znane dane." }, "degraded": { "type": "object", "properties": { "reason": { "type": "string" } } }, "billed": { "type": "integer", "enum": [0, 1], "description": "Ile jednostek pakietu zdjęto za tę odpowiedź. Zawsze 1 (`found` i `not_found`) albo 0 (`unavailable` oraz źródła spoza SLA). Mnożników nie ma: jedno zapytanie = jedna jednostka, niezależnie od źródła, świeżości i certyfikatu." }, "attribution": { "type": "string", "description": "Gotowa nota o źródle (wymóg ustawy o otwartych danych)." }, "certificate": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "digest": { "type": "string" } } } } }, "timestamps": { "type": "object", "properties": { "requestedAt": { "type": "string", "format": "date-time" }, "sourceFetchedAt": { "type": ["string", "null"], "format": "date-time" }, "validAsOf": { "type": ["string", "null"], "description": "Dzień/moment ważności danych w rejestrze." } } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "Problem": { "type": "object", "description": "Błąd w formacie RFC 9457 (`application/problem+json`). Uwaga: dotyczy wyłącznie błędów TRANSPORTU i autoryzacji. Brak danych w rejestrze NIE jest błędem — wraca jako `200` z kopertą i `status: not_found` albo `unavailable`.", "required": ["type", "title", "status", "code", "requestId"], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string", "enum": [ "invalid_key", "key_revoked", "ip_not_allowed", "source_not_in_plan", "invalid_identifier", "rate_limited", "quota_exceeded", "payload_too_large", "index_does_not_cover_date", "unknown_endpoint", "internal_error" ], "description": "Kod maszynowy — stabilny w obrębie wersji API." }, "detail": { "type": "string" }, "requestId": { "type": "string", "description": "Podaj go w reklamacji — po nim odtworzymy zapytanie z audytu." } } } } }, "paths": { "/v1/sources": { "get": { "tags": ["Podmiot"], "operationId": "listSources", "summary": "Katalog źródeł, ich dostępność i koszt", "responses": { "200": { "description": "Katalog" }, "400": { "description": "Nieprawidłowy identyfikator", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Brak lub zły klucz API", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Źródło spoza planu klucza", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Limit chwilowy (`rate_limited`) albo pakiet: wyczerpany w planie bez nadwyżki lub twardy sufit 3× pakiet (`quota_exceeded`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/subjects/{identifier}": { "get": { "tags": ["Podmiot"], "operationId": "getSubject", "summary": "Agregat: tożsamość + VAT + KRS jednym zapytaniem", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "NIP, KRS albo REGON" }, { "name": "fresh", "in": "query", "schema": { "type": "boolean" }, "description": "Pomija cache i pyta rejestr. NIE kosztuje więcej — jedno zapytanie to zawsze jedna jednostka. Ma za to własny udział w pakiecie (nagłówki `RateLimit-Fresh-*`); po jego wyczerpaniu odpowiedź wraca z cache z nagłówkiem `X-DS-Freshness: degraded` i ostrzeżeniem `fresh_degraded` — nigdy błędem. Ograniczenie chroni rejestry publiczne przed przeciążeniem, dlatego degradujemy zamiast blokować." } ], "responses": { "200": { "description": "Koperta kopert" }, "400": { "description": "Nieprawidłowy identyfikator", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Brak lub zły klucz API", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Źródło spoza planu klucza", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Limit chwilowy (`rate_limited`) albo pakiet: wyczerpany w planie bez nadwyżki lub twardy sufit 3× pakiet (`quota_exceeded`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/krs/{identifier}": { "get": { "tags": ["KRS"], "operationId": "getKrsExcerpt", "summary": "Odpis KRS (aktualny lub pełny)", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "NIP, KRS albo REGON — most NIP→KRS po naszej stronie" }, { "name": "scope", "in": "query", "schema": { "type": "string", "enum": ["aktualny", "pelny"] } }, { "name": "fresh", "in": "query", "schema": { "type": "boolean" }, "description": "Pomija cache i pyta rejestr. NIE kosztuje więcej — jedno zapytanie to zawsze jedna jednostka. Ma za to własny udział w pakiecie (nagłówki `RateLimit-Fresh-*`); po jego wyczerpaniu odpowiedź wraca z cache z nagłówkiem `X-DS-Freshness: degraded` i ostrzeżeniem `fresh_degraded` — nigdy błędem. Ograniczenie chroni rejestry publiczne przed przeciążeniem, dlatego degradujemy zamiast blokować." }, { "name": "certificate", "in": "query", "schema": { "type": "boolean" }, "description": "Wystawia certyfikat zapytania — zamrożoną kopertę z odciskiem HMAC, czyli dowód, że o tej godzinie rejestr odpowiedział dokładnie tak. Wymaga zakresu `certificate` przy kluczu. BEZ DOPŁATY w każdym pakiecie i bez osobnej jednostki — to ten sam, już rozliczony fakt z rejestru, tylko zamrożony i podpisany. Certyfikaty są poza retencją 90 dni; po rozwiązaniu umowy pozostają do pobrania przez 12 miesięcy." } ], "responses": { "200": { "description": "Koperta z danymi KRS albo `status: not_found`", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Pojemność wiadra (burst) dla tego klucza." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Ile żetonów zostało w tej chwili." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Za ile sekund wiadro będzie pełne." }, "RateLimit-Quota-Limit": { "schema": { "type": "integer" }, "description": "Pakiet miesięczny w zapytaniach." }, "RateLimit-Quota-Used": { "schema": { "type": "integer" }, "description": "Zapytania rozliczone w bieżącym okresie." }, "RateLimit-Quota-Remaining": { "schema": { "type": "integer" }, "description": "Ile zapytań zostało do końca pakietu. Po zejściu do zera plan z nadwyżką pracuje dalej (do twardego sufitu 3× pakiet), plan FREE zwraca `429 quota_exceeded`." }, "RateLimit-Quota-Reset": { "schema": { "type": "integer" }, "description": "Za ile sekund zaczyna się nowy okres rozliczeniowy (miesiąc UTC)." }, "RateLimit-Fresh-Limit": { "schema": { "type": "integer" }, "description": "Ile świeżych pobrań (`fresh=true`) mieści się w pakiecie." }, "RateLimit-Fresh-Remaining": { "schema": { "type": "integer" }, "description": "Ile świeżych pobrań zostało w bieżącym okresie." }, "RateLimit-Sandbox-Limit": { "schema": { "type": "integer" }, "description": "Tylko dla kluczy `ds_test_*`: dzienny sufit piaskownicy. Klucze testowe nie zużywają pakietu, ale mają własny limit — po jego przekroczeniu `429` do północy UTC." }, "RateLimit-Sandbox-Remaining": { "schema": { "type": "integer" }, "description": "Ile zapytań piaskownicy zostało do końca doby (UTC)." }, "X-DS-Freshness": { "schema": { "type": "string", "enum": ["fresh", "degraded"] }, "description": "Obecny tylko przy `fresh=true`. `fresh` = poszliśmy do rejestru. `degraded` = udział świeżych pobrań wyczerpany, odpowiedź pochodzi z cache (200, nie błąd) — patrz ostrzeżenie `fresh_degraded` w kopercie." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistryEnvelope" }, "example": { "apiVersion": "v1", "requestId": "01KYFPM6DWBAY31GYT46C8FNEF", "status": "not_found", "subject": { "nip": null, "regon": null, "krs": "1132998955", "countryCode": "PL", "resolvedVia": "direct" }, "source": { "id": "krs", "name": "Krajowy Rejestr Sądowy", "authority": "Ministerstwo Sprawiedliwości", "official": true, "endpoint": "https://api-krs.ms.gov.pl/api/krs", "availability": "ga" }, "data": null, "meta": { "cache": { "hit": false }, "stale": false, "billed": 1 }, "timestamps": { "requestedAt": "2026-07-26T17:12:20.101Z", "sourceFetchedAt": "2026-07-26T17:12:20.400Z", "validAsOf": null }, "warnings": [] } } } }, "400": { "description": "Nieprawidłowy identyfikator", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Brak lub zły klucz API", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Źródło spoza planu klucza", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Limit chwilowy (`rate_limited`) albo pakiet: wyczerpany w planie bez nadwyżki lub twardy sufit 3× pakiet (`quota_exceeded`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/vat/{nip}": { "get": { "tags": ["VAT"], "operationId": "getVatStatus", "summary": "Status VAT na dzień (biała lista)", "parameters": [ { "name": "nip", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Domyślnie dziś" }, { "name": "fresh", "in": "query", "schema": { "type": "boolean" }, "description": "Pomija cache i pyta rejestr. NIE kosztuje więcej — jedno zapytanie to zawsze jedna jednostka. Ma za to własny udział w pakiecie (nagłówki `RateLimit-Fresh-*`); po jego wyczerpaniu odpowiedź wraca z cache z nagłówkiem `X-DS-Freshness: degraded` i ostrzeżeniem `fresh_degraded` — nigdy błędem. Ograniczenie chroni rejestry publiczne przed przeciążeniem, dlatego degradujemy zamiast blokować." }, { "name": "certificate", "in": "query", "schema": { "type": "boolean" }, "description": "Wystawia certyfikat zapytania — zamrożoną kopertę z odciskiem HMAC, czyli dowód, że o tej godzinie rejestr odpowiedział dokładnie tak. Wymaga zakresu `certificate` przy kluczu. BEZ DOPŁATY w każdym pakiecie i bez osobnej jednostki — to ten sam, już rozliczony fakt z rejestru, tylko zamrożony i podpisany. Certyfikaty są poza retencją 90 dni; po rozwiązaniu umowy pozostają do pobrania przez 12 miesięcy." } ], "responses": { "200": { "description": "Koperta z danymi VAT", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Pojemność wiadra (burst) dla tego klucza." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Ile żetonów zostało w tej chwili." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Za ile sekund wiadro będzie pełne." }, "RateLimit-Quota-Limit": { "schema": { "type": "integer" }, "description": "Pakiet miesięczny w zapytaniach." }, "RateLimit-Quota-Used": { "schema": { "type": "integer" }, "description": "Zapytania rozliczone w bieżącym okresie." }, "RateLimit-Quota-Remaining": { "schema": { "type": "integer" }, "description": "Ile zapytań zostało do końca pakietu. Po zejściu do zera plan z nadwyżką pracuje dalej (do twardego sufitu 3× pakiet), plan FREE zwraca `429 quota_exceeded`." }, "RateLimit-Quota-Reset": { "schema": { "type": "integer" }, "description": "Za ile sekund zaczyna się nowy okres rozliczeniowy (miesiąc UTC)." }, "RateLimit-Fresh-Limit": { "schema": { "type": "integer" }, "description": "Ile świeżych pobrań (`fresh=true`) mieści się w pakiecie." }, "RateLimit-Fresh-Remaining": { "schema": { "type": "integer" }, "description": "Ile świeżych pobrań zostało w bieżącym okresie." }, "RateLimit-Sandbox-Limit": { "schema": { "type": "integer" }, "description": "Tylko dla kluczy `ds_test_*`: dzienny sufit piaskownicy. Klucze testowe nie zużywają pakietu, ale mają własny limit — po jego przekroczeniu `429` do północy UTC." }, "RateLimit-Sandbox-Remaining": { "schema": { "type": "integer" }, "description": "Ile zapytań piaskownicy zostało do końca doby (UTC)." }, "X-DS-Freshness": { "schema": { "type": "string", "enum": ["fresh", "degraded"] }, "description": "Obecny tylko przy `fresh=true`. `fresh` = poszliśmy do rejestru. `degraded` = udział świeżych pobrań wyczerpany, odpowiedź pochodzi z cache (200, nie błąd) — patrz ostrzeżenie `fresh_degraded` w kopercie." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistryEnvelope" }, "example": { "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, pozyskano 2026-07-26, dane przetworzone technicznie (normalizacja nazw pól i formatów), bez zmiany treści." }, "timestamps": { "requestedAt": "2026-07-26T17:12:19.552Z", "sourceFetchedAt": "2026-07-26T16:25:17.000Z", "validAsOf": "2026-07-26" }, "warnings": [] } } } }, "400": { "description": "Nieprawidłowy identyfikator", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Brak lub zły klucz API", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Źródło spoza planu klucza", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Limit chwilowy (`rate_limited`) albo pakiet: wyczerpany w planie bez nadwyżki lub twardy sufit 3× pakiet (`quota_exceeded`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/vat/{nip}/bank-account/{account}": { "get": { "tags": ["VAT"], "operationId": "verifyBankAccount", "summary": "Czy rachunek należy do podatnika (weryfikacja przelewu)", "description": "Potwierdzenia pochodzą z dziennego pliku płaskiego MF, gdy indeks obejmuje wskazany dzień (`data.provider = \"flat_file\"`, brak zużycia limitów rejestru). Brak potwierdzenia w pliku NIE jest odpowiedzią negatywną — wtedy pytamy API MF (`data.provider = \"wl_api\"`), bo tylko rejestr może rozstrzygnąć m.in. rachunki wirtualne.", "parameters": [ { "name": "nip", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account", "in": "path", "required": true, "schema": { "type": "string" }, "description": "NRB (26 cyfr) lub IBAN" }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "certificate", "in": "query", "schema": { "type": "boolean" }, "description": "Wystawia certyfikat zapytania — zamrożoną kopertę z odciskiem HMAC, czyli dowód, że o tej godzinie rejestr odpowiedział dokładnie tak. Wymaga zakresu `certificate` przy kluczu. BEZ DOPŁATY w każdym pakiecie i bez osobnej jednostki — to ten sam, już rozliczony fakt z rejestru, tylko zamrożony i podpisany. Certyfikaty są poza retencją 90 dni; po rozwiązaniu umowy pozostają do pobrania przez 12 miesięcy." } ], "responses": { "200": { "description": "Koperta z wynikiem weryfikacji", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Pojemność wiadra (burst) dla tego klucza." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Ile żetonów zostało w tej chwili." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Za ile sekund wiadro będzie pełne." }, "RateLimit-Quota-Limit": { "schema": { "type": "integer" }, "description": "Pakiet miesięczny w zapytaniach." }, "RateLimit-Quota-Used": { "schema": { "type": "integer" }, "description": "Zapytania rozliczone w bieżącym okresie." }, "RateLimit-Quota-Remaining": { "schema": { "type": "integer" }, "description": "Ile zapytań zostało do końca pakietu. Po zejściu do zera plan z nadwyżką pracuje dalej (do twardego sufitu 3× pakiet), plan FREE zwraca `429 quota_exceeded`." }, "RateLimit-Quota-Reset": { "schema": { "type": "integer" }, "description": "Za ile sekund zaczyna się nowy okres rozliczeniowy (miesiąc UTC)." }, "RateLimit-Fresh-Limit": { "schema": { "type": "integer" }, "description": "Ile świeżych pobrań (`fresh=true`) mieści się w pakiecie." }, "RateLimit-Fresh-Remaining": { "schema": { "type": "integer" }, "description": "Ile świeżych pobrań zostało w bieżącym okresie." }, "RateLimit-Sandbox-Limit": { "schema": { "type": "integer" }, "description": "Tylko dla kluczy `ds_test_*`: dzienny sufit piaskownicy. Klucze testowe nie zużywają pakietu, ale mają własny limit — po jego przekroczeniu `429` do północy UTC." }, "RateLimit-Sandbox-Remaining": { "schema": { "type": "integer" }, "description": "Ile zapytań piaskownicy zostało do końca doby (UTC)." }, "X-DS-Freshness": { "schema": { "type": "string", "enum": ["fresh", "degraded"] }, "description": "Obecny tylko przy `fresh=true`. `fresh` = poszliśmy do rejestru. `degraded` = udział świeżych pobrań wyczerpany, odpowiedź pochodzi z cache (200, nie błąd) — patrz ostrzeżenie `fresh_degraded` w kopercie." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistryEnvelope" } } } }, "400": { "description": "Nieprawidłowy identyfikator", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Brak lub zły klucz API", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Źródło spoza planu klucza", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Limit chwilowy (`rate_limited`) albo pakiet: wyczerpany w planie bez nadwyżki lub twardy sufit 3× pakiet (`quota_exceeded`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/regon/{identifier}": { "get": { "tags": ["REGON"], "operationId": "getRegonEntity", "summary": "Tożsamość, adres i PKD (GUS BIR, fallback CEIDG)", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fresh", "in": "query", "schema": { "type": "boolean" }, "description": "Pomija cache i pyta rejestr. NIE kosztuje więcej — jedno zapytanie to zawsze jedna jednostka. Ma za to własny udział w pakiecie (nagłówki `RateLimit-Fresh-*`); po jego wyczerpaniu odpowiedź wraca z cache z nagłówkiem `X-DS-Freshness: degraded` i ostrzeżeniem `fresh_degraded` — nigdy błędem. Ograniczenie chroni rejestry publiczne przed przeciążeniem, dlatego degradujemy zamiast blokować." }, { "name": "certificate", "in": "query", "schema": { "type": "boolean" }, "description": "Wystawia certyfikat zapytania — zamrożoną kopertę z odciskiem HMAC, czyli dowód, że o tej godzinie rejestr odpowiedział dokładnie tak. Wymaga zakresu `certificate` przy kluczu. BEZ DOPŁATY w każdym pakiecie i bez osobnej jednostki — to ten sam, już rozliczony fakt z rejestru, tylko zamrożony i podpisany. Certyfikaty są poza retencją 90 dni; po rozwiązaniu umowy pozostają do pobrania przez 12 miesięcy." } ], "responses": { "200": { "description": "Koperta z danymi REGON", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Pojemność wiadra (burst) dla tego klucza." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Ile żetonów zostało w tej chwili." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Za ile sekund wiadro będzie pełne." }, "RateLimit-Quota-Limit": { "schema": { "type": "integer" }, "description": "Pakiet miesięczny w zapytaniach." }, "RateLimit-Quota-Used": { "schema": { "type": "integer" }, "description": "Zapytania rozliczone w bieżącym okresie." }, "RateLimit-Quota-Remaining": { "schema": { "type": "integer" }, "description": "Ile zapytań zostało do końca pakietu. Po zejściu do zera plan z nadwyżką pracuje dalej (do twardego sufitu 3× pakiet), plan FREE zwraca `429 quota_exceeded`." }, "RateLimit-Quota-Reset": { "schema": { "type": "integer" }, "description": "Za ile sekund zaczyna się nowy okres rozliczeniowy (miesiąc UTC)." }, "RateLimit-Fresh-Limit": { "schema": { "type": "integer" }, "description": "Ile świeżych pobrań (`fresh=true`) mieści się w pakiecie." }, "RateLimit-Fresh-Remaining": { "schema": { "type": "integer" }, "description": "Ile świeżych pobrań zostało w bieżącym okresie." }, "RateLimit-Sandbox-Limit": { "schema": { "type": "integer" }, "description": "Tylko dla kluczy `ds_test_*`: dzienny sufit piaskownicy. Klucze testowe nie zużywają pakietu, ale mają własny limit — po jego przekroczeniu `429` do północy UTC." }, "RateLimit-Sandbox-Remaining": { "schema": { "type": "integer" }, "description": "Ile zapytań piaskownicy zostało do końca doby (UTC)." }, "X-DS-Freshness": { "schema": { "type": "string", "enum": ["fresh", "degraded"] }, "description": "Obecny tylko przy `fresh=true`. `fresh` = poszliśmy do rejestru. `degraded` = udział świeżych pobrań wyczerpany, odpowiedź pochodzi z cache (200, nie błąd) — patrz ostrzeżenie `fresh_degraded` w kopercie." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistryEnvelope" } } } }, "400": { "description": "Nieprawidłowy identyfikator", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Brak lub zły klucz API", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Źródło spoza planu klucza", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Limit chwilowy (`rate_limited`) albo pakiet: wyczerpany w planie bez nadwyżki lub twardy sufit 3× pakiet (`quota_exceeded`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/batch/vat": { "post": { "tags": ["VAT"], "operationId": "batchVatStatus", "summary": "Status VAT dla maksymalnie 30 NIP-ów (jedno zapytanie do rejestru)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["nips"], "properties": { "nips": { "type": "array", "maxItems": 30, "items": { "type": "string" } }, "date": { "type": "string", "format": "date" } } } } } }, "responses": { "200": { "description": "Lista kopert + lista odrzuconych identyfikatorów" }, "400": { "description": "Nieprawidłowy identyfikator", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Brak lub zły klucz API", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Źródło spoza planu klucza", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "Więcej niż 30 pozycji" }, "429": { "description": "Limit chwilowy (`rate_limited`) albo pakiet: wyczerpany w planie bez nadwyżki lub twardy sufit 3× pakiet (`quota_exceeded`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/bzp/{nip}": { "get": { "tags": ["BZP"], "operationId": "getPublicProcurement", "summary": "Postępowania publiczne, w których podmiot wystąpił (BZP)", "description": "Odpowiedź pochodzi z NASZEGO indeksu ogłoszeń, nie z odpytania UZP: API Biuletynu nie potrafi wyszukiwać po NIP, nie ma paginacji i ucina wynik na 500 rekordach. Zwracamy postępowania, w których podmiot wystąpił jako WYKONAWCA lub jako ZAMAWIAJĄCY. UWAGA: pole `data.coverage` podaje zakres dat, który realnie mamy zaindeksowany — pusta lista NIE jest dowodem braku postępowań poza tym zakresem. Szukamy po wszystkich znanych identyfikatorach podmiotu (NIP, KRS, REGON), bo zamawiający wpisują je zamiennie.", "parameters": [ { "name": "nip", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 200, "default": 50 } }, { "name": "certificate", "in": "query", "schema": { "type": "boolean" }, "description": "Wystawia certyfikat zapytania — zamrożoną kopertę z odciskiem HMAC, czyli dowód, że o tej godzinie rejestr odpowiedział dokładnie tak. Wymaga zakresu `certificate` przy kluczu. BEZ DOPŁATY w każdym pakiecie i bez osobnej jednostki — to ten sam, już rozliczony fakt z rejestru, tylko zamrożony i podpisany. Certyfikaty są poza retencją 90 dni; po rozwiązaniu umowy pozostają do pobrania przez 12 miesięcy." } ], "responses": { "200": { "description": "Koperta z listą postępowań i zakresem pokrycia", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Pojemność wiadra (burst) dla tego klucza." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Ile żetonów zostało w tej chwili." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Za ile sekund wiadro będzie pełne." }, "RateLimit-Quota-Limit": { "schema": { "type": "integer" }, "description": "Pakiet miesięczny w zapytaniach." }, "RateLimit-Quota-Used": { "schema": { "type": "integer" }, "description": "Zapytania rozliczone w bieżącym okresie." }, "RateLimit-Quota-Remaining": { "schema": { "type": "integer" }, "description": "Ile zapytań zostało do końca pakietu. Po zejściu do zera plan z nadwyżką pracuje dalej (do twardego sufitu 3× pakiet), plan FREE zwraca `429 quota_exceeded`." }, "RateLimit-Quota-Reset": { "schema": { "type": "integer" }, "description": "Za ile sekund zaczyna się nowy okres rozliczeniowy (miesiąc UTC)." }, "RateLimit-Fresh-Limit": { "schema": { "type": "integer" }, "description": "Ile świeżych pobrań (`fresh=true`) mieści się w pakiecie." }, "RateLimit-Fresh-Remaining": { "schema": { "type": "integer" }, "description": "Ile świeżych pobrań zostało w bieżącym okresie." }, "RateLimit-Sandbox-Limit": { "schema": { "type": "integer" }, "description": "Tylko dla kluczy `ds_test_*`: dzienny sufit piaskownicy. Klucze testowe nie zużywają pakietu, ale mają własny limit — po jego przekroczeniu `429` do północy UTC." }, "RateLimit-Sandbox-Remaining": { "schema": { "type": "integer" }, "description": "Ile zapytań piaskownicy zostało do końca doby (UTC)." }, "X-DS-Freshness": { "schema": { "type": "string", "enum": ["fresh", "degraded"] }, "description": "Obecny tylko przy `fresh=true`. `fresh` = poszliśmy do rejestru. `degraded` = udział świeżych pobrań wyczerpany, odpowiedź pochodzi z cache (200, nie błąd) — patrz ostrzeżenie `fresh_degraded` w kopercie." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistryEnvelope" }, "example": { "apiVersion": "v1", "requestId": "01KYFQ2R8N4TZK1M0S6VD3XB7Q", "status": "found", "subject": { "nip": "8531456990", "regon": null, "krs": null, "countryCode": "PL", "resolvedVia": "direct" }, "source": { "id": "bzp", "name": "Biuletyn Zamówień Publicznych", "authority": "Urząd Zamówień Publicznych", "official": true, "endpoint": "https://ezamowienia.gov.pl/mo-board/api/v1/notice", "availability": "ga" }, "meta": { "cache": { "hit": false }, "stale": false, "billed": 1 }, "timestamps": { "requestedAt": "2026-07-26T17:18:02.113Z", "sourceFetchedAt": "2026-07-26T08:34:58.000Z", "validAsOf": "2026-07-26" }, "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 w Mielęcinie – etap II”", "cpvCode": "45000000-7 (Roboty budowlane)", "procedureResult": null, "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 — brak wyniku nie oznacza braku postępowań." } ] } } } }, "400": { "description": "Nieprawidłowy identyfikator", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Brak lub zły klucz API", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Źródło spoza planu klucza", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Limit chwilowy (`rate_limited`) albo pakiet: wyczerpany w planie bez nadwyżki lub twardy sufit 3× pakiet (`quota_exceeded`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/sudop/{nip}": { "get": { "tags": ["SUDOP"], "operationId": "getStateAid", "summary": "Pomoc publiczna i de minimis otrzymana przez podmiot (SUDOP)", "description": "Zdarzenia pomocowe zarejestrowane przez UOKiK: kto udzielił, kiedy, w jakiej formie i za ile (PLN oraz EUR według przelicznika organu). Sekcja `data.deMinimis` sumuje pomoc de minimis 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. ⚠️ `headroomEur` jest ORIENTACYJNY i NIE zastępuje zaświadczeń o pomocy de minimis: limit dotyczy „jednego przedsiębiorstwa” w rozumieniu rozporządzenia, czyli obejmuje także podmioty powiązane — suma liczona dla samego NIP-u może być zaniżona. Sumy i wyliczenia zawsze pochodzą z KOMPLETU zdarzeń, także gdy lista `events` została przycięta parametrem `limit` (wtedy `data.truncated` = true).", "parameters": [ { "name": "nip", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Ile zdarzeń wypisać (od najnowszych). Nie wpływa na sumy ani na de minimis.", "schema": { "type": "integer", "maximum": 1000, "default": 200 } }, { "name": "certificate", "in": "query", "schema": { "type": "boolean" }, "description": "Wystawia certyfikat zapytania — zamrożoną kopertę z odciskiem HMAC, czyli dowód, że o tej godzinie rejestr odpowiedział dokładnie tak. Wymaga zakresu `certificate` przy kluczu. BEZ DOPŁATY w każdym pakiecie i bez osobnej jednostki — to ten sam, już rozliczony fakt z rejestru, tylko zamrożony i podpisany. Certyfikaty są poza retencją 90 dni; po rozwiązaniu umowy pozostają do pobrania przez 12 miesięcy." } ], "responses": { "200": { "description": "Koperta z listą zdarzeń pomocowych i podsumowaniem de minimis", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Pojemność wiadra (burst) dla tego klucza." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Ile żetonów zostało w tej chwili." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Za ile sekund wiadro będzie pełne." }, "RateLimit-Quota-Limit": { "schema": { "type": "integer" }, "description": "Pakiet miesięczny w zapytaniach." }, "RateLimit-Quota-Used": { "schema": { "type": "integer" }, "description": "Zapytania rozliczone w bieżącym okresie." }, "RateLimit-Quota-Remaining": { "schema": { "type": "integer" }, "description": "Ile zapytań zostało do końca pakietu. Po zejściu do zera plan z nadwyżką pracuje dalej (do twardego sufitu 3× pakiet), plan FREE zwraca `429 quota_exceeded`." }, "RateLimit-Quota-Reset": { "schema": { "type": "integer" }, "description": "Za ile sekund zaczyna się nowy okres rozliczeniowy (miesiąc UTC)." }, "RateLimit-Fresh-Limit": { "schema": { "type": "integer" }, "description": "Ile świeżych pobrań (`fresh=true`) mieści się w pakiecie." }, "RateLimit-Fresh-Remaining": { "schema": { "type": "integer" }, "description": "Ile świeżych pobrań zostało w bieżącym okresie." }, "RateLimit-Sandbox-Limit": { "schema": { "type": "integer" }, "description": "Tylko dla kluczy `ds_test_*`: dzienny sufit piaskownicy. Klucze testowe nie zużywają pakietu, ale mają własny limit — po jego przekroczeniu `429` do północy UTC." }, "RateLimit-Sandbox-Remaining": { "schema": { "type": "integer" }, "description": "Ile zapytań piaskownicy zostało do końca doby (UTC)." }, "X-DS-Freshness": { "schema": { "type": "string", "enum": ["fresh", "degraded"] }, "description": "Obecny tylko przy `fresh=true`. `fresh` = poszliśmy do rejestru. `degraded` = udział świeżych pobrań wyczerpany, odpowiedź pochodzi z cache (200, nie błąd) — patrz ostrzeżenie `fresh_degraded` w kopercie." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistryEnvelope" }, "example": { "apiVersion": "v1", "requestId": "01KYFQ2SB1M7WQ4E9Z0PH5TCXK", "status": "found", "subject": { "nip": "7740001454", "regon": null, "krs": null, "countryCode": "PL", "resolvedVia": "direct" }, "source": { "id": "sudop", "name": "System Udostępniania Danych o Pomocy Publicznej", "authority": "Urząd Ochrony Konkurencji i Konsumentów", "official": true, "endpoint": "https://api-sudop.uokik.gov.pl/sudop-api", "availability": "ga" }, "meta": { "cache": { "hit": false }, "stale": false, "billed": 1 }, "timestamps": { "requestedAt": "2026-07-26T17:18:05.402Z", "sourceFetchedAt": "2026-07-26T17:18:07.881Z", "validAsOf": "2026-07-26" }, "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. Limit dotyczy „jednego przedsiębiorstwa” w rozumieniu rozporządzenia, czyli także podmiotów powiązanych — suma dla samego NIP-u może być zaniżona." }, "events": [ { "grantedOn": "2026-07-20", "grantorNip": "5262748966", "grantorName": "Polskie Sieci Elektroenergetyczne S.A.", "measureNumber": "SA.46100(2017/N)", "measureName": "Polski mechanizm rynku mocy", "legalBasis": "ustawa z dnia 8 grudnia 2017 r. o rynku mocy", "formName": "dotacja lub inne bezzwrotne świadczenie", "sectorName": "Wytwarzanie energii elektrycznej", "value": { "nominalPln": 108098.97, "grossPln": 108098.97, "grossEur": 24931.15 }, "isDeMinimis": false, "deMinimisPool": null } ] }, "warnings": [ { "code": "sudop_truncated", "message": "Lista zdarzeń przycięta do 2 z 296. Sumy i de minimis policzono z kompletu." } ] } } } }, "400": { "description": "Nieprawidłowy identyfikator", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Brak lub zły klucz API", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Źródło spoza planu klucza", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Limit chwilowy (`rate_limited`) albo pakiet: wyczerpany w planie bez nadwyżki lub twardy sufit 3× pakiet (`quota_exceeded`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/crbr/{nip}": { "get": { "tags": ["CRBR"], "operationId": "getBeneficialOwners", "summary": "Beneficjenci rzeczywiści (CRBR)", "description": "Oficjalna bramka SOAP Ministerstwa Finansów. RODO: z numeru PESEL beneficjenta wyprowadzamy WYŁĄCZNIE rok urodzenia — samego numeru nie zwracamy ani nie przechowujemy (dotyczy też surowej odpowiedzi zapisywanej w certyfikacie). `status: not_found` oznacza brak wpisu w rejestrze, a nie brak podmiotu: z obowiązku zgłoszenia zwolnione są m.in. spółki publiczne, a jednoosobowe działalności w CRBR nie figurują.", "parameters": [ { "name": "nip", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fresh", "in": "query", "schema": { "type": "boolean" }, "description": "Pomija cache i pyta rejestr. NIE kosztuje więcej — jedno zapytanie to zawsze jedna jednostka. Ma za to własny udział w pakiecie (nagłówki `RateLimit-Fresh-*`); po jego wyczerpaniu odpowiedź wraca z cache z nagłówkiem `X-DS-Freshness: degraded` i ostrzeżeniem `fresh_degraded` — nigdy błędem. Ograniczenie chroni rejestry publiczne przed przeciążeniem, dlatego degradujemy zamiast blokować." }, { "name": "certificate", "in": "query", "schema": { "type": "boolean" }, "description": "Wystawia certyfikat zapytania — zamrożoną kopertę z odciskiem HMAC, czyli dowód, że o tej godzinie rejestr odpowiedział dokładnie tak. Wymaga zakresu `certificate` przy kluczu. BEZ DOPŁATY w każdym pakiecie i bez osobnej jednostki — to ten sam, już rozliczony fakt z rejestru, tylko zamrożony i podpisany. Certyfikaty są poza retencją 90 dni; po rozwiązaniu umowy pozostają do pobrania przez 12 miesięcy." } ], "responses": { "200": { "description": "Koperta z danymi CRBR", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Pojemność wiadra (burst) dla tego klucza." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Ile żetonów zostało w tej chwili." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Za ile sekund wiadro będzie pełne." }, "RateLimit-Quota-Limit": { "schema": { "type": "integer" }, "description": "Pakiet miesięczny w zapytaniach." }, "RateLimit-Quota-Used": { "schema": { "type": "integer" }, "description": "Zapytania rozliczone w bieżącym okresie." }, "RateLimit-Quota-Remaining": { "schema": { "type": "integer" }, "description": "Ile zapytań zostało do końca pakietu. Po zejściu do zera plan z nadwyżką pracuje dalej (do twardego sufitu 3× pakiet), plan FREE zwraca `429 quota_exceeded`." }, "RateLimit-Quota-Reset": { "schema": { "type": "integer" }, "description": "Za ile sekund zaczyna się nowy okres rozliczeniowy (miesiąc UTC)." }, "RateLimit-Fresh-Limit": { "schema": { "type": "integer" }, "description": "Ile świeżych pobrań (`fresh=true`) mieści się w pakiecie." }, "RateLimit-Fresh-Remaining": { "schema": { "type": "integer" }, "description": "Ile świeżych pobrań zostało w bieżącym okresie." }, "RateLimit-Sandbox-Limit": { "schema": { "type": "integer" }, "description": "Tylko dla kluczy `ds_test_*`: dzienny sufit piaskownicy. Klucze testowe nie zużywają pakietu, ale mają własny limit — po jego przekroczeniu `429` do północy UTC." }, "RateLimit-Sandbox-Remaining": { "schema": { "type": "integer" }, "description": "Ile zapytań piaskownicy zostało do końca doby (UTC)." }, "X-DS-Freshness": { "schema": { "type": "string", "enum": ["fresh", "degraded"] }, "description": "Obecny tylko przy `fresh=true`. `fresh` = poszliśmy do rejestru. `degraded` = udział świeżych pobrań wyczerpany, odpowiedź pochodzi z cache (200, nie błąd) — patrz ostrzeżenie `fresh_degraded` w kopercie." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistryEnvelope" } } } }, "400": { "description": "Nieprawidłowy identyfikator", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Brak lub zły klucz API", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Źródło spoza planu klucza", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Limit chwilowy (`rate_limited`) albo pakiet: wyczerpany w planie bez nadwyżki lub twardy sufit 3× pakiet (`quota_exceeded`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/batch/vat/bank-accounts": { "post": { "tags": ["VAT"], "operationId": "batchVerifyBankAccounts", "summary": "Zbiorcza weryfikacja rachunków z dziennego pliku płaskiego MF (bez zapytań do rejestru)", "description": "Odpowiada z własnego indeksu pliku płaskiego, więc nie zużywa limitów MF. UWAGA na semantykę: `confirmed` dowodzi, że rachunek należał do podatnika w danym dniu; `not_confirmed` oznacza BRAK POTWIERDZENIA (np. rachunek wirtualny opisany maską), a NIE to, że rachunek nie należy do podatnika — po odpowiedź definitywną użyj GET /v1/vat/{nip}/bank-account/{account}, który dopytuje API MF.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["pairs"], "properties": { "pairs": { "type": "array", "maxItems": 200, "items": { "type": "object", "required": ["nip", "account"], "properties": { "nip": { "type": "string" }, "account": { "type": "string", "description": "NRB (26 cyfr) lub IBAN" } } } }, "date": { "type": "string", "format": "date", "description": "Dzień, na który weryfikujemy. Musi być objęty indeksem — patrz `vatFlatIndex` w GET /v1/sources." } } } } } }, "responses": { "200": { "description": "Wyniki par + ostrzeżenie o semantyce `not_confirmed`" }, "400": { "description": "Nieprawidłowy identyfikator", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Brak lub zły klucz API", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Źródło spoza planu klucza", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "Więcej niż 200 par" }, "422": { "description": "Indeks nie obejmuje wskazanego dnia" }, "429": { "description": "Limit chwilowy (`rate_limited`) albo pakiet: wyczerpany w planie bez nadwyżki lub twardy sufit 3× pakiet (`quota_exceeded`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/health/vat-flat": { "get": { "tags": ["Stan usługi"], "operationId": "getVatFlatHealth", "summary": "Stan indeksu pliku płaskiego (na jaki dzień i ile wpisów)", "security": [], "responses": { "200": { "description": "Indeks wczytany" }, "503": { "description": "Brak indeksu — weryfikacja rachunków idzie przez API MF" } } } }, "/v1/certificates/{id}": { "get": { "tags": ["Certyfikaty"], "operationId": "getCertificate", "summary": "Certyfikat zapytania (zamrożona koperta + odcisk HMAC)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Certyfikat" }, "400": { "description": "Nieprawidłowy identyfikator", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Brak lub zły klucz API", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Źródło spoza planu klucza", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Limit chwilowy (`rate_limited`) albo pakiet: wyczerpany w planie bez nadwyżki lub twardy sufit 3× pakiet (`quota_exceeded`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/access-requests": { "post": { "tags": ["Dostęp"], "operationId": "requestApiAccess", "summary": "Wniosek o dostęp do API (formularz portalu, bez klucza)", "description": "Zgłoszenie handlowe, nie rejestracja. Klucz wydajemy ręcznie po kontakcie — ten endpoint nie zakłada konta i nie zwraca żadnych danych uwierzytelniających. Dławienie: 5 wniosków na adres IP w ciągu doby.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["company", "email", "useCase"], "properties": { "company": { "type": "string", "maxLength": 200 }, "nip": { "type": ["string", "null"], "description": "Nieobowiązkowy — ale podany musi przejść walidację sumy kontrolnej." }, "email": { "type": "string", "format": "email", "maxLength": 200 }, "useCase": { "type": "string", "minLength": 20, "maxLength": 2000, "description": "Do czego posłużą dane. Decyduje o planie i zakresie umowy." }, "expectedMonthlyRequests": { "type": ["integer", "null"] }, "plan": { "type": ["string", "null"], "enum": ["free", "starter", "pro", "enterprise", null] } } }, "example": { "company": "Integrator sp. z o.o.", "nip": "5252344078", "email": "integracje@example.com", "useCase": "Weryfikacja kontrahentów przy zakładaniu konta w naszym systemie faktur.", "expectedMonthlyRequests": 3000, "plan": "starter" } } } }, "responses": { "202": { "description": "Wniosek przyjęty do rozpatrzenia (klucza NIE wydaje).", "content": { "application/json": { "example": { "status": "received", "requestId": "req_01J8Z9K2M4", "detail": "Wniosek przyjęty. Klucz wydajemy ręcznie, po kontakcie z naszej strony.", "notified": true } } } }, "400": { "description": "Braki lub błędy w danych wniosku", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Za dużo wniosków z jednego adresu", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/health": { "get": { "tags": ["Stan usługi"], "operationId": "getHealth", "summary": "Liveness (bez klucza)", "security": [], "responses": { "200": { "description": "ok" }, "503": { "description": "Usługa nie przyjmuje ruchu (zamykanie procesu).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } } }