Premiers pas

Obtenir une clé et un secret d'API

Veuillez nous contacter pour qu'une clé et un secret d'API soient générés selon vos besoins.

Une fois que vous disposez de votre clé et de votre secret d'API, vous devrez utiliser les deux pour vous authentifier auprès de l'API. Nous utilisons la vérification de signature HMAC pour valider les requêtes.

Effectuer des requêtes signées

La clé d'API doit être envoyée via le header x-api-key.

Le secret d'API est utilisé pour générer une signature HMAC, incluant un horodatage, et la signature doit être envoyée via le header x-signature.

Toutes les requêtes doivent également inclure le header x-req-timestamp.

Processus de génération de la signature

La génération de la signature suit ces étapes :

1. Hacher le secret avec SHA256 :

   hashed_secret = SHA256(your_secret)

2. Construire le payload à signer au format suivant :

   payload = METHOD:URL_PATH:TIMESTAMP:BODY

   • METHOD : méthode HTTP (GET, POST, etc.)
   • URL_PATH : chemin de la requête incluant les paramètres de requête (ex. /rest/v1/sites?from=2024-01-01)
   • TIMESTAMP : horodatage Unix en secondes
   • BODY : corps de la requête en JSON (chaîne vide si aucun corps)

3. Générer la signature HMAC-SHA256 en utilisant le secret haché :

   signature = HMAC-SHA256(payload, hashed_secret)

4. Envoyer dans les headers de la requête sous forme de chaîne hexadécimale

Exemple d'implémentation

Avertissement

Notez que nous envoyons la clé, l'horodatage et la signature. Le secret ne doit jamais être transmis sur le réseau.

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,
        }
    });
}

Limitation de requêtes

Nous limitons actuellement l'utilisation à 40 requêtes par minute par endpoint pour chaque clé API.

Vérifications de disponibilité

Un endpoint non authentifié est disponible à l'adresse /rest/v1/ping pour les vérifications automatisées de disponibilité. Lorsque l'API REST est opérationnelle, cet endpoint retourne une réponse HTTP 200.

Exemple de requête :

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

Exemple de réponse :

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