API d’administration de l’espace de travail

L’API d’administration de l’espace de travail permet aux intégrations de serveur à serveur d’administrer un espace de travail EVCharge. Cette documentation s’adresse aux administrateurs d’espaces de travail et aux intégrateurs API externes. Elle utilise des jetons d’accès révocables liés à l’espace de travail et des portées précises ; les jetons de connexion client et les sessions de navigateur ne sont pas acceptés.

Ce répertoire est la référence canonique des développeurs pour l’API /v2/admin implémentée par app-api. Il ne documente ni les routes client/mobile ni les propres routes HTTP du portail d’administration.

• Requêtes et réponses des points de terminaison répertorie les 87 points de terminaison enregistrés, les portées, les paramètres, les corps de requête et les corps de réussite.
• Schémas et exemples définit les types de requête/réponse réutilisables et des corps JSON représentatifs.
• Contrat des réponses et des erreurs définit chaque corps d’échec commun ou propre à un point de terminaison.

URL de base et périmètre des ressources

Toutes les routes sont relatives à l’origine du service app-api déployé :

https://api.evcharge.mobi/v2/admin/...

L’ID de l’espace de travail n’est accepté ni dans l’URL, ni dans les paramètres, ni dans le corps de requête. Chaque jeton d’accès est lié à un seul espace de travail, et l’API déduit cpoId de l’identité du jeton authentifié. Si un site, une borne, un utilisateur, un tarif, un profil, une attribution ou une transaction imbriqué n’appartient pas à cet espace de travail, l’API renvoie la même réponse 404 RESOURCE_NOT_FOUND qui ne révèle pas l’existence des ressources.

Obtenir un jeton d’accès

Un administrateur de l’espace de travail crée les jetons dans les Paramètres de l’espace de travail, rubrique Accès à l’API. La gestion des jetons n’est volontairement pas accessible aux jetons d’espace de travail.

• L’accès à l’API est inclus dans toutes les offres, y compris Free. L’administrateur doit avoir l’autorisation de modifier l’espace de travail.
• L’hôte de l’espace de travail doit activer l’API d’administration via adminApiEnabled ; sinon, un jeton valide reçoit depuis app-api une réponse 404 qui ne révèle pas l’existence des ressources.
• L’administrateur ne peut accorder que les portées autorisées par ses propres autorisations actuelles et par les droits de l’espace de travail.
• Les nouveaux jetons peuvent être sans expiration (valeur par défaut des Paramètres de l’espace de travail) ou avoir une durée de vie de 1 à 365 jours entiers choisie par l’administrateur ; le serveur calcule les expirations absolues finies. Les jetons sans expiration restent valides jusqu’à leur révocation.
• Un espace de travail peut avoir au maximum 50 jetons actifs.
• L’identifiant en clair n’est affiché qu’une seule fois. Enregistrez-le immédiatement dans un gestionnaire de secrets.
• Le nom, les portées et l’expiration sont immuables. Pour effectuer une rotation, créez un remplacement, déployez-le, vérifiez-le et révoquez l’ancien jeton.
• La révocation est immédiate ; les lignes révoquées restent visibles dans un historique immuable et expurgé de l’espace de travail. Aucun point de terminaison d’introspection du jeton Bearer ou de suppression définitive n’existe.

app-api n’a aucun point de terminaison qui émette, renouvelle, liste ou révoque ces identifiants. L’obtention du jeton est donc un préalable effectué par une personne dans le portail d’administration, pas un autre point de terminaison de cette référence.

Ne placez jamais le jeton dans le gestionnaire de versions, les URL, les chaînes de requête, les cookies, les journaux, les outils d’analyse ou les rapports d’erreur.

Authentification

Envoyez exactement un en-tête de type RFC 6750 à chaque requête :

Authorization: Bearer evc_ws_<selector>.<secret>

L’identifiant opaque exact se compose de evc_ws_, suivi d’un sélecteur base64url canonique de 16 caractères, de ., puis d’un secret base64url canonique de 43 caractères. Envoyez l’identifiant complet tel quel ; ne le réencodez pas en base64.

L’API refuse les en-têtes d’autorisation dupliqués, les valeurs jointes par des virgules, les autres schémas, les valeurs Bearer vides, les JWT clients et les identifiants fournis ailleurs que dans cet en-tête.

Les jetons mal formés, inconnus, expirés, révoqués ou invalides pour toute autre raison reçoivent tous la même réponse :

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
Cache-Control: no-store
Content-Type: application/json

{
  "error": "Unauthorized",
  "code": "INVALID_WORKSPACE_TOKEN"
}

Le service vérifie l’état du jeton et les droits actuels de l’espace de travail à chaque requête. Retirer un droit peut donc désactiver les portées concernées avant l’expiration du jeton.

Les jetons d’espace de travail sont des identifiants opaques, pas des JWT. Ils n’ont pas de jeton de renouvellement et aucun point de terminaison de renouvellement n’existe. Un jeton à durée limitée cesse d’authentifier à son instant absolu expiresAt ; un jeton sans expiration reste valide jusqu’à sa révocation. La rotation consiste à créer un identifiant de remplacement dans le portail, à le déployer dans le client et à révoquer l’ancien.

Conventions des requêtes

• Utilisez Content-Type: application/json pour les requêtes avec un corps JSON.
• Les valeurs facultatives X-Request-Id sont débarrassées de leurs espaces de début et de fin et ne sont acceptées que si elles contiennent entre 1 et 128 caractères issus de A-Z, a-z, 0-9, ., _, : ou - ; sinon, le serveur génère un UUID. Chaque réponse renvoie la valeur choisie sous X-Request-Id.
• Le paramètre facultatif X-Error-Format: envelope convertit chaque réponse d’erreur JSON dans l’enveloppe structurée décrite dans Contrat des réponses et des erreurs. Toute autre valeur conserve le corps de compatibilité par défaut.
• Les ID des paramètres de chemin sont des entiers positifs. Les ID de jeton d’accès renvoyés par le portail sont des chaînes décimales, car leurs valeurs en base sont des entiers non signés sur 64 bits.
• Les dates-heures sont des chaînes RFC 3339 avec un décalage explicite, par exemple 2026-08-13T12:30:00Z.
• Les suppressions réussies renvoient normalement 204 No Content.
• Les créations renvoient normalement 201 Created.
• Une opération OCPP seulement mise en file d’attente peut renvoyer 202 Accepted ; ne l’interprétez pas comme une confirmation de la borne, sauf si la réponse l’indique explicitement.
• Les réponses authentifiées utilisent Cache-Control: no-store. Les points de terminaison QR et d’export de rapports renvoient des corps binaires avec des en-têtes de contenu explicites.
• Les origines de navigateur autorisées peuvent lire X-Request-Id, Idempotency-Replayed, Retry-After et Content-Disposition via CORS. Cela permet aux clients web de corréler les requêtes, de détecter les répétitions idempotentes, de respecter le délai avant une nouvelle tentative et de conserver les noms de fichiers de téléchargement choisis par le serveur.

Idempotence

Toutes les requêtes d’administration POST, PUT, PATCH et DELETE doivent inclure un en-tête Idempotency-Key. Les clés comportent entre 1 et 255 caractères visibles et sont liées au jeton, à la méthode et au chemin.

Idempotency-Key: provisioning-2026-08-13-site-42

Réutiliser une clé terminée avec une URL et un corps identiques répète la réponse enregistrée et ajoute :

Idempotency-Replayed: true

Réutiliser une clé avec une requête différente renvoie 409 IDEMPOTENCY_CONFLICT. Une requête toujours en cours renvoie 409 IDEMPOTENT_REQUEST_PROCESSING avec Retry-After: 5.

Les réponses terminées et les résultats définitifs sont conservés pour répétition ou rapprochement pendant sept jours après leur dernière mise à jour. Passé ce délai, la même clé peut être traitée comme une nouvelle commande. Les clients doivent donc utiliser des clés globalement uniques et ne pas les recycler volontairement.

Si le bail de traitement expire, si la connexion se ferme après le début de l’exécution ou si l’opération renvoie une erreur serveur, l’API ne peut pas établir de façon sûre si un effet externe s’est produit. Pendant la fenêtre de conservation de sept jours, la clé reste définitivement indéterminée et renvoie 409 IDEMPOTENCY_OUTCOME_UNKNOWN ; elle n’est ni reprise ni réexécutée automatiquement. Vérifiez les effets de l’opération avant toute récupération manuelle et ne soumettez pas la même opération avec une nouvelle clé tant que ce rapprochement n’est pas terminé.

Tous les points de terminaison d’administration modifiant des données, y compris POST /reports/send, nécessitent Idempotency-Key.

Limites de fréquence des requêtes

Les limites s’appliquent au jeton individuel et à son espace de travail. Les valeurs par défaut enregistrées dans le dépôt sont :

Une requête soumise à une limite renvoie 429 Too Many Requests et un en-tête Retry-After. Ces valeurs peuvent être remplacées selon le déploiement.

Erreurs

Les erreurs JSON utilisent un code stable lorsque l’appelant doit choisir une branche de traitement :

{
  "error": "Insufficient workspace-token scope",
  "code": "INSUFFICIENT_SCOPE"
}

Les erreurs de validation utilisent des tableaux de champs :

{
  "validationErrors": {
    "name": ["String must contain at least 1 character(s)"]
  }
}

Les statuts courants sont :

Catalogue des portées

Le catalogue de portées suivant est utilisé lorsqu’un administrateur crée un jeton. Une portée d’écriture ou à fort impact peut impliquer la portée de lecture correspondante, mais les portées de lecture n’accordent jamais l’écriture. Les portées disponibles dépendent des autorisations de l’administrateur et des fonctionnalités activées dans l’espace de travail.

L’accès à l’API lui-même est inclus dans toutes les offres et contrôlé par le paramètre adminApiEnabled de l’hôte. Les droits supplémentaires aux fonctionnalités mentionnés ci-dessus restent applicables ; l’accès à l’API n’accorde pas de fonctionnalités hors de l’offre de l’espace de travail.

Référence des points de terminaison

Les tableaux ci-dessous répertorient les 87 routes d’administration de l’espace de travail. Toutes les portées mentionnées dans une cellule sont obligatoires.

Espace de travail

Champs de modification partielle de l’espace de travail : name, email, website, addressLine1, addressLine2, postalCode, city, state et countryId. Au moins un champ est requis. Les chaînes vides autorisant null sont normalisées en null.

Sites et gestion de la puissance

Les corps de création et de modification partielle des sites utilisent :

{
  "name": "Main depot",
  "description": null,
  "addressLine1": "1 Example Street",
  "addressLine2": null,
  "postalCode": "LV-1001",
  "city": "Riga",
  "state": null,
  "countryId": 1,
  "timezoneId": 1,
  "latitude": 56.9496,
  "longitude": 24.1052
}

Le géocodage d’un site accepte les champs de requête facultatifs street, city, state, country et countryCode sur deux lettres, ainsi que l’en-tête Accept-Language. La recherche combinée rue/ville/région doit contenir au moins deux caractères. Les réponses contiennent uniquement placeId, displayName, latitude et longitude ; les identifiants du fournisseur et ses métadonnées spécifiques ne sont pas exposés. Le serveur applique la file partagée du fournisseur à une requête par seconde, un délai maximal de huit secondes, un cache borné de 24 heures et les limites globales des jetons d’espace de travail.

La gestion de la puissance accepte { "pools": [...] }. Un groupe contient id, name, limit, éventuellement meterSources et des children récursifs. Une borne enfant contient chargepointId et priority. L’API limite la taille de l’arbre et le nombre de compteurs et effectue un effacement OCPP puis une nouvelle validation en deux phases lors du remplacement de l’état installé. Une modification refusée, expirée ou affectée par une concurrence renvoie 409 POWER_MANAGEMENT_CONFLICT tout en conservant la configuration précédente.

Bornes

Les paramètres de requête des journaux de borne sont cursor, limit (50 par défaut, 200 au maximum), from, to, action, direction et levelId. Les paramètres des sessions sont page, limit (25 par défaut, 100 au maximum), from, to et customerId (un ID positif ou unknown). L’historique des programmations composites utilise cursor, limit (20 par défaut, 50 au maximum) et éventuellement connectorId.

Rapports

Les filtres des données de rapport et d’export sont from, to, siteId, chargerId, userId, anonymous et active. from/to couvrent par défaut les 90 derniers jours et ne peuvent pas dépasser 90 jours. userId ne peut pas être combiné avec anonymous=true.

• Pagination des données : cursor opaque, limit=50 par défaut, maximum 100.
• Mesures : transactionLogId obligatoire, cursor opaque, limit=500 par défaut, maximum 1 000.
• Export : format=csv|pdf, csv par défaut, limite stricte de 2 000 lignes.
• Les réponses d’export utilisent Content-Disposition: attachment, Cache-Control: private, no-store et X-Content-Type-Options: nosniff.

Corps de programmation :

{
  "enabled": true,
  "recipientEmail": "reports@example.com",
  "format": "csv",
  "sendDay": 5,
  "sendTime": "08:30"
}

sendDay est compris entre 1 et 28 et sendTime est interprété en UTC. Le planificateur rattrape une minute programmée manquée pendant le mois de livraison courant. Les constructions échouées avant remise sont réessayées après 5 et 10 minutes ; une réservation building interrompue peut être reprise après 30 minutes et la livraison automatique s’arrête après trois tentatives. Le planificateur enregistre indeterminate juste avant la remise à SMTP ; indeterminate et l’ancien statut sending sont tous deux définitifs, car réessayer automatiquement pourrait envoyer la pièce jointe en double. Les exploitants doivent rapprocher ces résultats manuellement avant de modifier l’état de la programmation. Chaque cycle sélectionne au maximum dix programmations, cesse de démarrer du travail après un budget de 45 secondes et utilise des délais SMTP bornés. La tâche est désactivée par défaut et doit être activée explicitement après validation de SMTP et de la capacité. La programmation API appartient à l’espace de travail au lieu d’emprunter l’identité de la personne ayant créé le jeton.

Tarifs

Le corps d’un tarif contient name, exactement un élément parmi currencyId, currencyCode ou currency, éventuellement biddingZoneId, et tax. Le corps d’une attribution est :

{ "tariffId": 17, "connectorId": 0 }

Lors de la création d’une attribution, le tarif s’applique à tous les connecteurs physiques si connectorId est omis ou explicitement défini à 0. Les mises à jour ciblent une attribution enregistrée et exigent donc un connectorId physique positif explicite ; 0 est refusé.

Un composant contient les champs obligatoires typeId, seasonId et price ; priority et les limites de validité par mois, jour de la semaine et heure sont facultatifs.

Profils de recharge

Les champs de métadonnées du profil sont label, locationId, stackLevel, purposeId, kindId, éventuellement recurrencyKindId, validFrom, validTo, startSchedule, rateUnitId et éventuellement minChargingRate. Une période de programmation contient startPeriod, limit et éventuellement numberOfPhases. Le corps d’attribution contient profileId et connectorId (0 par défaut).

La suppression de profils et le remplacement de la gestion de la puissance peuvent attendre la confirmation de la borne. Un refus, un délai dépassé ou un changement d’état concurrent renvoie un conflit et conserve la configuration en base au lieu de prétendre que la borne a été effacée.

Utilisateurs, invitations, RFID, accès et limites

La pagination des véhicules et celle des utilisateurs status=members utilisent un cursor numérique positif. Les pages d’invitation utilisent un curseur i2.* opaque, tandis que status=all utilise un curseur composite a2.* opaque après la première page ; un curseur numérique n’est valable que pour continuer l’ancien flux de membres. La recherche utilisateur est fournie dans l’en-tête X-Admin-User-Search afin de ne pas placer les e-mails dans les URL ou les journaux d’accès. limit vaut 50 par défaut et est limité à 100 ; la liste des utilisateurs prend en charge status=all|members|invitations. Traitez tous les curseurs renvoyés comme opaques et retournez-les sans modification.

La création directe d’un utilisateur ne crée ni mot de passe, ni identité de connexion, ni session. Elle rattache uniquement un client déjà enregistré. Utilisez le point de terminaison d’invitation pour un e-mail inconnu. L’utilisateur système Tagless protégé ne peut pas être modifié via ces routes.

Exemples

Définissez les valeurs dans votre shell sans afficher le jeton :

export ADMIN_API_BASE_URL="https://api.example.com"
export WORKSPACE_TOKEN="<read from secret manager>"

Listez les sites :

curl --fail-with-body \
  -H "Authorization: Bearer ${WORKSPACE_TOKEN}" \
  "${ADMIN_API_BASE_URL}/v2/admin/sites"

Créez un site en toute sécurité :

curl --fail-with-body \
  -X POST \
  -H "Authorization: Bearer ${WORKSPACE_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: site-main-depot-v1" \
  --data '{
    "name":"Main depot",
    "description":null,
    "addressLine1":"1 Example Street",
    "addressLine2":null,
    "postalCode":"LV-1001",
    "city":"Riga",
    "state":null,
    "countryId":1,
    "timezoneId":1,
    "latitude":56.9496,
    "longitude":24.1052
  }' \
  "${ADMIN_API_BASE_URL}/v2/admin/sites"

Téléchargez un rapport CSV pour une plage UTC explicite :

curl --fail-with-body \
  -H "Authorization: Bearer ${WORKSPACE_TOKEN}" \
  -o report.csv \
  "${ADMIN_API_BASE_URL}/v2/admin/reports/export?format=csv&from=2026-07-01T00%3A00%3A00Z&to=2026-08-01T00%3A00%3A00Z"

Exclusions volontaires

L’API des jetons d’espace de travail n’expose pas les opérations nécessitant une identité humaine ou des pouvoirs plus larges. Elles comprennent :

• la création, l’affichage, la rotation ou la révocation de jetons avec un autre jeton ;
• la connexion, la réinitialisation du mot de passe, les sessions, la délégation de rôles ou de privilèges humains et les changements de propriétaire de l’espace de travail ;
• la création/suppression d’espaces de travail et l’appartenance à un compte de facturation ;
• les paramètres de paiement, l’inscription Stripe, les offres, les factures et la facturation de l’hôte ;
• les opérations d’assistance à l’échelle de l’hôte et les webhooks des fournisseurs ;
• les notifications aux personnes, les redirections de navigation, les ressources de marque et les routes de développement/test.