RiskWatch API

Dokumentacja

v1https://api.riskwatch.pl/v1

Przegląd API

Publiczne API działa pod /v1 i uwierzytelnia się kluczem API Bearer z prefiksem rw_live_. Prefiks rw_test_ to sandbox: nie czyta ani nie zapisuje danych organizacji, nie jest liczony do limitów i zwraca deterministyczne dane testowe (oznaczone sandbox: true) tylko dla syntetycznych NIP-ów 1111111111, 2222222222 i 3333333333 (inne NIP-y zwracają 404, a webhooki wymagają klucza live; serwer MCP odrzuca klucze rw_test_ (403) — użyj klucza live lub OAuth). Każde żądanie zapisu wymaga nagłówka Idempotency-Key; zwykłe odpowiedzi można odtworzyć, ale replay operacji zwracającej jednorazowy sekret kończy się jawnym błędem 409.

Koperta odpowiedzi

Poprawne odpowiedzi opakowują ładunek w data i meta:

200 OK
{
  "data": { "added": ["<YOUR_VALID_NIP>"], "skipped": [], "reactivated": [], "failed": [], "plan_limit": 250 },
  "meta": { "request_id": "req_h4x82k", "timestamp": "2026-07-10T08:14:02.114Z" }
}

Błędy

Błędy używają stabilnego enuma error.code (VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, RATE_LIMITED, SOURCE_ERROR, SOURCE_UNAVAILABLE, INTERNAL_ERROR) i tam, gdzie ma to zastosowanie, zawierają retry_after w sekundach:

429 Too Many Requests
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Usage limit exceeded for manual_refreshes",
    "retry_after": 41230
  },
  "meta": { "request_id": "req_p03m1c", "timestamp": "2026-07-10T08:15:44.902Z" }
}

Stronicowanie

Stronicowane feedy listy obserwowanych, zdarzeń i dostarczeń webhooków przyjmują limit (od 1 do 500) oraz nieprzezroczysty cursor. Gdy istnieją kolejne wiersze, odpowiedź zawiera meta.next_cursor; przekaż go z powrotem, aby pobrać następną stronę.

Jednorazowe sprawdzenia (/v1/checks/*) a lista obserwowanych

Oprócz cyklicznego monitoringu listy obserwowanych (/v1/watchlist) każde konto z kluczem produkcyjnym rw_live_ i zakresem read może wykonywać jednorazowe sprawdzenia bez dopisywania podmiotu do listy obserwowanych. Każde wywołanie wymaga nagłówka Idempotency-Key i zużywa 1 jednostkę api_requests (zwracaną przy błędach 4xx/5xx); klucze sandbox (rw_test_) zwracają 403.

  • POST /v1/checks/vat — Jednorazowe sprawdzenie statusu VAT do 30 numerów NIP na Białej liście MF (wykazpodatnikowvat.mf.gov.pl/api) na wskazany dzień; zwraca status_vat, liczbę rachunków i request_id MF.
  • POST /v1/checks/bank-account — Weryfikacja rachunku bankowego przed przelewem metodą check MF (czy 26-cyfrowy NRB lub PL+NRB jest przypisany do NIP w wybranym dniu). Zwraca assigned (true/false), request_id MF oraz zamaskowany numer rachunku (widoczne tylko 4 ostatnie cyfry).
  • POST /v1/checks/vies — Weryfikacja numeru VAT UE w systemie Komisji Europejskiej VIES (country_code + vat_number, opcjonalnie dane pytającego dla uzyskania numeru konsultacji request_identifier). Niedostępność państwa członkowskiego kończy się statusem 503 SOURCE_UNAVAILABLE, nigdy fałszywym valid: false.
  • POST /v1/checks/sanctions — Weryfikacja na lokalnie synchronizowanych oficjalnych listach sankcyjnych: polskiej liście MSWiA (PL_MSWIA), skonsolidowanej liście UE (EU_FSF) oraz amerykańskiej liście OFAC (US_OFAC_SDN). Dopasowanie jest wyłącznie dokładne (exact match po NIP albo znormalizowanej nazwie/aliasie, bez rozmytego scoringu). Gdy którakolwiek lista ma synchronizację starszą niż 48h, brak trafienia zwraca result: "inconclusive" (stale: true), nigdy "no_match". Narzędzie pomocnicze — nie zastępuje pełnego programu AML/KYC, weryfikacji PEP ani porady prawnej.
POST /v1/checks/vat
curl -X POST https://api.riskwatch.pl/v1/checks/vat \
  -H "Authorization: Bearer rw_live_yourkey" \
  -H "Idempotency-Key: check-vat-001" \
  -H "Content-Type: application/json" \
  -d '{"nips":["<YOUR_VALID_NIP>"],"date":"2026-11-06"}'
POST /v1/checks/bank-account
curl -X POST https://api.riskwatch.pl/v1/checks/bank-account \
  -H "Authorization: Bearer rw_live_yourkey" \
  -H "Idempotency-Key: check-nrb-001" \
  -H "Content-Type: application/json" \
  -d '{"nip":"<YOUR_VALID_NIP>","account":"<YOUR_26_DIGIT_NRB>","date":"2026-11-06"}'
POST /v1/checks/vies
curl -X POST https://api.riskwatch.pl/v1/checks/vies \
  -H "Authorization: Bearer rw_live_yourkey" \
  -H "Idempotency-Key: check-vies-001" \
  -H "Content-Type: application/json" \
  -d '{"country_code":"DE","vat_number":"143454214"}'
POST /v1/checks/sanctions
curl -X POST https://api.riskwatch.pl/v1/checks/sanctions \
  -H "Authorization: Bearer rw_live_yourkey" \
  -H "Idempotency-Key: check-sanctions-001" \
  -H "Content-Type: application/json" \
  -d '{"nip":"<YOUR_VALID_NIP>","name":"Synthetic Sp. z o.o."}'