Schnellstart

Integrieren Sie die EIC-X Validation API in wenigen Minuten.

1. API-Key erhalten

Registrieren Sie sich unter eicchecker.ch/signup und generieren Sie Ihren API-Key im Dashboard.

2. Erste Anfrage

javascript

// Installation
// npm install axios (or use fetch)

// Single validation
async function validateCode(code) {
  try {
    const response = await fetch('https://eicchecker.ch/api/v1/validate', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY'
      },
      body: JSON.stringify({ code })
    });

    const data = await response.json();
    
    if (data.valid) {
      console.log('Valid code:', data.normalized);
      console.log('Entity:', data.name);
      console.log('Company:', data.company);
    } else {
      console.log('Invalid code');
    }
    
    return data;
  } catch (error) {
    console.error('API Error:', error);
    throw error;
  }
}

// Usage
validateCode('12X-0000000002-J');

3. Response verarbeiten

json

{
  "valid": true,
  "normalized": "12X-0000000002-J",
  "name": "Swissgrid AG",
  "function": "TSO",
  "company": "Swissgrid AG",
  "zip": "5001",
  "city": "Aarau",
  "date": "2020-01-01",
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "duration": "45ms"
}

Feld-Beschreibungen:

valid: Boolean - Gibt an, ob der Code gültig ist
normalized: String - Normierte Version des Codes
name: String - Name der Entität
function: String - Funktion (TSO, DSO, SUP, MSP)
company: String - Firmenname
zip: String - Postleitzahl
city: String - Ort
date: String - Registrierungsdatum (ISO 8601)

Authentifizierung

Die EIC-X Validation API verwendet API-Key-basierte Authentifizierung über HTTP Header.

API-Key Header

Fügen Sie Ihren API-Key als Bearer Token im Authorization Header hinzu:

text

Authorization: Bearer YOUR_API_KEY

Beispiel Request

bash

curl -X POST https://eicchecker.ch/api/v1/validate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_1234567890abcdef" \
  -d '{"code": "12X-0000000002-J"}'

Sicherheitshinweise

Niemals API-Keys im Frontend-Code oder öffentlichen Repositories speichern
API-Keys sollten nur auf dem Server verwendet werden
Bei Kompromittierung sofort einen neuen Key generieren
Verwenden Sie unterschiedliche Keys für Development und Production

Rate Limits

Rate Limits schützen die API vor Missbrauch und gewährleisten faire Nutzung für alle. Die Rate-Limits werden automatisch basierend auf Ihrem Abonnement-Plan angewendet.

Standard Limits

Free Tier:100 Requests/Monat

Pro Tier:10,000 Requests/Monat

Enterprise:Unbegrenzt

Rate Limit Headers

Die API sendet Rate Limit Informationen in den Response Headers bei jeder Anfrage mit API-Key:

text

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9995
X-RateLimit-Reset: 1642680000

Hinweis: Rate-Limits werden nur für authentifizierte Anfragen (mit API-Key) geprüft. Anfragen ohne API-Key sind nicht limitiert, werden aber auch nicht geloggt.

Rate Limit Exceeded

Bei Überschreitung erhalten Sie einen 429 Too Many Requests Status. Das Limit wird monatlich zurückgesetzt (am ersten Tag des Monats).

json

{
  "error": "Rate limit exceeded",
  "retryAfter": 3600,
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

retryAfter: Sekunden bis zum Reset des Limits (Unix-Timestamp)

POST /v1/validate

Validiert einen einzelnen EIC-X Code und gibt detaillierte Informationen zurück.

Request

Endpoint:

https://eicchecker.ch/api/v1/validate(Empfohlen - Main Domain)

https://api.eicchecker.ch/api/v1/validate(Alternative - Subdomain, falls konfiguriert)

⚠️ Die Main Domain URL funktioniert immer. Die Subdomain muss in Vercel konfiguriert werden.

Method:

POST

Content-Type:

application/json

Headers

Header	Required	Description
`Authorization`	Required	Bearer YOUR_API_KEY
`Content-Type`	Required	application/json

Body Parameters

Parameter	Type	Required	Description
`code`	string	Yes	Der zu validierende EIC-X Code

Beispiel Request

javascript

// Installation
// npm install axios (or use fetch)

// Single validation
async function validateCode(code) {
  try {
    const response = await fetch('https://eicchecker.ch/api/v1/validate', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY'
      },
      body: JSON.stringify({ code })
    });

    const data = await response.json();
    
    if (data.valid) {
      console.log('Valid code:', data.normalized);
      console.log('Entity:', data.name);
      console.log('Company:', data.company);
    } else {
      console.log('Invalid code');
    }
    
    return data;
  } catch (error) {
    console.error('API Error:', error);
    throw error;
  }
}

// Usage
validateCode('12X-0000000002-J');

Response

json

{
  "valid": true,
  "normalized": "12X-0000000002-J",
  "name": "Swissgrid AG",
  "function": "TSO",
  "company": "Swissgrid AG",
  "zip": "5001",
  "city": "Aarau",
  "date": "2020-01-01",
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "duration": "45ms"
}

POST /v1/validate (Batch)

Validiert mehrere EIC-X Codes in einer einzigen Anfrage. Maximale Anzahl: 100 Codes pro Request.

Body Parameters

Parameter	Type	Required	Description
`codes`	string[]	Yes	Array von EIC-X Codes (max. 100)

Beispiel Request

javascript

// Batch validation
async function validateCodes(codes) {
  try {
    const response = await fetch('https://eicchecker.ch/api/v1/validate', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY'
      },
      body: JSON.stringify({ codes })
    });

    const data = await response.json();
    
    console.log(`Validated ${data.count} codes`);
    console.log(`${data.validCount} valid codes`);
    
    data.results.forEach(result => {
      if (result.valid) {
        console.log(`${result.code}: ${result.name}`);
      }
    });
    
    return data;
  } catch (error) {
    console.error('API Error:', error);
    throw error;
  }
}

// Usage
validateCodes(['12X-0000000002-J', '12X-0000000003-K']);

Response

json

{
  "results": [
    {
      "code": "12X-0000000002-J",
      "valid": true,
      "normalized": "12X-0000000002-J",
      "name": "Swissgrid AG",
      "function": "TSO",
      "company": "Swissgrid AG"
    },
    {
      "code": "12X-0000000003-K",
      "valid": false,
      "normalized": "12X-0000000003-K",
      "message": "EIC-X code not found in database"
    }
  ],
  "count": 2,
  "validCount": 1,
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "duration": "120ms"
}

GET /v1/validate

Alternative GET-Methode für einfache Validierungen ohne Authentifizierung (nur für Testing).

Query Parameters

Parameter	Type	Required	Description
`code`	string	Yes	Der zu validierende EIC-X Code

Beispiel Request

javascript

// GET request (simpler, no auth required for testing)
async function validateCodeGet(code) {
  try {
    const response = await fetch(
      `https://eicchecker.ch/api/v1/validate?code=${encodeURIComponent(code)}`
    );
    
    const data = await response.json();
    return data;
  } catch (error) {
    console.error('API Error:', error);
    throw error;
  }
}

// Usage
validateCodeGet('12X-0000000002-J');

Success Response

Bei erfolgreicher Validierung erhalten Sie detaillierte Informationen über den EIC-X Code.

json

{
  "valid": true,
  "normalized": "12X-0000000002-J",
  "name": "Swissgrid AG",
  "function": "TSO",
  "company": "Swissgrid AG",
  "zip": "5001",
  "city": "Aarau",
  "date": "2020-01-01",
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "duration": "45ms"
}

Error Handling

Die API verwendet standardisierte Error-Responses mit aussagekräftigen Fehlermeldungen.

Error Response Format

json

{
  "valid": false,
  "error": "Invalid EIC-X code format",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

Häufige Fehler

400 Bad Request

Ungültige Anfrage:

json

{
  "valid": false,
  "error": "Missing code parameter",
  "requestId": "..."
}

429 Too Many Requests

Rate Limit überschritten:

json

{
  "error": "Rate limit exceeded",
  "retryAfter": 3600
}

500 Internal Server Error

Server-Fehler:

json

{
  "valid": false,
  "error": "Unknown error occurred",
  "requestId": "..."
}

Status Codes

Status Code	Description
`200`	Erfolgreiche Anfrage
`400`	Ungültige Anfrage (fehlende/ungültige Parameter)
`401`	Unauthorized (ungültiger API-Key)
`429`	Rate Limit überschritten
`500`	Interner Server-Fehler

Code Examples

Vollständige, funktionsfähige Beispiele für verschiedene Programmiersprachen.

JavaScript/TypeScript

javascript

// Installation
// npm install axios (or use fetch)

// Single validation
async function validateCode(code) {
  try {
    const response = await fetch('https://eicchecker.ch/api/v1/validate', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY'
      },
      body: JSON.stringify({ code })
    });

    const data = await response.json();
    
    if (data.valid) {
      console.log('Valid code:', data.normalized);
      console.log('Entity:', data.name);
      console.log('Company:', data.company);
    } else {
      console.log('Invalid code');
    }
    
    return data;
  } catch (error) {
    console.error('API Error:', error);
    throw error;
  }
}

// Usage
validateCode('12X-0000000002-J');

Python

python

# Installation
# pip install requests

import requests

def validate_code(code):
    """Validate a single EIC-X code"""
    url = 'https://eicchecker.ch/api/v1/validate'
    headers = {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY'
    }
    payload = {'code': code}
    
    try:
        response = requests.post(url, json=payload, headers=headers)
        response.raise_for_status()
        data = response.json()
        
        if data.get('valid'):
            print(f"Valid code: {data['normalized']}")
            print(f"Entity: {data['name']}")
            print(f"Company: {data['company']}")
        else:
            print("Invalid code")
        
        return data
    except requests.exceptions.RequestException as e:
        print(f"API Error: {e}")
        raise

# Usage
validate_code('12X-0000000002-J')

cURL

bash

# Single validation
curl -X POST https://eicchecker.ch/api/v1/validate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "code": "12X-0000000002-J"
  }'

Postman

Schritt-für-Schritt Anleitung für die Verwendung der API in Postman.

1. Request konfigurieren

Method & URL:

Method: POST
URL (Empfohlen - Main Domain): https://eicchecker.ch/api/v1/validate
URL (Alternative - Subdomain): https://api.eicchecker.ch/api/v1/validate
⚠️ Wichtig: Kein Leerzeichen am Ende der URL!

Hinweis: Verwenden Sie die Main Domain URL für zuverlässige Verbindungen. Falls Sie einen DEPLOYMENT_NOT_FOUND Fehler mit der Subdomain erhalten, ist die Subdomain noch nicht in Vercel konfiguriert.

2. Headers hinzufügen

Gehen Sie zum Headers Tab und fügen Sie folgende Header hinzu:

Key	Value	Required
`Content-Type`	`application/json`	✅ Ja
`Authorization`	`Bearer YOUR_API_KEY`	⚠️ Optional (empfohlen)

Hinweis: Ersetzen Sie YOUR_API_KEY mit Ihrem tatsächlichen API-Key (z.B. eicx_uSXHUhMAF6xQ-1e8KS3Lj9E4WQBbGPYdqlESSAVNxsc)

3. Body konfigurieren

Gehen Sie zum Body Tab:

Wählen Sie raw
Wählen Sie im Dropdown rechts JSON
Fügen Sie folgenden JSON-Code ein:

Für einzelne Validierung:

json

{
  "code": "12X-0000000002-J"
}

Für Batch-Validierung:

json

{
  "codes": [
    "12X-0000000002-J",
    "12X-0000000003-K"
  ]
}

4. Request senden

Klicken Sie auf Send und Sie sollten eine Antwort erhalten:

json

{
  "valid": true,
  "normalized": "12X-0000000002-J",
  "name": "AGE_SA_CHIASS-ST",
  "function": "Capacity Trader",
  "company": "Acqua Gas Elettricità SA Chiasso",
  "zip": "6830",
  "city": "Chiasso",
  "date": "24.05.2008",
  "requestId": "0b5637c0-8595-4853-889b-f9e58192c29f",
  "timestamp": "2025-12-15T10:51:49.518Z",
  "duration": "130ms"
}

Häufige Fehler

DEPLOYMENT_NOT_FOUND (404):
- Überprüfen Sie, dass die URL korrekt ist und kein Leerzeichen am Ende hat
- Lösung: Verwenden Sie https://eicchecker.ch/api/v1/validate statt https://api.eicchecker.ch/api/v1/validate
- Die Subdomain api.eicchecker.ch muss möglicherweise erst in Vercel als Domain konfiguriert werden
400 Bad Request: Stellen Sie sicher, dass Content-Type: application/json gesetzt ist
401 Unauthorized: Überprüfen Sie, dass der Authorization Header im Format Bearer YOUR_API_KEY ist
JSON Parse Error: Stellen Sie sicher, dass der Body-Tab auf raw und JSON eingestellt ist

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

type ValidateRequest struct {
    Code string `json:"code"`
}

type ValidateResponse struct {
    Valid      bool   `json:"valid"`
    Normalized string `json:"normalized"`
    Name       string `json:"name,omitempty"`
    Company    string `json:"company,omitempty"`
    Function   string `json:"function,omitempty"`
    Zip        string `json:"zip,omitempty"`
    City       string `json:"city,omitempty"`
    Date       string `json:"date,omitempty"`
}

func validateCode(code string) (*ValidateResponse, error) {
    url := "https://eicchecker.ch/api/v1/validate"
    
    reqBody := ValidateRequest{Code: code}
    jsonData, err := json.Marshal(reqBody)
    if err != nil {
        return nil, err
    }
    
    req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    if err != nil {
        return nil, err
    }
    
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    
    body, err := io.ReadAll(resp.Body)
    if err != nil {
        return nil, err
    }
    
    var result ValidateResponse
    if err := json.Unmarshal(body, &result); err != nil {
        return nil, err
    }
    
    return &result, nil
}

func main() {
    result, err := validateCode("12X-0000000002-J")
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }
    
    if result.Valid {
        fmt.Printf("Valid code: %s\n", result.Normalized)
        fmt.Printf("Entity: %s\n", result.Name)
    } else {
        fmt.Println("Invalid code")
    }
}

Best Practices

Fehlerbehandlung

Implementieren Sie Retry-Logik mit exponential backoff
Behandeln Sie Rate Limit Errors (429) mit entsprechenden Wartezeiten
Loggen Sie API-Fehler für Debugging und Monitoring
Validieren Sie Eingaben vor dem API-Call

javascript

// Beispiel: Retry-Logik mit exponential backoff
async function validateWithRetry(code, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch('https://eicchecker.ch/api/v1/validate', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': 'Bearer YOUR_API_KEY'
        },
        body: JSON.stringify({ code })
      });

      if (response.status === 429) {
        const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }

      if (!response.ok) {
        throw new Error(`API Error: ${response.status}`);
      }

      return await response.json();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
    }
  }
}

Caching-Strategien

Cachen Sie erfolgreiche Validierungen (TTL: 24h)
Nutzen Sie ETag/If-None-Match Headers wenn verfügbar
Vermeiden Sie unnötige Re-Validierungen
Implementieren Sie Cache-Invalidation bei Bedarf

javascript

// Beispiel: Caching mit localStorage (Browser)
const CACHE_TTL = 24 * 60 * 60 * 1000; // 24 Stunden

async function validateWithCache(code) {
  const cacheKey = `eicx_${code}`;
  const cached = localStorage.getItem(cacheKey);
  
  if (cached) {
    const { data, timestamp } = JSON.parse(cached);
    if (Date.now() - timestamp < CACHE_TTL) {
      return data;
    }
  }
  
  const data = await validateCode(code);
  localStorage.setItem(cacheKey, JSON.stringify({
    data,
    timestamp: Date.now()
  }));
  
  return data;
}

Performance-Tipps

Nutzen Sie Batch-Endpoint für mehrere Codes
Vermeiden Sie parallele Requests (Rate Limit beachten)
Implementieren Sie Request-Queuing für grosse Mengen
Nutzen Sie GET-Endpoint für einfache Validierungen ohne Auth

javascript

// Beispiel: Batch-Validierung statt einzelner Requests
async function validateMultipleCodes(codes) {
  // ❌ Schlecht: Viele einzelne Requests
  // const results = await Promise.all(
  //   codes.map(code => validateCode(code))
  // );
  
  // ✅ Gut: Ein Batch-Request
  const response = await fetch('https://eicchecker.ch/api/v1/validate', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_API_KEY'
    },
    body: JSON.stringify({ codes })
  });
  
  const data = await response.json();
  return data.results;
}

Support

Benötigen Sie Hilfe? Wir sind für Sie da.

Kontakt

E-Mail: hello@eicchecker.ch

Antwortzeit: Innerhalb von 24 Stunden (Mo-Fr)

Status Page

API-Status und Uptime-Informationen

Status anzeigen

Response-Zeit-Garantien

Free Tier:< 2000ms (95. Perzentil)

Pro Tier:< 1000ms (95. Perzentil)

Enterprise:< 500ms (95. Perzentil)

GitHub

Issues, Discussions und Code-Beispiele

GitHub öffnen

FAQ

Wie erhalte ich einen API-Key?

Registrieren Sie sich auf eicchecker.ch und generieren Sie Ihren API-Key im Dashboard unter "API Keys".

Gibt es ein Limit für Batch-Requests?

Ja, Sie können maximal 100 Codes pro Batch-Request validieren. Für grössere Mengen teilen Sie die Codes in mehrere Batches auf.

Ist die API kostenlos?

Wir bieten einen kostenlosen Tier mit 100 Requests pro Monat. Für höhere Limits und zusätzliche Features stehen Pro- und Enterprise-Pläne zur Verfügung.

Wie aktuell sind die Daten?

Die EIC-X Code-Datenbank wird täglich aktualisiert und enthält alle registrierten Codes aus der Swissgrid-Datenbank.

API Dokumentation

Schnellstart

1. API-Key erhalten

2. Erste Anfrage

3. Response verarbeiten

Authentifizierung

API-Key Header

Beispiel Request

Rate Limits

Rate Limit Headers

POST /v1/validate

Request

Headers

Body Parameters

Beispiel Request

Response

POST /v1/validate (Batch)

Body Parameters

Beispiel Request

Response

GET /v1/validate

Query Parameters

Beispiel Request

Success Response

Error Handling

Error Response Format

Häufige Fehler

Status Codes

Code Examples

JavaScript/TypeScript

Python

cURL

Postman

Go

Best Practices

Fehlerbehandlung

Caching-Strategien

Performance-Tipps

Support

FAQ