Przejdź do treści
DlugiBiz

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.

Programista integruje status kontrahentów z systemem ERP
GET /api/v1/kontrahenci/5260250995
{
  "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"
}
PoleWartości
rejestraktywny, zawieszony, wykreslony, nieznany, brak_odpowiedzi
vatstatus z wykazu podatników VAT, na przykład czynny albo zwolniony; brak, gdy firmy nie ma w wykazie
rachunkiliczba rachunków przypisanych do NIP w wykazie
krzczysto, postepowanie (wpis o upadłości albo restrukturyzacji w dziale szóstym KRS), brak_odpowiedzi
dlugiliczba aktywnych długów na profilu, bez kwot i wierzycieli
ocenaok, 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

KodZnaczenie
200Odpowiedź z danymi
401Brak klucza albo klucz nieprawidłowy lub unieważniony
403Plan firmy nie obejmuje API
422Niepoprawny NIP, błędna suma kontrolna
429Przekroczony 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ę

  1. 01

    Kupujesz plan Korporacja

    W cenniku, kartą, z fakturą VAT. Bez umowy i rozmowy z handlowcem.

  2. 02

    Importujesz kontrahentów

    Plik CSV z NIP-ami albo lista wklejona w panelu, do 2 000 firm naraz.

  3. 03

    Generujesz klucz i sekret

    Klucz tworzysz w zakładce API panelu, adres webhooka podajesz w ustawieniach alertów i od razu dostajesz sekret.

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