Dienstleister

Was ist ein Dienstleister?

Dienstleister ist ein Unternehmen mit vollständigen rechtlichen Details, das in der offiziellen Datenbank juristischer Personen des Landes, in dem es tätig ist, registriert ist.

Datenbankbeschränkungen

Leider kann die Datenbank der Dienstleister unvollständig sein. Nicht alle Unternehmen aus dem ukrainischen Register sind möglicherweise im System vorhanden.

Benutzerdefinierte Vertragspartner

Benutzerdefinierte Vertragspartner sind vom Benutzer erstellte Einträge für Unternehmen, die nicht in der offiziellen Dienstleisterdatenbank enthalten sind. Sie können alle erforderlichen Informationen manuell eingeben.

Verfügbare Felder

Validierungsregeln

Benutzerzugriff

Sie können Ihre benutzerdefinierten Vertragspartner auf der dedizierten Seite verwalten:

REST API

API für Dienstleister (nur Lesen)

Dienstleister aus der offiziellen Datenbank sind über schreibgeschützte API-Endpunkte verfügbar:

API-Endpunkte

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

Abfrageparameter

• 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)

Anforderungsbeispiele

Beispiel 1: Erste 50 aktive Anbieter abrufen

Anwendungsfall: Erstes Laden der Dienstleisterliste

GET /api/v1/service-providers

Beispiel 2: Suche nach Firmennamen

Anwendungsfall: Benutzer gibt Firmennamen in Suchfeld ein. Gibt Anbieter zurück, die der Suchanfrage im Namen- oder Kurznamenfeld entsprechen.

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

Beispiel 3: Suche nach EDRPOU-Code

Anwendungsfall: Benutzer gibt 8-stelligen EDRPOU-Code von Rechnung ein. Gibt exakte Übereinstimmung zurück, wenn Anbieter in Datenbank existiert.

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

Beispiel 4: Nach Region filtern mit Paginierung

Anwendungsfall: Anbieter nur aus bestimmter Region anzeigen, 20 pro Seite. Nützlich zum Filtern lokaler Versorgungsunternehmen.

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

Beispiel 5: Spezifische Anbieterdetails abrufen

Anwendungsfall: Benutzer klickt auf Anbieter aus Liste, um vollständige Details zu sehen. Gibt vollständige Informationen einschließlich Zeitstempel zurück.

GET /api/v1/service-providers/1

Beispiel für Listenantwort

{
  "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
}

Antwortfelder:

• items - Array von Anbieterobjekten (max. 100 Elemente pro Seite)
• total - Gesamtzahl der Anbieter, die Ihren Kriterien entsprechen
• pages - Gesamtzahl der Seiten (berechnet als: ceil(total / limit))

Beispiel für detaillierte Antwort

{
  "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"
}

Zusätzliche Felder in Detailansicht:

• created_at - Wann der Datensatz zur Datenbank hinzugefügt wurde (ISO 8601-Format)
• updated_at - Letzte Änderung des Datensatzes (ISO 8601-Format)

Fehlerantworten

404 Not Found - Anbieter existiert nicht oder ist inaktiv

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

Anwendungsfall: Ungültige ID oder Anbieter wurde in Datenbank deaktiviert

API für benutzerdefinierte Vertragspartner (vollständiger CRUD)

Benutzerdefinierte Vertragspartner unterstützen vollständige CRUD-Operationen mit strenger Validierung:

API-Endpunkte

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

Authentifizierung erforderlich: Alle Endpunkte erfordern Benutzerauthentifizierung. Sie können nur Ihre eigenen Vertragspartner verwalten.

Anforderungsbeispiele

Beispiel 1: Liste Ihrer Vertragspartner abrufen

Anwendungsfall: Anzeige aller benutzerdefinierten Vertragspartner in Dropdown-Liste des Ausgabenformulars oder auf Verwaltungsseite.

GET /api/v1/user/custom-contragents

Beispiel 2: Neuen Vertragspartner erstellen

Anwendungsfall: Benutzer fügt neues Unternehmen hinzu, das nicht in offizieller Datenbank ist. Nur Namensfeld erforderlich, alle anderen Felder optional, aber validiert falls angegeben.

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"
}

Beispiel 3: Vertragspartner-Details abrufen

Anwendungsfall: Vollständige Informationen über bestimmten Vertragspartner auf Detailseite anzeigen.

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

Beispiel 4: Vertragspartner aktualisieren

Anwendungsfall: Benutzer bearbeitet Vertragspartner-Informationen. Nur zu aktualisierende Felder senden. Alle Validierungsregeln gelten.

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"
}

Beispiel 5: Vertragspartner löschen

Anwendungsfall: Benutzer entfernt nicht mehr benötigten Vertragspartner. Kann nicht gelöscht werden, wenn Vertragspartner in Ausgaben verwendet wird.

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

Beispiel für Listenantwort

{
  "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"
    }
  ]
}

Erfolgsantwort auf Erstellen/Aktualisieren

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

Erfolgsantwort auf Löschen

{
  "message": "Contragent deleted successfully"
}

Antwort mit Validierungsfehlern

Mit HTTP 400 zurückgegeben, wenn Validierung fehlschlägt. Enthält Feldnamen und Fehlermeldungen.

{
  "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 Verboten - Zugriff verweigert

Wird zurückgegeben beim Versuch, auf Vertragspartner eines anderen Benutzers zuzugreifen oder ihn zu ändern.

{
  "error": "Access denied"
}

404 Nicht gefunden - Vertragspartner nicht gefunden

Wird zurückgegeben, wenn Vertragspartner mit angegebener ID nicht existiert.

{
  "error": "Contragent not found"
}

409 Konflikt - Kann nicht gelöscht werden

Wird zurückgegeben beim Versuch, Vertragspartner zu löschen, der in Ausgaben oder anderen Datensätzen verwendet wird.

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

Swagger / OpenAPI

Vollständige API-Dokumentation ist in Swagger UI verfügbar: