Dokumentacja API - Endpoint pobierania firm /companies
Przegląd
Ten endpoint umożliwia pobieranie danych firm z bazy danych z zaawansowanymi opcjami filtrowania, sortowania i paginacji. API implementuje mechanizmy bezpieczeństwa, rate limiting oraz cache'owanie dla optymalnej wydajności.
Endpoint
Autoryzacja
API wymaga klucza autoryzacji przekazywanego w nagłówku:
Authorization: Bearer YOUR_API_KEY
Limity
- Rate Limiting: 10 zapytań na 10 sekund na użytkownika
- Limit miesięczny: Zgodny z planem użytkownika
- Limit wyników: Maksymalnie 100 rekordów na zapytanie
Parametry zapytania
Paginacja i sortowanie
| Parametr | Typ | Domyślna wartość | Opis |
|---|
limit | integer | 10 | Liczba wyników (1-100) |
offset | integer | 0 | Przesunięcie wyników |
sortBy | string | 'createdAt' | Pole sortowania: createdAt, name, updatedAt |
sortOrder | string | 'desc' | Kierunek sortowania: asc, desc |
Filtry lokalizacyjne
| Parametr | Typ | Opis |
|---|
miasto | string | Filtrowanie po mieście |
wojewodztwo | string | Filtrowanie po województwie |
powiat | string | Filtrowanie po powiecie |
gmina | string | Filtrowanie po gminie |
Filtry branżowe
| Parametr | Typ | Opis |
|---|
pkd | string | Kod PKD firmy |
category | string | Kategoria firmy |
branza | string | Branża działalności |
Filtry obecności mediów społecznościowych
Wszystkie parametry typu boolean (wartości: true/1 lub false/0):
| Parametr | Opis |
|---|
hasWebsite | Firma posiada stronę internetową |
hasFacebook | Firma posiada profil Facebook |
hasTiktok | Firma posiada profil TikTok |
hasX | Firma posiada profil X (Twitter) |
hasInstagram | Firma posiada profil Instagram |
hasYoutube | Firma posiada kanał YouTube |
hasLinkedin | Firma posiada profil LinkedIn |
Filtry kontaktowe
| Parametr | Typ | Opis |
|---|
hasPhone | boolean | Firma posiada numer telefonu |
hasEmail | boolean | Firma posiada adres email |
Przykłady użycia
Podstawowe zapytanie
GET /api/companies?limit=20&offset=0
Filtrowanie po lokalizacji
GET /api/companies?miasto=Warszawa&wojewodztwo=mazowieckie
Filtrowanie firm z mediami społecznościowymi
GET /api/companies?hasFacebook=true&hasInstagram=true&hasWebsite=true
Zaawansowane filtrowanie
GET /api/companies?miasto=Kraków&branza=IT&hasLinkedin=true&sortBy=name&sortOrder=asc
Odpowiedź API
Sukces (200 OK)
{
"metadata": {
"total": 1250,
"limit": 10,
"offset": 0
},
"data": [
{
"id": "12345",
"name": "Przykładowa Firma Sp. z o.o.",
"miasto": "Warszawa",
"wojewodztwo": "mazowieckie",
"pkd": "6201Z",
"website": "https://example.com",
"facebook": "https://facebook.com/example",
"email": "kontakt@example.com",
"phone": "+48123456789",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T14:45:00Z"
}
]
}
Błędy
401 Unauthorized - Brak klucza API
{
"error": "Missing API key",
"code": "MISSING_API_KEY"
}
401 Unauthorized - Nieprawidłowy klucz API
{
"error": "Invalid API key",
"code": "INVALID_API_KEY"
}
429 Too Many Requests - Przekroczenie limitów
{
"error": "Rate limit exceeded",
"code": "RATE_LIMIT_EXCEEDED"
}
400 Bad Request - Nieprawidłowe parametry
{
"error": "Invalid parameters",
"code": "INVALID_PARAMETERS",
"details": {
"fieldErrors": {
"limit": ["Number must be between 1 and 100"]
}
}
}
500 Internal Server Error
{
"error": "Internal server error",
"code": "INTERNAL_SERVER_ERROR"
}
Funkcje techniczne
Cache'owanie
- Wyniki są cache'owane na 24 godziny dla lepszej wydajności
- Cache jest automatycznie odświeżany przy aktualizacji danych
Rate Limiting
- Implementacja sliding window: 10 zapytań na 10 sekund
- Limity są sprawdzane per użytkownik (na podstawie klucza API)
Walidacja
- Wszystkie parametry są walidowane przy użyciu biblioteki Zod
- Automatyczna konwersja typów dla parametrów numerycznych i boolean
Logowanie
- Wszystkie zapytania są logowane dla celów monitoringu
- Błędy są szczegółowo rejestrowane z kontekstem użytkownika
Najlepsze praktyki
- Używaj paginacji - Zawsze określaj
limit i offset dla dużych zbiorów danych - Optymalizuj filtry - Używaj jak najbardziej specyficznych filtrów aby zmniejszyć ilość zwracanych danych
- Monitoruj limity - Śledź swoje użycie API aby uniknąć przekroczenia limitów
- Cache wyniki - Jeśli to możliwe, cache'uj wyniki po stronie klienta
- Obsługuj błędy - Zawsze implementuj odpowiednią obsługę błędów w swojej aplikacji
Wsparcie
W przypadku problemów z API lub pytań technicznych, skontaktuj się z zespołem wsparcia technicznego.
