Dostawcy usług

Czym jest dostawca usług?

Dostawca usług to przedsiębiorstwo z pełnymi danymi prawnymi zarejestrowane w oficjalnej bazie danych osób prawnych kraju, w którym działa.

Ograniczenia bazy danych

Niestety baza danych dostawców usług może być niekompletna. Nie wszystkie firmy z ukraińskiego rejestru mogą być obecne w systemie.

Niestandardowi kontrahenci

Niestandardowi kontrahenci to utworzone przez użytkownika wpisy dla firm, których nie ma w oficjalnej bazie dostawców usług. Możesz ręcznie wprowadzić wszystkie niezbędne informacje.

Dostępne pola

Zasady walidacji

Dostęp użytkownika

Możesz zarządzać swoimi niestandardowymi kontrahentami na dedykowanej stronie:

REST API

API dla dostawców usług (tylko odczyt)

Dostawcy usług z oficjalnej bazy danych są dostępni przez punkty końcowe API tylko do odczytu:

Punkty końcowe API

GET /api/v1/service-providers              # List all active providers
GET /api/v1/service-providers/{id}         # Get specific provider details

Parametry zapytania

• page (integer, optional) - Page number, starts from 1. Default: 1
• limit (integer, optional) - Items per page, max 100. Default: 50
• search (string, optional) - Search by company name or EDRPOU code
• region (string, optional) - Filter by region (exact match)

Przykłady zapytań

Przykład 1: Pobierz pierwszych 50 aktywnych dostawców

Przypadek użycia: początkowe ładowanie listy dostawców usług

GET /api/v1/service-providers

Przykład 2: Wyszukiwanie po nazwie firmy

Przypadek użycia: użytkownik wpisuje nazwę firmy w polu wyszukiwania. Zwraca dostawców pasujących do zapytania w polach nazwy lub krótkiej nazwy.

GET /api/v1/service-providers?search=Kyiv Energy Company

Przykład 3: Wyszukiwanie po kodzie EDRPOU

Przypadek użycia: użytkownik wprowadza 8-cyfrowy kod EDRPOU z rachunku. Zwraca dokładne dopasowanie, jeśli dostawca istnieje w bazie danych.

GET /api/v1/service-providers?search=00131305

Przykład 4: Filtrowanie po regionie z paginacją

Przypadek użycia: pokaż dostawców tylko z określonego regionu, 20 na stronę. Przydatne do filtrowania lokalnych firm użyteczności publicznej.

GET /api/v1/service-providers?region=Kyiv&page=1&limit=20

Przykład 5: Pobierz szczegóły konkretnego dostawcy

Przypadek użycia: użytkownik klika dostawcę z listy, aby zobaczyć pełne szczegóły. Zwraca pełne informacje wraz z znacznikami czasu.

GET /api/v1/service-providers/1

Przykład odpowiedzi z listą

{
  "items": [
    {
      "id": 1,
      "edrpou": "00131305",
      "name": "Public Joint Stock Company Kyiv Energy",
      "short_name": "Kyiv Energy JSC",
      "legal_address": "Kyiv, Sakharov St, 139",
      "region": "Kyiv",
      "website": "https://kyivenergo.ua",
      "description": "Electricity distribution company serving Kyiv",
      "phone": "+380 44 467 0067",
      "email": "[email protected]",
      "is_active": true,
      "country": {
        "id": 1,
        "code": "UA",
        "name": {
          "uk": "Україна",
          "en": "Ukraine",
          "ru": "Украина",
          "pl": "Ukraina",
          "de": "Ukraine"
        }
      }
    }
  ],
  "total": 1234,
  "pages": 25
}

Pola odpowiedzi:

• items - Tablica obiektów dostawców (max 100 elementów na stronę)
• total - Całkowita liczba dostawców pasujących do kryteriów
• pages - Całkowita liczba stron (obliczona jako: ceil(total / limit))

Przykład szczegółowej odpowiedzi

{
  "id": 1,
  "edrpou": "00131305",
  "name": "Public Joint Stock Company Kyiv Energy",
  "website": "https://kyivenergo.ua",
  "description": "Electricity distribution company serving Kyiv",
  "phone": "+380 44 467 0067",
  "country": {
    "id": 1,
    "code": "UA",
    "name": {
      "uk": "Україна",
      "en": "Ukraine",
      "ru": "Украина",
      "pl": "Ukraina",
      "de": "Ukraine"
    }
  },
  "created_at": "2024-01-15T10:30:00+02:00",
  "updated_at": "2024-06-20T14:45:00+02:00"
}

Dodatkowe pola w widoku szczegółowym:

• created_at - Kiedy rekord został dodany do bazy danych (format ISO 8601)
• updated_at - Ostatnia modyfikacja rekordu (format ISO 8601)

Błędy

404 Not Found - Dostawca nie istnieje lub jest nieaktywny

{
  "error": "Service provider not found"
}

Przypadek użycia: nieprawidłowe ID lub dostawca został dezaktywowany w bazie danych

API dla niestandardowych kontrahentów (pełny CRUD)

Niestandardowi kontrahenci obsługują pełne operacje CRUD ze ścisłą walidacją:

Punkty końcowe API

GET    /api/v1/user/custom-contragents           # List all user contragents
POST   /api/v1/user/custom-contragents           # Create new contragent
GET    /api/v1/user/custom-contragents/{id}      # Get contragent details
PUT    /api/v1/user/custom-contragents/{id}      # Update contragent
DELETE /api/v1/user/custom-contragents/{id}      # Delete contragent

Wymagana autentykacja: Wszystkie punkty końcowe wymagają uwierzytelnienia użytkownika. Możesz zarządzać tylko własnymi kontrahentami.

Przykłady zapytań

Przykład 1: Pobierz listę swoich kontrahentów

Przypadek użycia: wyświetlenie wszystkich kontrahentów użytkownika w liście rozwijanej formularza wydatków lub na stronie zarządzania.

GET /api/v1/user/custom-contragents

Przykład 2: Utwórz nowego kontrahenta

Przypadek użycia: użytkownik dodaje nową firmę, której nie ma w oficjalnej bazie danych. Wymagane jest tylko pole nazwy, wszystkie inne pola są opcjonalne, ale walidowane jeśli podane.

POST /api/v1/user/custom-contragents
Content-Type: application/json

{
  "name": "Example Company LLC",
  "short_name": "Example Co",
  "legal_form": "LLC",
  "tax_number": "12345678",
  "vat_number": "123456789012",
  "iban": "UA123456789012345678901234567",
  "bank_name": "PrivatBank",
  "bank_mfo": "305299",
  "swift": "PBANUA2X",
  "email": "[email protected]",
  "phone": "+380 44 123 4567",
  "website": "https://example.com",
  "director_name": "John Doe",
  "legal_address": "Kyiv, Khreshchatyk St, 1",
  "registration_date": "2020-01-15"
}

Przykład 3: Pobierz szczegóły kontrahenta

Przypadek użycia: wyświetlenie pełnych informacji o konkretnym kontrahencie na stronie szczegółów.

GET /api/v1/user/custom-contragents/01a06b0b-5f36-7d8b-b211-b03c9c7d9a24

Przykład 4: Zaktualizuj kontrahenta

Przypadek użycia: użytkownik edytuje informacje o kontrahencie. Wysyłaj tylko pola wymagające aktualizacji. Wszystkie zasady walidacji obowiązują.

PUT /api/v1/user/custom-contragents/01a06b0b-5f36-7d8b-b211-b03c9c7d9a24
Content-Type: application/json

{
  "phone": "+380 44 999 8888",
  "email": "[email protected]",
  "website": "https://new-website.com"
}

Przykład 5: Usuń kontrahenta

Przypadek użycia: użytkownik usuwa kontrahenta, który nie jest już potrzebny. Nie można usunąć, jeśli kontrahent jest używany w wydatkach.

DELETE /api/v1/user/custom-contragents/01a06b0b-5f36-7d8b-b211-b03c9c7d9a24

Przykład odpowiedzi z listą

{
  "contragents": [
    {
      "id": 1,
      "name": "Example Company LLC",
      "short_name": "Example Co",
      "legal_form": "LLC",
      "tax_number": "12345678",
      "vat_number": "123456789012",
      "iban": "UA123456789012345678901234567",
      "bank_name": "PrivatBank",
      "bank_mfo": "305299",
      "swift": "PBANUA2X",
      "email": "[email protected]",
      "phone": "+380 44 123 4567",
      "website": "https://example.com",
      "director_name": "John Doe",
      "contact_person": "Jane Smith",
      "legal_address": "Kyiv, Khreshchatyk St, 1",
      "actual_address": "Kyiv, Khreshchatyk St, 1",
      "registration_date": "2020-01-15",
      "notes": "Primary utility provider",
      "created_at": "2024-01-15T10:30:00+02:00",
      "updated_at": "2024-06-20T14:45:00+02:00"
    }
  ]
}

Odpowiedź na utworzenie/aktualizację

{
  "id": 1,
  "name": "Example Company LLC",
  "message": "Contragent created successfully"
}

Odpowiedź na usunięcie

{
  "message": "Contragent deleted successfully"
}

Odpowiedź z błędami walidacji

Zwracane z HTTP 400, gdy walidacja się nie powiedzie. Zawiera nazwy pól i komunikaty błędów.

{
  "error": "Validation failed",
  "violations": {
    "name": "Name must be at least 3 characters long",
    "tax_number": "Tax number must be 8-12 digits",
    "iban": "Invalid IBAN format",
    "email": "Invalid email address"
  }
}

403 Zabroniony - Dostęp zabroniony

Zwracane przy próbie dostępu lub modyfikacji kontrahenta należącego do innego użytkownika.

{
  "error": "Access denied"
}

404 Nie znaleziono - Kontrahent nie znaleziony

Zwracane, gdy kontrahent o podanym ID nie istnieje.

{
  "error": "Contragent not found"
}

409 Konflikt - Nie można usunąć

Zwracane przy próbie usunięcia kontrahenta używanego w wydatkach lub innych rekordach.

{
  "error": "Cannot delete contragent. It is used in 5 expense records."
}

Swagger / OpenAPI

Pełna dokumentacja API jest dostępna w Swagger UI: