README

Ein Laravel-Package zur Integration des Schweizer UID-Webservices (Unternehmens-Identifikationsnummer) vom Bundesamt für Statistik (BFS).

Basiert auf der offiziellen API Version 5.0

📄 Offizielle Dokumentation (PDF)

Features

• 🔍 Unternehmen per UID-Nummer abrufen (GetByUID)
• 🔎 Unternehmen nach Name, Ort, Kanton suchen (Search)
• ✅ UID-Nummern validieren (ValidateUID)
• 💰 MWST-Nummern validieren (ValidateVatNumber)
• 📦 Automatisches Caching für bessere Performance
• 🏷️ Laravel Validation Rule
• 💡 Einfache Facade für schnellen Zugriff

Webservice Endpoints

Installation

composer require ecolabor/laravel-swiss-uid-search

Konfiguration

Veröffentlichen Sie die Konfigurationsdatei:

php artisan vendor:publish --tag=swiss-uid-config

Umgebungsvariablen

# Umgebung: production oder test
SWISS_UID_ENVIRONMENT=production

# Sprache: 1=DE, 2=FR, 3=IT, 4=EN
SWISS_UID_LANGUAGE=1

# Cache-Einstellungen
SWISS_UID_CACHE_ENABLED=true
SWISS_UID_CACHE_TTL=3600

# Such-Einstellungen
SWISS_UID_MAX_RESULTS=100
SWISS_UID_SEARCH_MODE=auto

# Partner Services (optional, für erweiterte Funktionen)
SWISS_UID_PARTNER_USERNAME=your_username_sa
SWISS_UID_PARTNER_PASSWORD=your_password

Verwendung

Unternehmen per UID abrufen

use Ecolabor\SwissUid\Facades\SwissUid;

// Mit formatierter UID
$company = SwissUid::getByUid('CHE-123.456.789');

// Oder nur mit Ziffern
$company = SwissUid::getByUid('123456789');

if ($company) {
    echo $company->organisationName;         // Firmenname
    echo $company->uidFormatted;             // CHE-123.456.789
    echo $company->address->getOneLiner();   // Strasse 1, 8000 Zürich
    echo $company->legalFormText;            // Aktiengesellschaft
    echo $company->vatNumberFormatted;       // CHE-123.456.789 MWST
    echo $company->isActive();               // true/false
    echo $company->isVatRegistered();        // true/false
    echo $company->isInCommercialRegister(); // true/false
}

Nach Unternehmen suchen

use Ecolabor\SwissUid\Facades\SwissUid;

// Nach Name suchen
$result = SwissUid::searchByName('Migros');

// Nach Ort suchen
$result = SwissUid::searchByLocation('Zürich');

// Kombinierte Suche mit allen Parametern
$result = SwissUid::search([
    'organisationName' => 'AG',
    'town' => 'Bern',
    'canton' => 'BE',
    'zipCode' => '3000',
    'legalFormId' => 6,                        // Aktiengesellschaft
    'uidregStatusEnterpriseActive' => true,    // Nur aktive
    'maxNumberOfRecords' => 50,
    'searchMode' => 'auto',                    // auto, exact, wild
]);

foreach ($result->entities as $company) {
    echo "{$company->organisationName} - {$company->uidFormatted}\n";
}

// Ergebnisse filtern
$activeOnly = $result->onlyActive();
$vatRegistered = $result->onlyVatRegistered();
$inHr = $result->onlyInCommercialRegister();

// Für Dropdowns
$options = $result->toSelectOptions();
// ['123456789' => 'Firma AG (CHE-123.456.789)', ...]

UID validieren

use Ecolabor\SwissUid\Facades\SwissUid;

// Prüfen ob UID gültig ist
if (SwissUid::validateUid('CHE-123.456.789')) {
    echo "UID ist gültig!";
}

// MWST-Nummer validieren
if (SwissUid::validateVatNumber('CHE-123.456.789')) {
    echo "MWST-Nummer ist gültig!";
}

Validation Rule

use Ecolabor\SwissUid\Rules\ValidSwissUid;

// Nur Format validieren (schnell, kein API-Call)
$request->validate([
    'uid' => ['required', ValidSwissUid::format()],
]);

// Format + Existenz im Register prüfen (API-Call)
$request->validate([
    'uid' => ['required', ValidSwissUid::exists()],
]);

UID formatieren

use Ecolabor\SwissUid\Facades\SwissUid;

$formatted = SwissUid::formatUid('123456789');
// Ergebnis: CHE-123.456.789

$mwst = SwissUid::formatMwst('123456789');
// Ergebnis: CHE-123.456.789 MWST

$normalized = SwissUid::normalizeUid('CHE-123.456.789');
// Ergebnis: 123456789

UidEntity Eigenschaften

Basis-Informationen

Status-Informationen (UID-Register)

MWST-Informationen

Handelsregister-Informationen

Adresse

Address Eigenschaften (eCH-0010)

$address = $company->address;

$address->street;              // Strasse
$address->houseNumber;         // Hausnummer
$address->swissZipCode;        // PLZ
$address->town;                // Ort
$address->countryIdISO2;       // Land (CH)

// Hilfsmethoden
$address->getStreetLine();     // "Bahnhofstrasse 1"
$address->getCityLine();       // "8000 Zürich"
$address->getFullAddress();    // Mehrzeilige Adresse
$address->getOneLiner();       // "Bahnhofstrasse 1, 8000 Zürich"
$address->isSwiss();           // true/false

Rechtsformen (Legal Forms)

Fehlerbehandlung

use Ecolabor\SwissUid\Exceptions\UidApiException;

try {
    $company = SwissUid::getByUid('invalid');
} catch (UidApiException $e) {
    // API-Fehler behandeln
    logger()->error('UID API Error: ' . $e->getMessage());
}

// Oder mit Search (gibt UidSearchResult zurück)
$result = SwissUid::search(['name' => 'Test']);

if ($result->hasError()) {
    echo "Fehler: " . $result->errorMessage;
    echo "Code: " . $result->errorCode;
}

Testing

composer test

Ressourcen

• UID-Register Webseite
• BFS Dokumentation
• API Spezifikation (PDF)
• UID Helpdesk

Lizenz

MIT License. Siehe LICENSE für weitere Informationen.

Credits

• ecolabor GmbH
• Bundesamt für Statistik (BFS)