Biała lista API i status kontrahentów w jednym zapytaniu
Biała lista API w DlugiBiz to zapytanie REST po NIP, które zwraca status VAT i rachunki z wykazu podatników VAT razem ze stanem w KRS albo CEIDG, wpisami o upadłości z działu szóstego KRS i aktywnymi długami. Do tego webhook z podpisem przy każdej zmianie u kontrahentów z Twojej listy.
Plan Korporacja 399 zł netto / mies. + 23% VAT przy płatności rocznej. Klucz API od razu po zakupie, bez umowy.
{
"nip": "5260250995",
"rejestr": "aktywny",
"vat": "czynny",
"rachunki": 154,
"krz": "czysto",
"dlugi": 0,
"ocena": "ok"
}
Po co API statusu kontrahentów
System ERP zwalnia zamówienie, wydaje towar i zleca przelew, zanim ktokolwiek otworzy przeglądarkę. API pozwala sprawdzić kontrahenta automatycznie w tym właśnie momencie i zatrzymać operację, gdy firma ma dług, upadłość w KRS albo rachunek spoza wykazu.
Dokumentacja
Autoryzacja i adres bazowy
Adres bazowy to https://dlugi.biz.pl/api/v1. Klucz z prefiksem db_ generujesz w panelu, a podajesz go wyłącznie w nagłówku Authorization. Klucza nigdy nie umieszczaj w adresie.
- Klucz widzisz raz, przechowujemy tylko jego skrót
- Unieważnienie i nowy klucz jednym kliknięciem
- Połączenia tylko przez HTTPS, odpowiedzi w JSON w UTF-8
Status jednego kontrahenta
curl -s https://dlugi.biz.pl/api/v1/kontrahenci/5260250995 \
-H "Authorization: Bearer db_TWOJ_KLUCZ"
{
"nip": "5260250995",
"nazwa": "ORANGE POLSKA SPÓŁKA AKCYJNA",
"profil": "https://dlugi.biz.pl/firma/orange-polska-spolka-akcyjna-5260250995",
"miejscowosc": "Warszawa",
"rejestr": "aktywny",
"rejestr_opis": "Aktywna w KRS",
"vat": "czynny",
"rachunki": 154,
"krz": "czysto",
"dlugi": 0,
"sprawdzono": "2026-10-17T07:00:12+02:00",
"ocena": "ok"
}
| Pole | Wartości |
|---|---|
| rejestr | aktywny, zawieszony, wykreslony, nieznany, brak_odpowiedzi |
| vat | status z wykazu podatników VAT, na przykład czynny albo zwolniony; brak, gdy firmy nie ma w wykazie |
| rachunki | liczba rachunków przypisanych do NIP w wykazie |
| krz | czysto, postepowanie (wpis o upadłości albo restrukturyzacji w dziale szóstym KRS), brak_odpowiedzi |
| dlugi | liczba aktywnych długów na profilu, bez kwot i wierzycieli |
| ocena | ok, uwaga (dług, postępowanie, wykreślenie, zawieszenie), sprawdz (brak w wykazie albo w rejestrach) |
Zdarzenia i lista monitorowanych firm
Endpoint zdarzeń zwraca zmiany wykryte u kontrahentów z Twojej listy od wskazanej chwili, najwyżej 1 000 w jednej odpowiedzi. Typy zdarzeń to dlug, sprzeciw, splata, komentarz, rejestr, vat, rachunek i upadlosc. Endpoint listy zwraca wszystkie monitorowane NIP-y z ostatnim statusem VAT.
curl -s "https://dlugi.biz.pl/api/v1/zdarzenia?od=2026-10-16T00:00:00%2B02:00" \
-H "Authorization: Bearer db_TWOJ_KLUCZ"
curl -s https://dlugi.biz.pl/api/v1/lista \
-H "Authorization: Bearer db_TWOJ_KLUCZ"
Odpowiedź /api/v1/zdarzenia
{
"zdarzenia": [
{
"id": 48211,
"typ": "rachunek",
"opis": "Nowy rachunek w wykazie VAT, końcówka 0912",
"nip": "NIP_KONTRAHENTA",
"nazwa": "NAZWA KONTRAHENTA Z REJESTRU",
"profil": "https://dlugi.biz.pl/firma/nazwa-kontrahenta-NIP",
"wykryto": "2026-10-17T06:58:40+02:00"
}
]
}
Webhook
Webhook zmian z podpisem HMAC
W ustawieniach alertów podajesz adres zaczynający się od https:// i dostajesz sekret. Przy każdej zmianie wysyłamy POST z treścią w tym samym formacie co endpoint zdarzeń i nagłówkiem X-Podpis: t=<czas unix>,v1=<podpis>. Podpis to HMAC SHA-256 z ciągu czas, kropka i surowa treść żądania, liczony Twoim sekretem. Sprawdzaj go przed przetworzeniem danych.
PHP
$sekret = getenv('DLUGIBIZ_SEKRET');
$tresc = file_get_contents('php://input');
$naglowek = $_SERVER['HTTP_X_PODPIS'] ?? '';
$ok = preg_match('/^t=(\d+),v1=([a-f0-9]{64})$/', $naglowek, $m) === 1
&& abs(time() - (int) $m[1]) <= 300
&& hash_equals(hash_hmac('sha256', $m[1] . '.' . $tresc, $sekret), $m[2]);
if ($ok === false) {
http_response_code(400);
exit;
}
$dane = json_decode($tresc, true);
foreach ($dane['zdarzenia'] as $z) {
// na przykład wstrzymaj zamówienia kontrahenta $z['nip']
}
http_response_code(204);
Node.js
const crypto = require('crypto');
const express = require('express');
const app = express();
app.post('/dlugibiz', express.raw({ type: 'application/json' }), (req, res) => {
const m = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(req.get('X-Podpis') || '');
const swiezy = m && Math.abs(Date.now() / 1000 - Number(m[1])) <= 300;
const oczekiwany = m && crypto
.createHmac('sha256', process.env.DLUGIBIZ_SEKRET)
.update(m[1] + '.' + req.body)
.digest();
const ok = swiezy && crypto.timingSafeEqual(oczekiwany, Buffer.from(m[2], 'hex'));
if (Boolean(ok) === false) return res.sendStatus(400);
const { zdarzenia } = JSON.parse(req.body);
zdarzenia.forEach((z) => { /* na przykład wstrzymaj zamówienia z.nip */ });
res.sendStatus(204);
});
Limity i kody odpowiedzi
| Kod | Znaczenie |
|---|---|
| 200 | Odpowiedź z danymi |
| 401 | Brak klucza albo klucz nieprawidłowy lub unieważniony |
| 403 | Plan firmy nie obejmuje API |
| 422 | Niepoprawny NIP, błędna suma kontrolna |
| 429 | Przekroczony limit 10 000 zapytań na dobę albo 120 na minutę |
Błędy mają postać {"blad": "opis"}. Zdarzenia odbierane webhookiem nie zużywają limitu zapytań.
Pytanie i odpowiedź
- Czy biała lista ma API?
- Tak, wykaz podatników VAT ma oficjalne API z dziennymi limitami zapytań. DlugiBiz łączy dane z wykazu z KRS, CEIDG i długami w jednym zapytaniu i dodaje webhook zmian.
- Czy API nadaje się do sprawdzania rachunku przed przelewem?
- API zwraca liczbę rachunków i status VAT. Konkretny numer konta sprawdzasz w panelu, gdzie wynik trafia do dziennika sprawdzeń, opisanego na stronie o weryfikacji rachunku bankowego kontrahenta.
Jak uruchomić integrację
-
01
Kupujesz plan Korporacja
W cenniku, kartą, z fakturą VAT. Bez umowy i rozmowy z handlowcem.
-
02
Importujesz kontrahentów
Plik CSV z NIP-ami albo lista wklejona w panelu, do 2 000 firm naraz.
-
03
Generujesz klucz i sekret
Klucz tworzysz w zakładce API panelu, adres webhooka podajesz w ustawieniach alertów i od razu dostajesz sekret.
-
04
Podpinasz ERP
Zapytanie przed zwolnieniem zamówienia, webhook do wstrzymania dostaw albo przelewów.
API korzysta z tych samych danych co monitoring KRS i kontrola statusu VAT kontrahenta. Co plan Korporacja daje zarządowi poza API, opisuje strona monitoring kontrahentów dla zarządu.
Pytania o API
Pytania techniczne wysyłaj na kontakt@dlugi.biz.pl.
Czym różni się to API od oficjalnego API wykazu podatników VAT?
Oficjalne API wykazu zwraca dane z białej listy: status VAT, rachunki i dane rejestrowe. API DlugiBiz zwraca w jednym zapytaniu także stan w KRS albo CEIDG, wpisy o upadłości i restrukturyzacji z działu szóstego KRS, liczbę aktywnych długów zgłoszonych w serwisie i gotową ocenę, a do tego wysyła webhook przy każdej zmianie na Twojej liście.
W którym planie jest API?
API statusu kontrahentów i webhook zmian są w planie Korporacja, razem z monitoringiem do 2 000 firm, alertami od razu po wykryciu i logowaniem SSO. Plan kupujesz sam w cenniku, klucz generujesz w panelu w zakładce API.
Jakie są limity zapytań?
Do 10 000 zapytań na dobę i 120 na minutę na klucz. Po przekroczeniu API zwraca kod 429. Limit dobowy odnawia się o północy czasu polskiego.
Czy API zwraca kwoty długów i wierzycieli?
Nie. API pokazuje to samo, co publiczny profil firmy: liczbę aktywnych długów bez kwot, rodzajów i wierzycieli. Szczegóły długu widzi tylko zweryfikowana firma po wniosku i zobowiązaniu do poufności, w panelu.
Jak zabezpieczony jest webhook?
Każde wywołanie ma nagłówek X-Podpis z czasem wysłania i podpisem HMAC SHA-256 treści, liczonym Twoim sekretem. Twój serwer liczy podpis sam, porównuje go w czasie stałym i odrzuca wywołania starsze niż kilka minut.
Co jeśli mój serwer nie odbierze webhooka?
Żadne zdarzenie nie ginie. Endpoint /api/v1/zdarzenia zwraca wszystkie zdarzenia z Twojej listy od wskazanej chwili, więc po przerwie dociągasz je jednym zapytaniem.
Podłącz status kontrahentów do swojego systemu
Plan Korporacja z API, webhookiem, SSO i monitoringiem do 2 000 firm kupujesz sam, klucz dostajesz od razu.