API Reference

Opis

Pobiera dane firmy z GUS BIR1.1 na podstawie numeru NIP. Jeśli firma nie istnieje w lokalnej bazie, zostanie automatycznie pobrana z GUS i zapisana. Wykorzystuje inteligentny cache.

Path Parameters

Query Parameters

Headers

Responses

{
  "success": true,
  "nip": "1234567890",
  "regon": "123456789",
  "nazwa": "PRZYKŁADOWA FIRMA SP. Z O.O.",
  "adres": "ul. Testowa 123/45, 00-001 Warszawa",
  "data_zakonczenia_dzialalnosci": "2024-12-31"
}

{
  "success": true,
  "nip": "1234567890",
  "regon": "123456789",
  "nazwa": "PRZYKŁADOWA FIRMA SP. Z O.O.",
  "ulica": "ul. Testowa",
  "numer_budynku": "123",
  "numer_lokalu": "45",
  "kod_pocztowy": "00-001",
  "miasto": "Warszawa",
  "data_zakonczenia_dzialalnosci": "2024-12-31"
}

{
  "success": false,
  "message": "Firma nie istnieje"
}

{
  "success": false,
  "message": "Nieprawidłowy klucz API",
  "error": "INVALID_API_KEY"
}

{
  "success": false,
  "message": "Przekroczono dzienny limit zapytań dla Twojego konta",
  "error": "RATE_LIMIT_EXCEEDED",
  "limit": 10,
  "used": 11,
  "info": "Limit dotyczy wszystkich Twoich kluczy API łącznie"
}

Opis

Alternatywna metoda wyszukiwania firmy po NIP używając metody POST. Zwraca te same dane co endpoint GET. Użyteczne gdy NIP jest przekazywany w body żądania.

Query Parameters

Headers

Request Body

{
  "nip": "1234567890"
}

Responses

{
  "success": true,
  "nip": "1234567890",
  "regon": "123456789",
  "nazwa": "PRZYKŁADOWA FIRMA SP. Z O.O.",
  "adres": "ul. Testowa 123/45, 00-001 Warszawa",
  "data_zakonczenia_dzialalnosci": "2024-12-31"
}

{
  "success": false,
  "message": "Firma nie istnieje"
}

{
  "success": false,
  "message": "Pole nip jest wymagane",
  "error": "VALIDATION_ERROR"
}

{
  "success": false,
  "message": "Nieprawidłowy klucz API",
  "error": "INVALID_API_KEY"
}

{
  "success": false,
  "message": "Przekroczono dzienny limit zapytań dla Twojego konta",
  "error": "RATE_LIMIT_EXCEEDED",
  "limit": 10,
  "used": 11
}

Opis

Sprawdza do 20 numerów NIP w jednym żądaniu i zwraca zbiorczą odpowiedź. Każdy unikalny, poprawny NIP liczy się jako 1 zapytanie w dziennym limicie konta. Duplikaty w tablicy są pomijane (liczone raz). Niepoprawne NIPy zwracane są w wynikach z błędem INVALID_NIP i nie obciążają limitu.

Przed przetwarzaniem API sprawdza, czy masz wystarczający limit na dzisiaj. Limit jest pobierany dopiero po pomyślnym zakończeniu batcha. Czas odpowiedzi zależy od cache — przy danych z cache ~100 ms, przy wielu zapytaniach do GUS nawet 10–40 s.

Headers

Request Body

{
  "nips": ["5261040828", "1234567890", "9876543210"],
  "format": "simple"
}

Responses

{
  "success": true,
  "summary": {
    "requested": 3,
    "unique_valid": 3,
    "duplicates_skipped": 0,
    "invalid": 0,
    "found": 2,
    "not_found": 1,
    "errors": 0
  },
  "meta": {
    "processing_time_ms": 74.12,
    "format": "simple",
    "quota": {
      "charged": 3,
      "used_today": 23,
      "daily_limit": 10,
      "remaining": 0
    }
  },
  "results": [
    {
      "success": true,
      "nip": "5261040828",
      "regon": "123456789",
      "nazwa": "PRZYKŁADOWA FIRMA SP. Z O.O.",
      "adres": "ul. Testowa 1, 00-001 Warszawa"
    },
    {
      "nip": "1234567890",
      "success": false,
      "error": "NOT_FOUND",
      "message": "Firma o podanym NIP nie istnieje w rejestrze GUS"
    }
  ]
}

{
  "success": false,
  "message": "Brak poprawnych NIPów do sprawdzenia.",
  "error": "NO_VALID_NIPS",
  "results": [
    {
      "input": "123",
      "success": false,
      "error": "INVALID_NIP",
      "message": "Nieprawidłowy format NIP. Wymagane 10 cyfr."
    }
  ]
}

{
  "success": false,
  "message": "Niewystarczający dzienny limit zapytań dla tego batcha.",
  "error": "RATE_LIMIT_EXCEEDED",
  "required": 15,
  "remaining": 10,
  "limit": 10,
  "used": 0,
  "info": "Limit dotyczy wszystkich Twoich kluczy API łącznie. Duplikaty NIPów liczone są raz."
}

{
  "success": false,
  "message": "Nieprawidłowy klucz API",
  "error": "INVALID_API_KEY"
}