Erste Schritte

API-Schlüssel und Secret erhalten

Bitte kontaktieren Sie uns, um einen API-Schlüssel und ein Secret für Ihre Anforderungen zu erhalten.

Sobald Sie über Ihren API-Schlüssel und Ihr Secret verfügen, müssen Sie beide zur Authentifizierung bei der API verwenden. Wir nutzen HMAC-Signaturverifizierung zur Validierung der Anfragen.

Signierte Anfragen senden

Der API-Schlüssel muss über den x-api-key Header gesendet werden.

Das API-Secret wird verwendet, um eine HMAC-Signatur inklusive Zeitstempel zu generieren. Die Signatur muss über den x-signature Header gesendet werden.

Alle Anfragen müssen außerdem den x-req-timestamp Header enthalten.

Signaturerstellungsprozess

Die Signaturerstellung folgt diesen Schritten:

1. Secret hashen mit SHA256:

   hashed_secret = SHA256(your_secret)

2. Zu signierende Payload zusammenstellen im folgenden Format:

   payload = METHOD:URL_PATH:TIMESTAMP:BODY

   • METHOD: HTTP-Methode (GET, POST, etc.)
   • URL_PATH: Anfragepfad inklusive Query-Parameter (z. B. /rest/v1/sites?from=2024-01-01)
   • TIMESTAMP: Unix-Zeitstempel in Sekunden
   • BODY: Anfrage-Body als JSON-String (leerer String, wenn kein Body vorhanden)

3. HMAC-SHA256-Signatur generieren mit dem gehashten Secret:

   signature = HMAC-SHA256(payload, hashed_secret)

4. In den Request-Headern senden als hexadezimal-kodierter String

Implementierungsbeispiel

Warnung

Beachten Sie, dass wir den Schlüssel, den Zeitstempel und die Signatur übermitteln. Das Secret darf niemals über das Netzwerk übertragen werden.

const crypto = require('crypto');

function makeSignedRequest(method, path, body, apiKey, apiSecret) {
    const timestamp = Math.floor(Date.now() / 1000);

    // 1. Hash the secret using SHA256
    const hashedSecret = crypto
        .createHash('sha256')
        .update(apiSecret)
        .digest('hex');

    // 2. Construct the payload to sign
    let payloadToSign = `${method}:${path}:${timestamp}:`;
    if (body) {
        payloadToSign += JSON.stringify(body);
    }

    // 3. Create the signature using the hashed secret
    const signature = crypto
        .createHmac('sha256', hashedSecret)
        .update(payloadToSign)
        .digest('hex');

    // 4. Send headers
    return fetch(`https://chargepilot-api.tmhusa.energy/rest/v1${path}`, {
        method: method,
        ...(body ? { body: JSON.stringify(body) } : {}),
        headers: {
            'Content-Type': 'application/json',
            'x-api-key': apiKey,
            'x-req-timestamp': timestamp.toString(),
            'x-signature': signature,
        }
    });
}

Anfragebegrenzung

Wir begrenzen die Nutzung derzeit auf 40 Anfragen pro Minute pro Endpoint für jeden API-Schlüssel.

Verfügbarkeitsprüfungen

Ein nicht authentifizierter Endpoint ist unter dem Pfad /rest/v1/ping für automatisierte Verfügbarkeitsprüfungen verfügbar. Wenn die REST-API betriebsbereit und erreichbar ist, gibt dieser Endpoint eine HTTP 200-Antwort zurück.

Beispielanfrage:

curl -X GET https://chargepilot-api.tmhusa.energy/rest/v1/ping

Beispielantwort:

{ "result": "ChargePilot Rest API is available" }