KRS API z danymi finansowymi, oceną firmy i webhookiem zmian
Jedno zapytanie po numerze NIP, KRS albo REGON zwraca dane z KRS, liczby z e-sprawozdań XML wczytanych przez klienta, status VAT, sygnały o upadłości i restrukturyzacji z działu 6 KRS oraz score 0-100 ze składowymi i rekomendacją terminu płatności. Webhook przekazuje obsługiwane zdarzenia o zmianach score, ryzyka, sygnałów i nowej wzmiance o sprawozdaniu w KRS. API jest w planach Business, Portfel i Enterprise, od 20 000 zapytań miesięcznie.
Sprawdź, co API zwróci dla Twojego kontrahenta
Status VAT, numer KRS, forma prawna i kapitał od razu. Pełny score 0-100 po założeniu konta.
Co zwraca KRS API w Score
| Zasób | Zawartość |
|---|---|
| Firma | nazwa, forma prawna, PKD, numery NIP, KRS i REGON |
| Rejestr | zarząd, kapitał, data wpisu, status na białej liście VAT |
| Finanse | pozycje bilansu, RZiS i przepływów za kolejne lata, wskaźniki |
| Ocena | score 0-100, cztery składowe, sekcja branży, poziom ryzyka |
| Sygnały | postępowania z działu 6 KRS, zmiany zarządu, status VAT, zaległe sprawozdania |
| Rekomendacja | termin płatności w dniach i limit kupiecki według Twoich reguł |
| Portfel | lista monitorowanych NIP-ów, dodawanie i usuwanie przez API |
Liczby finansowe pochodzą z plików e-sprawozdań wczytanych na Twoim koncie. Gdy spółka nie ma jeszcze sprawozdania, odpowiedź ma pole financial_data ustawione na false, a ocena opiera się na samych rejestrach.
Endpointy API w wersji v1
Adres bazowy to https://score.pl/api/v1. Każde zapytanie ma nagłówek Authorization: Bearer <klucz API>. Klucze tworzysz, nazywasz i unieważniasz w ustawieniach organizacji, a każdy ma własną datę ostatniego użycia.
| Metoda i ścieżka | Co robi |
|---|---|
| GET /companies/{numer}/score | score, ryzyko, składowe, sygnały i rekomendacja |
| GET /companies/{numer} | to samo plus dane rejestrowe, finanse za kolejne lata i wskaźniki |
| GET /portfolio | lista firm w monitoringu z ostatnim score i datą sprawdzenia |
| POST /portfolio | dodaje NIP do monitoringu |
| DELETE /portfolio/{nip} | usuwa NIP z monitoringu |
| GET /usage | plan, limit miesięczny, zużyte zapytania i koniec okresu |
W miejscu {numer} podajesz NIP, numer KRS albo REGON. Score sam ustala NIP spółki na podstawie numeru KRS albo REGON.
Przykład zapytania i odpowiedzi
API działa w standardzie REST i zwraca JSON w UTF-8. Tak wygląda sprawdzenie odbiorcy przed zatwierdzeniem zamówienia w ERP.
GET /api/v1/companies/{nip}/score
Authorization: Bearer <klucz API>
{
"nip": "<NIP>",
"name": "Przykładowa Hurtownia",
"score": 44,
"risk": "medium",
"components": {
"liquidity": 38,
"debt": 41,
"profitability": 35,
"revenue_growth": 52
},
"signals": [
{
"description": "Zmiana zarządu w ostatnich 6 miesiącach",
"points": -4,
"source": "KRS"
}
],
"recommendation": {
"term_days": 21,
"credit_limit": 35000
},
"financial_data": true,
"complete": true
}
Pole score to ocena 0-100, risk przyjmuje wartości low, medium albo high, a recommendation podaje termin i limit kupiecki wyliczone według reguł ustawionych w Twojej organizacji. Nazwa i liczby w przykładzie są przykładowe.
Kody odpowiedzi i limity
| Kod | Znaczenie | Czy zużywa zapytanie |
|---|---|---|
| 200 | dane firmy i ocena | tak |
| 401 | brak klucza albo klucz nieważny | nie |
| 404 | firmy nie ma w rejestrach | tak przy numerze KRS i REGON sprawdzonym w rejestrze |
| 422 | błędny NIP, KRS albo REGON (suma kontrolna, długość) | nie |
| 429 | wyczerpany limit miesięczny albo za dużo zapytań na minutę | nie |
| 503 | rejestr publiczny chwilowo nie odpowiada | nie |
Przy kodzie 429 nagłówek Retry-After mówi, po ilu sekundach ponowić zapytanie. Zapytania, które nie dały wyniku z powodu awarii rejestru, wracają do limitu planu, więc nie płacisz za przestoje po stronie państwowych serwisów.
Webhook zmian w portfelu
Webhook wysyła zdarzenie na Twój adres https, gdy score kontrahenta się zmienia, pojawia się nowy sygnał w rejestrze, kontrahent przechodzi do innego poziomu ryzyka albo w KRS pojawia się nowa wzmianka o sprawozdaniu. Przeliczenie finansów wymaga wczytania pliku XML przez klienta. Dzięki temu nie musisz codziennie odpytywać API o cały portfel.
- score.changed, z nowym i poprzednim score
- risk.changed, z nowym i poprzednim poziomem ryzyka
- signal.created, z opisem sygnału
- statement.published, z datą końca okresu sprawozdania
Każde zdarzenie ma nagłówek Score-Signature w postaci t=<czas>,v1=<podpis>, gdzie podpis to HMAC-SHA256 z czasu i treści liczony kluczem webhooka. Twój system sprawdza podpis i odrzuca zdarzenia, które nie pochodzą ze Score. W panelu wyślesz zdarzenie testowe, zanim podepniesz produkcję.
Ile kosztuje KRS API w Score.pl
| Plan | Cena netto miesięcznie + 23% VAT | Zapytania miesięcznie | Koszt jednego zapytania | Monitoring |
|---|---|---|---|---|
| Business | 1 490 zł | 20 000 | około 7,5 gr | do 500 NIP-ów |
| Portfel | 3 900 zł | 200 000 | około 2 gr | do 5 000 NIP-ów |
| Enterprise | 7 800 zł | 500 000 | około 1,6 gr | do 50 000 NIP-ów |
Przy płatności rocznej cena jest o 50 procent niższa. Webhook jest w każdym z tych planów. Plan Pro za 349 zł nie ma API, ale ma karty firm bez limitu i monitoring 50 kontrahentów w przeglądarce. Wszystkie różnice są w cenniku.
Do czego firmy używają KRS API
- Wstępna ocena wniosku w leasingu, faktoringu i finansowaniu MSP, zanim analityk otworzy dokumenty
- Blokada zamówienia w ERP, gdy odbiorca przekracza limit kupiecki albo wchodzi w wysokie ryzyko
- Pole score w karcie klienta w CRM, na przykład w HubSpot albo Pipedrive
- Automatyczny monitoring kontrahentów z webhookiem do kanału działu należności
- Synchronizacja portfela z Comarch ERP Optima, enova365, Symfonia i Subiekt przez plik CSV
Hurtownia, która wystawia kilkaset faktur z terminem miesięcznie, wpina zapytanie score w zatwierdzanie zamówienia. Handlowiec widzi rekomendowany termin od razu, a dział finansów nie musi sprawdzać każdego nowego klienta ręcznie.
Rządowe API KRS a KRS API w Score
Ministerstwo Sprawiedliwości udostępnia bezpłatne API KRS, które po numerze KRS zwraca odpis aktualny albo pełny w JSON. To dobre źródło danych rejestrowych, ale nie wystarczy do decyzji kredytowej.
| Co potrzebujesz | Rządowe API KRS | KRS API w Score |
|---|---|---|
| Wyszukiwanie po NIP i REGON | nie, tylko po numerze KRS | tak, NIP, KRS albo REGON |
| Odpis z KRS | tak | tak, przetworzony na pola |
| Liczby ze sprawozdań finansowych | nie, tylko wzmianka o złożeniu | bilans, RZiS i wskaźniki za kolejne lata |
| Status na białej liście VAT | nie | tak |
| Ocena 0-100 i poziom ryzyka | nie | tak |
| Termin płatności i limit kupiecki | nie | tak, według Twoich reguł |
| Powiadomienia o zmianach | nie, trzeba odpytywać | webhook z podpisem |
| Cena | bez opłaty | od 1 490 zł netto miesięcznie + 23% VAT |
Jeśli potrzebujesz tylko składu zarządu jednej spółki, rządowe API wystarczy. Gdy na wynik zapytania ma czekać decyzja o fakturze z terminem, Score oszczędza Ci budowę parsera odpisów, obsługi plików e-sprawozdań i modelu oceny. Źródła opisujemy na stronie źródła danych o firmach, a sposób liczenia w metodologii.
Pytania programistów o KRS API
Czy KRS ma API?
Tak. Ministerstwo Sprawiedliwości udostępnia publiczne API KRS, które po numerze KRS zwraca odpis aktualny albo pełny w formacie JSON, bez klucza i bez opłaty. API nie wyszukuje firm po NIP-ie i nie zwraca liczb ze sprawozdań finansowych, dlatego do oceny kontrahenta łączy się je z innymi źródłami, tak jak robi to Score.
Jak pobrać dane z KRS przez API?
W rządowym API wysyłasz zapytanie GET z numerem KRS i rodzajem rejestru, a w odpowiedzi dostajesz odpis jako JSON do samodzielnego przetworzenia. W Score wysyłasz GET /api/v1/companies/{numer} z kluczem API i dostajesz gotowe pola: zarząd, kapitał, PKD, status VAT, finanse do pięciu lat z XML wczytanych na konto i ocenę. Bez sprawozdania nie podajemy kwoty limitu kupieckiego.
Czy przez API można pobrać sprawozdanie finansowe spółki?
Rządowe API KRS podaje tylko informację, że sprawozdanie złożono. Same liczby są w plikach XML w Repozytorium Dokumentów Finansowych. W Score pliki e-sprawozdań wczytane na koncie są odczytywane do pól bilansu i RZiS, a endpoint /companies/{numer} zwraca je jako tabelę lat ze wskaźnikami.
Ile kosztuje API z danymi o firmach?
Rządowe API KRS i biała lista VAT są bez opłaty, ale zwracają surowe dane. KRS API w Score kosztuje od 1 490 zł netto miesięcznie + 23% VAT w planie Business z limitem 20 000 zapytań, co daje około 7,5 gr za zapytanie. W planie Portfel koszt spada do około 2 gr, a płatność roczna obniża cenę o połowę.
Jak sprawdzić firmę po NIP przez API?
W Score wpisujesz NIP w ścieżce zapytania, na przykład GET /api/v1/companies/{nip}/score, i dostajesz ocenę, ryzyko i rekomendację terminu. NIP jest sprawdzany pod kątem sumy kontrolnej, więc błędny numer kończy się kodem 422 bez zużycia limitu. Ręcznie zrobisz to samo na stronie sprawdź firmę po NIP.
Czy jest wersja testowa API?
Jedną pełną ocenę firmy wykonasz w przeglądarce bez opłaty i bez karty płatniczej, więc zobaczysz dokładnie te dane, które zwraca API. Klucz API tworzysz po wybraniu planu Business, a w panelu wyślesz zdarzenie testowe webhooka i sprawdzisz zużycie limitu przez GET /api/v1/usage.
Podłącz ocenę kontrahentów do swojego systemu
Wybierz plan Business, utwórz klucz API w ustawieniach organizacji i wyślij pierwsze zapytanie. Wszystkie dane, które zwraca API, zobaczysz też w karcie firmy.