API et webhooks
Votre outil (ticketing, supervision, outil d’automatisation) crée une demande d’intervention avec votre propre n° de ticket, lit votre registre de sites et de bornes, et reçoit chaque étape de la mission. Connecteurs natifs pour Zendesk, Jira Service Management, ServiceNow, Freshdesk, Salesforce, Sitetracker, HubSpot et Dynamics 365 ; pour tout autre outil, API et webhook génériques. Aucun montant n’est jamais transmis.
Description machine (OpenAPI 3.1, à importer dans Postman, Insomnia ou un générateur de client) : /api/v1/openapi.json.
Authentification et limites
En-tête « Authorization: Bearer ct_live_… » ou « X-API-Key ». La clé se crée dans votre espace client, onglet Intégrations (réservé à un administrateur de votre société) ; elle n’est montrée qu’une fois.
- Créer une demande : 60 appels par minute et par clé.
- Lire le registre : 30 appels par minute et par clé.
- Au-delà, ou après trop d’essais de clé invalide depuis une même adresse : réponse 429, réessayez une minute plus tard.
Créer une demande
POST https://espace.chargeteam.pro/api/v1/demandes
Envoyez votre propre numéro de ticket dans « reference_client ». Un appel rejoué rend la même demande, jamais une deuxième.
| Champ | Type | Description |
|---|---|---|
| reference_client | string, ≤ 120 | |
| site_nom | string, ≤ 200 | |
| adresse | string, ≤ 300 | |
| ville | string, ≤ 120 | |
| code_postal | string, ≤ 20 | |
| latitude | number | |
| longitude | number | |
| description | string, ≤ 2000 | |
| type | string (panne, maintenance, autre, ne_charge_pas, connecteur, ecran, paiement, cable, communication, mise_en_service, maintenance_preventive, maintenance_curative, installation_materiel, nettoyage, reprise_supervision, electricite_generale) | |
| contact_nom | string, ≤ 160 | |
| contact_email | string, email, ≤ 200 | |
| contact_tel | string, ≤ 40 | |
| contact_terrain_nom | string, ≤ 160 | |
| contact_terrain_tel | string, ≤ 40 | |
| acces | string, ≤ 500 | |
| site_en_libre_acces | boolean | |
| marque | string, ≤ 120 | |
| modele | string, ≤ 120 | |
| numero_serie | string, ≤ 120 | |
| borne_id | string, ≤ 120 | |
| courant | string (ac, dc) | |
| site_id | string, uuid | |
| equipement_id | string, uuid |
* obligatoire.
Ce qui bloque la demande (réponse 422)
- Adresse complète (rue + ville ou code postal), ou coordonnées GPS : Sans lieu situable, aucun technicien ne peut être rapproché du site : la mission ne peut pas être affectée.
- Description de la panne constatée : Sans symptôme, impossible de savoir si la visite dure vingt minutes ou une demi-journée, ni quelles pièces emporter.
- Email ou téléphone du demandeur : Sans moyen de vous joindre, nous ne pouvons ni confirmer le rendez-vous ni vous rendre compte.
Ce qui manquera au technicien si vous ne l’envoyez pas
- Nom et téléphone d’une personne joignable sur place : Le technicien qui trouve une barrière fermée ou un local verrouillé n’a personne à appeler, et le déplacement est perdu.
- Conditions d’accès (badge, clé, code, horaires d’ouverture) : Une borne en parking fermé ou en site industriel n’est atteignable qu’aux heures et avec les moyens qu’on nous indique.
- Marque de la borne : La marque choisit le guide d’intervention et la documentation constructeur remise au technicien.
- Modèle, numéro de série ou référence de la borne : Sans identifiant, le technicien devant plusieurs bornes ne sait pas laquelle est en panne.
- Courant alternatif (AC) ou continu (DC) : Une borne DC demande une habilitation et un outillage differents : sans cette information, le rapprochement peut envoyer quelqu’un qui n’a pas le droit d’intervenir.
Un 201 accepte la demande et liste quand même ce qui manquera sur place. Un 422 refuse et dit tout ce qui manque d’un coup.
Exemple (curl)
curl -X POST https://espace.chargeteam.pro/api/v1/demandes \
-H "Authorization: Bearer ct_live_…" -H "Content-Type: application/json" \
-d '{"reference_client":"ZD-48213","numero_serie":"SN123456","description":"Borne en défaut, écran noir","contact_email":"[email protected]"}'- creer
- Votre outil (ticketing, supervision, outil d’automatisation ; connecteurs natifs : voir « connecteurs ») appelle POST /api/v1/demandes avec votre n° de ticket dans « reference_client ». Ce numéro revient dans CHAQUE événement (webhook et objet du courriel).
- exemple
- curl -X POST https://espace.chargeteam.pro/api/v1/demandes \ -H "Authorization: Bearer ct_live_…" -H "Content-Type: application/json" \ -d '{"reference_client":"ZD-48213","numero_serie":"SN123456","description":"Borne en défaut, écran noir","contact_email":"[email protected]"}'
- regle
- Une demande est relue par notre équipe avant toute affectation : rien ne part vers un technicien sans validation humaine.
Lire votre registre de sites et de bornes
- lecture
- GET https://espace.chargeteam.pro/api/v1/sites (même clé). Rend vos sites et leurs bornes ; « ?q= » filtre par nom, ville, code postal, n° de série ou identifiant de supervision.
- reference
- Dans une demande, « site_id » ou « equipement_id » (identifiants rendus par /api/v1/sites) désignent un site ou une borne de votre registre ; « numero_serie » seul retrouve aussi la borne. Les champs absents de l’appel (adresse, GPS, accès, contact sur place, marque, modèle, n° de série, identifiant de supervision, courant) sont complétés depuis le registre ; ce que vous envoyez prime toujours.
- erreur
- Un « site_id » ou « equipement_id » inconnu de votre registre est refusé (422, « reference_inconnue »). Un n° de série inconnu est simplement transmis tel quel.
- saisie
- Le registre se tient dans l’espace client (Mes sites) : saisie, ou import CSV/Excel.
Webhooks signés
Chaque changement d’état d’une mission ou d’un ticket part vers vos URL (webhook signé) et/ou votre adresse e-mail de ticketing. Réglages : espace client, Intégrations.
| Événement | Quand |
|---|---|
| demande.recue | Demande reçue |
| mission.planifiee | Intervention planifiée |
| technicien.affecte | Technicien affecté |
| technicien.arrive | Technicien arrivé |
| mission.terminee | Intervention terminée |
| pv.signe | PV signé |
| rapport.valide | Rapport validé |
| demande.refusee | Demande refusée |
| mission.annulee | Intervention annulée |
| ticket.created | Ticket ouvert |
| ticket.status_changed | Statut du ticket changé |
| ticket.message | Message sur le ticket |
- methode
- POST, corps JSON, réponse 2xx attendue sous 10 s.
- entetes
- ChargeTeam-Signature
- t=<horodatage secondes>,v1=<HMAC-SHA256 hex de "<t>.<corps brut>" avec votre secret whsec_…> ; pendant une rotation, une seconde v1 (ancien secret) suit la première
- ChargeTeam-Event
- type de l’événement, ex. technicien.arrive
- ChargeTeam-Delivery
- identifiant unique de l’événement : servez-vous-en pour ignorer un doublon
- reprises
- Sans réponse 2xx : nouvel essai après 1, 2, 4, 8… minutes (8 essais, environ 4 h), puis abandon visible au journal, renvoyable à la main.
- pause_automatique
- Une destination qui n’a réussi aucune livraison depuis 72 heures, avec au moins 3 envois abandonnés depuis sa dernière réussite, est mise en pause ; un seul avis de service part à un administrateur de votre société. Rien n’est perdu : réactivez, puis « Rejouer ».
- relecture
- Espace client, Intégrations, « Rejouer » : les envois des 30 derniers jours depuis la date choisie repartent avec le même ChargeTeam-Delivery. Par l’API : GET /api/v1/evenements?apres=<suivant> (30 jours, même charge utile, avec ou sans webhook).
- verification
- Refusez un horodatage de plus de 5 minutes et comparez la signature à temps constant.
- rotation
- Espace client, Intégrations, « Faire tourner le secret » : le nouveau secret est montré une fois ; l’ancien signe encore 24 heures (deux v1 dans l’en-tête, acceptez celle qui correspond), puis plus du tout. Les secrets sont chiffrés au repos.
Même événement en courriel court. Objet : « [VOTRE-REFERENCE] ChargeTeam : Technicien arrivé », pour que votre outil rattache le message au bon ticket.
Charge utile
- id
- identifiant unique de l’événement
- type
- technicien.arrive
- survenu_at
- ISO 8601
- reference_client
- votre n° de ticket, tel qu’envoyé dans « reference_client »
- chargeteam
- reference
- INT-2026-123
- suivi_url
- lien de suivi public
- mission
- type
- depannage
- statut
- en_cours
- date_planifiee
- AAAA-MM-JJ
- heure_debut
- HH:MM
- technicien
- référence opaque « tch_… », stable pour un même intervenant chez vous ; jamais un nom ni une coordonnée
- arrivee_at
- ISO 8601
- reussi
- booléen une fois terminée
- site
- id
- identifiant du registre (/api/v1/sites)
- nom
- …
- ville
- …
- code_postal
- …
- borne
- id
- identifiant du registre
- numero_serie
- …
- identifiant
- ChargeBox ID
- marque
- …
- modele
- …
- rapport
- version
- 1
- pdf_url
- lien signé vers le PDF
- expire_at
- ISO 8601, 30 jours
- pv
- mode
- sur_place | telephone | plateforme (événement pv.signe)
- signe_at
- ISO 8601
- reserve
- booléen : validé avec réserve
- refus
- motif
- motif public, celui de la page de suivi (événement demande.refusee) ; jamais une note interne
- absent
- Aucun montant, jamais. Aucun nom, téléphone ni position de technicien. Jamais le nom du signataire du PV.
Vérifier la signature
Calculez le HMAC-SHA256 de « horodatage.corps brut » avec votre secret, refusez un horodatage de plus de 5 minutes et comparez à temps constant.
Node.js
import { createHmac, timingSafeEqual } from 'node:crypto'
// corps = le corps BRUT de la requête (chaîne), avant tout JSON.parse.
// Pendant une rotation du secret, l'en-tête porte deux signatures v1 : une seule doit correspondre.
function verifier(secret, corps, entete) {
const [t, ...v1] = String(entete || '').split(',')
const ts = /^t=(\d+)$/.exec(t || '')?.[1]
if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false
const attendu = createHmac('sha256', secret).update(ts + '.' + corps).digest()
return v1.some((p) => /^v1=[a-f0-9]{64}$/.test(p) && timingSafeEqual(attendu, Buffer.from(p.slice(3), 'hex')))
}
// verifier(process.env.CHARGETEAM_SECRET, corps, req.headers['chargeteam-signature'])Python
import hmac, hashlib, re, time
def verifier(secret: str, corps: bytes, entete: str) -> bool:
t, *v1 = (entete or "").split(",")
m = re.fullmatch(r"t=(\d+)", t)
if not m or abs(time.time() - int(m.group(1))) > 300:
return False
attendu = hmac.new(secret.encode(), m.group(1).encode() + b"." + corps, hashlib.sha256).hexdigest()
return any(re.fullmatch(r"v1=[a-f0-9]{64}", p) and hmac.compare_digest(attendu, p[3:]) for p in v1)Rapports signés
À l’événement rapport.valide, la charge utile porte un lien signé vers le PDF du rapport (valable 30 jours, sans compte) : votre outil peut le télécharger et le joindre au ticket.
Erreurs
- 400 : corps illisible (JSON invalide).
- 401 : clé absente, inconnue, échue ou révoquée.
- 403 : la clé n’a pas la portée de la route (« portee_insuffisante »).
- 422 : demande refusée ; la réponse liste d’un coup tout ce qui manque.
- 429 : trop d’appels, réessayez une minute plus tard ; ou quota journalier de la clé atteint (« quota_journalier »).
- 5xx : incident de notre côté ; rejouez l’appel avec le même « reference_client », il ne créera pas de doublon.
Tickets
- principe
- Un ticket = un problème sur un site ou une borne. Chaque demande envoyée par POST /api/v1/demandes ouvre aussi un ticket ; une borne qui a déjà un ticket OUVERT voit le nouveau signalement ajouté à ce ticket (réponse 200, « complete: true »), jamais une seconde demande.
- lister
- GET https://espace.chargeteam.pro/api/v1/tickets ?statut=ouverts|clos|nouveau|… &priorite= &site=<site_id> &borne=<equipement_id> &depuis=AAAA-MM-JJ &jusqu=AAAA-MM-JJ &q= &limite=30 &decalage=0
- ouvrir
- POST https://espace.chargeteam.pro/api/v1/tickets : même clé ; « reference_client » rend l’appel rejouable (même ticket, 200) ; « description » obligatoire (10 caractères au moins).
- champs
- $schema
- https://json-schema.org/draft/2020-12/schema
- type
- object
- properties
- reference_client
- type
- string
- maxLength
- 120
- site_id
- type
- string
- format
- uuid
- pattern
- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
- equipement_id
- type
- string
- format
- uuid
- pattern
- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
- numero_serie
- type
- string
- maxLength
- 120
- borne_id
- type
- string
- maxLength
- 120
- site_nom
- type
- string
- maxLength
- 200
- adresse
- type
- string
- maxLength
- 300
- code_postal
- type
- string
- maxLength
- 20
- ville
- type
- string
- maxLength
- 120
- cles_requises
- maxItems
- 30
- type
- array
- items
- type
- string
- minLength
- 1
- maxLength
- 80
- boite_cles
- type
- boolean
- code_boite
- type
- string
- maxLength
- 60
- contact_nom
- type
- string
- maxLength
- 200
- contact_tel
- type
- string
- maxLength
- 40
- symptome
- type
- string
- enum
- hors_ligne
- ne_charge_pas
- connecteur_cable
- paiement_badge
- ecran
- isolement
- electrique
- degradation
- defaut
- autre
- titre
- type
- string
- maxLength
- 160
- description
- type
- string
- minLength
- 10
- maxLength
- 5000
- priorite
- default
- normale
- type
- string
- enum
- basse
- normale
- haute
- urgente
- required
- description
- additionalProperties
- false
- lire
- GET https://espace.chargeteam.pro/api/v1/tickets/{id} : {id} = identifiant, n° « T-000123 » ou votre « reference_client ». Rend l’état, le fil public, les interventions liées et un lien signé (30 jours) vers chaque rapport PDF validé.
- repondre
- POST https://espace.chargeteam.pro/api/v1/tickets/{id}/messages {"message": "…"} : ajouté au fil, visible de l’équipe ; il ne vous est pas renvoyé par webhook.
- statuts
- nouveau
- Nouveau
- pris_en_charge
- Pris en charge
- planifie
- Planifié
- en_intervention
- En intervention
- attente_client
- En attente de votre réponse
- resolu
- Résolu
- ferme
- Fermé
- symptomes
- hors_ligne
- Hors ligne ou communication
- ne_charge_pas
- Ne charge pas ou sessions en échec
- connecteur_cable
- Connecteur, câble ou point de charge
- paiement_badge
- Paiement, badge ou lecteur
- ecran
- Écran
- isolement
- Défaut d’isolement
- electrique
- Électrique ou puissance (disjoncteur, module)
- degradation
- Dégradation, choc ou porte
- defaut
- En défaut, sans précision
- autre
- Autre
- evenements
- ticket.created, ticket.status_changed (avant, après), ticket.message (messages publics de l’équipe ou de vos membres) : voir « sortie.charge_utile_ticket ». Les événements mission.* continuent de décrire chaque intervention.
- absent
- Aucun montant, aucune note interne de l’équipe.
Exigences du rapport
- principe
- Votre liste de photos et de contrôles : nos techniciens la remplissent à chaque intervention pour vous, en plus de notre rapport technique (jamais à la place de ses contrôles de sécurité). Un élément obligatoire manquant empêche l’envoi du rapport. La liste est versionnée : une intervention déjà confiée à un technicien garde la version en vigueur à ce moment.
- lire
- GET https://espace.chargeteam.pro/api/v1/exigences-rapport : la version en vigueur (« version », « elements », « mise_a_jour »).
- remplacer
- PUT https://espace.chargeteam.pro/api/v1/exigences-rapport {"elements": [...]} : remplace la liste entière ; nouvelle version seulement si elle change ; 20 appels par minute. 422 « liste_invalide » dit ce qui ne va pas.
- element
- $schema
- https://json-schema.org/draft/2020-12/schema
- type
- object
- properties
- id
- type
- string
- pattern
- ^[a-z0-9-]{4,40}$
- type
- type
- string
- enum
- photo
- case
- oui_non
- mesure
- texte
- libelle
- type
- string
- minLength
- 2
- maxLength
- 120
- consigne
- type
- string
- maxLength
- 200
- obligatoire
- type
- boolean
- unite
- type
- string
- maxLength
- 16
- min
- type
- number
- max
- type
- number
- portee
- type
- string
- enum
- toutes
- maintenance
- installation
- required
- id
- type
- libelle
- obligatoire
- additionalProperties
- false
- types
- photo
- photo demandée (emplacement à remplir)
- case
- case à cocher
- oui_non
- oui ou non
- mesure
- valeur mesurée, « unite », « min » et « max » facultatifs (hors plage : signalé, jamais bloquant)
- texte
- texte court
- portee
- Facultative : « toutes » (par défaut), « maintenance » (maintenance et dépannage) ou « installation » (installation et mise en service).
- Chaque élément et son résultat figurent au rapport PDF, section « Vos exigences » ; les photos demandées y sont jointes avec leur libellé.
- exemple
- elements
- id
- plaque
- type
- photo
- libelle
- Plaque signalétique
- consigne
- Numéro de série lisible
- obligatoire
- true
- id
- isolement
- type
- mesure
- libelle
- Résistance d’isolement
- unite
- MΩ
- min
- 1
- obligatoire
- true
Pieces
- principe
- Une pièce détachée signalée par le technicien sur une de vos interventions : signalée, validée ou refusée, commandée, expédiée, reçue, posée ; retour constructeur (RMA). Chaque pièce a un responsable : « chargeteam » ou « donneur_ordre » (vous commandez et expédiez).
- lister
- GET https://espace.chargeteam.pro/api/v1/pieces ?statut=signalee|validee|refusee|commandee|expediee|recue|posee|annulee
- lire
- GET https://espace.chargeteam.pro/api/v1/pieces/{id}
- agir
- PATCH https://espace.chargeteam.pro/api/v1/pieces/{id} {"action": "valider"} ; « refuser » (+ « motif ») ; si vous fournissez la pièce : « commander », « expedier » (+ « transporteur », « numero_suivi », « lieu_livraison » : site|depot|technicien), « recevoir », « rma » (+ « rma_statut », « rma_numero », « rma_envoye_le ») ; « fournisseur » (+ chargeteam|donneur_ordre) tant qu’elle n’est pas commandée. « actions_possibles » dit ce qui vous est permis.
- evenements
- Sur une intervention liée à un ticket, chaque étape s’inscrit au fil public du ticket : vous la recevez en ticket.message.
- absent
- Aucun prix, aucune photo.
Tarifs
- principe
- Missions directes ChargeTeam, prix HT, identiques à l’espace client : 1 h incluse, puis par demi-heure entamée, plus le déplacement compté depuis le technicien habilité le plus proche au moment de la demande. Le prix ferme est confirmé avant toute intervention.
- entreprise
- taux_horaire_ht
- 70
- demi_heure_ht
- 35
- deplacement
- base_ht
- 50
- jusqu_a_km
- 20
- tranche_km
- 10
- par_tranche_ht
- 6
- sur_devis_au_dela_km
- 150
- distance
- technicien habilité le plus proche, mesurée à la demande
- phrase
- 120 € HT (1 h incluse + déplacement), puis 35 € HT par demi-heure entamée. Déplacement : 50 € HT jusqu’à 20 km, puis 6 € HT par tranche de 10 km entamée ; au-delà de 150 km, sur devis.
- operateur_de_recharge
- taux_horaire_ht
- 80
- demi_heure_ht
- 40
- deplacement
- base_ht
- 60
- jusqu_a_km
- 20
- tranche_km
- 10
- par_tranche_ht
- 6
- sur_devis_au_dela_km
- 150
- distance
- technicien habilité le plus proche, mesurée à la demande
- phrase
- 140 € HT (1 h incluse + déplacement), puis 40 € HT par demi-heure entamée. Déplacement : 60 € HT jusqu’à 20 km, puis 6 € HT par tranche de 10 km entamée ; au-delà de 150 km, sur devis.
- votre_grille
- GET https://espace.chargeteam.pro/api/v1/tarifs (même clé) : la grille de votre société.
- offres
- offre
- Intervention à l’unité
- principe
- La grille publique : taux horaire, 1 h incluse puis par demi-heure entamée, déplacement par paliers. Prix confirmé avant l’intervention.
- offre
- Visite préventive
- principe
- Par borne, au tarif d’intervention, avec rapport et PV signé. Aucun dépannage inclus ; délai confirmé à la prise en charge.
- offre
- Parc sur mesure
- principe
- Sur devis, après un état des lieux de votre parc facturé au tarif d’intervention : le devis est établi en connaissant l’état de vos bornes.
- garantie
- Garantie premier passage, 15 jours. Si la même panne revient sur la même borne dans les 15 jours qui suivent une intervention déclarée réussie, nous revenons sans frais : ni main-d’œuvre, ni déplacement. Ne sont pas couverts : une pièce à remplacer ou une borne défaillante, le vandalisme, et les causes extérieures à la borne (réseau électrique, supervision ou connexion, usage). L’équipe vérifie la cause lors du second passage et vous la dit.
Connecteurs
- principe
- Pour Zendesk, Jira Service Management, ServiceNow, Freshdesk, Salesforce Service Cloud, Sitetracker, HubSpot Service Hub et Microsoft Dynamics 365 : l’administrateur de votre société relie l’outil dans l’espace client, onglet Intégrations. Un ticket créé chez vous (selon votre filtre, à partir de l’activation) devient un ticket ChargeTeam dont la « reference_client » est votre numéro ; reviennent dans CE ticket : statuts, messages publics de l’équipe, date et heure planifiées, PV signé (mode et heure, sans le nom du signataire), rapport validé (lien PDF signé ; PDF joint pour Salesforce et Sitetracker) et annulation.
- outils
- Zendesk
- Entrée : webhook signé (déclencheur « ticket créé »), puis GET /api/v2/tickets/{id}.json. Sortie : PUT /api/v2/tickets/{id}.json (commentaire, statut).
- Jira Service Management
- Entrée : GET /rest/api/3/search/jql (votre filtre JQL). Sortie : POST /rest/api/3/issue/{id}/comment (interne par défaut) et transition du workflow.
- ServiceNow
- Entrée : GET /api/now/table/{table} (votre requête encodée). Sortie : PATCH /api/now/table/{table}/{sys_id} (work_notes par défaut, state).
- Freshdesk
- Entrée : GET /api/v2/tickets (votre étiquette). Sortie : POST /api/v2/tickets/{id}/notes (privée par défaut), PUT /api/v2/tickets/{id} (status).
- Salesforce Service Cloud
- Entrée : SOQL sur Case (votre clause WHERE). Sortie : CaseComment, Status du Case, PDF du rapport en ContentVersion.
- Sitetracker
- Entrée : SOQL sur l’objet choisi (Job par défaut). Sortie : publication dans le fil Chatter (FeedItem), champ statut choisi, PDF du rapport en ContentVersion.
- HubSpot Service Hub
- Entrée : POST /crm/v3/objects/tickets/search (propriété=valeur). Sortie : note associée au ticket, étape du pipeline.
- Microsoft Dynamics 365
- Entrée : GET /api/data/v9.2/{entité} (votre $filter). Sortie : note (annotation), statuscode ou CloseIncident.
- zendesk_webhook
- url
- POST https://espace.chargeteam.pro/api/v1/connecteurs/{id}/webhook (URL exacte affichée dans l’onglet Intégrations)
- corps
- {"ticket_id": "{{ticket.id}}"} : seul l’identifiant compte, le ticket est relu par l’API Zendesk.
- signature
- En-têtes X-Zendesk-Webhook-Signature et X-Zendesk-Webhook-Signature-Timestamp (HMAC-SHA256 base64 de horodatage + corps, clé de signature du webhook Zendesk) ; horodatage à 5 minutes près, sinon 401.
- reponses
- 200 ticket importé ou déjà connu (rejouer ne crée rien) ; 202 connecteur en pause ; 401 signature absente, invalide ou périmée ; 503 outil injoignable : Zendesk réessaie.
- regles
- Idempotence : un ticket de votre outil donne un seul ticket ChargeTeam, quel que soit le nombre de passages ou de rejeux.
- Commentaires en note interne par défaut : jamais une réponse envoyée à votre propre demandeur, sauf réglage contraire.
- Aucun montant, aucune note interne de l’équipe ChargeTeam.
- Identifiants chiffrés au repos, jamais réaffichés ; requêtes uniquement vers l’instance cloud de l’éditeur (HTTPS, adresse publique vérifiée, aucune redirection suivie).
- Interrogation toutes les 5 minutes environ ; un échec est repris automatiquement et reste visible au journal de l’onglet Intégrations.
- Chaque connecteur se valide avec votre instance à la mise en service, sur un ticket de test.
Clés, portées et journal d’appels
- portees
- demandes:lire
- GET /tickets, /tickets/{id}, /sites, /pieces, /pieces/{id}, /tarifs, /exigences-rapport, exports demandes et tickets
- demandes:ecrire
- POST /demandes, /tickets, /tickets/{id}/messages, /supervision/etats ; PATCH /pieces/{id} ; PUT /exigences-rapport
- rapports:lire
- GET /rapports, export rapports, et le lien PDF dans les missions
- missions:lire
- GET /missions, /missions/{id}, export missions
- webhooks
- GET /evenements (relecture des événements)
- defaut
- Une clé créée avant le 03/10/2026 a toutes les portées. Une nouvelle clé reçoit celles que vous cochez (toutes par défaut).
- refus
- 403 {"erreur": "portee_insuffisante", "portee_requise": "…"} si la clé n’a pas la portée de la route ; 401 clé absente, inconnue, révoquée ou échue.
- quota
- Quota journalier facultatif par clé : au-delà, 429 {"erreur": "quota_journalier"}. S’ajoute aux limites par minute.
- rotation
- « Faire tourner » une clé (espace client, Intégrations) : nouvelle clé aux mêmes portées, montrée une fois ; l’ancienne reste valable 24 heures.
- journal
- Chaque appel d’une clé reconnue est inscrit (méthode, chemin sans la chaîne de requête, code, durée) et visible 90 jours dans Intégrations. Le contenu des requêtes n’est jamais conservé.
Lire vos interventions, rapports et événements
- missions
- GET /api/v1/missions : vos interventions, les plus récentes d’abord. Filtres depuis, jusqu (jour de création AAAA-MM-JJ, heure de Paris), site (identifiant du registre), statut (nouvelle, planifiee, en_cours, terminee, annulee, facturee) ; limite 1 à 200 (50 par défaut) ; curseur = « suivant » de la page précédente (pagination stable : une mission créée entre deux pages ne décale rien).
- mission
- GET /api/v1/missions/{id ou référence} : une intervention. 404 identique pour une mission inconnue ou d’une autre société.
- champs
- reference, reference_client, ticket, statut, type, priorite, cree_at, date_planifiee, heure_debut, arrivee_at, terminee, reussi, technicien (référence opaque tch_…), site, borne, pv (mode, signe_at, reserve), rapport (version, valide_at, pdf_url et expire_at avec la portée rapports:lire).
- rapports
- GET /api/v1/rapports : rapports validés, mêmes filtres et même pagination ; lien PDF signé valable 30 jours.
- evenements
- GET /api/v1/evenements?apres=<suivant>&limite=1..500 : vos événements des 30 derniers jours, même charge utile que les webhooks, avec ou sans webhook configuré.
- absent
- Aucun montant, aucun nom, téléphone ni position de technicien, aucune note interne, jamais le nom du signataire d’un PV.
Exports CSV et JSON
- routes
- Espace client, Intégrations, Exports (administrateur de la société) ; ou GET /api/v1/exports/{demandes|missions|tickets|rapports}?format=csv|json&depuis=&jusqu= (portée selon le type).
- format
- CSV : UTF-8 avec BOM, point-virgule, fins de ligne CRLF (s’ouvre tel quel dans un tableur), dates en heure de Paris « AAAA-MM-JJ HH:MM », oui/non. JSON : {"type", "colonnes", "lignes", "tronque"}. 10000 lignes au plus, les plus récentes.
- colonnes
- demandes
- reference_client
- votre référence (reference_client)
- etat
- recue | convertie | rejetee
- motif_refus
- motif public d’un refus
- recue_le
- date de réception
- mission_reference
- intervention créée
- site_id
- site du registre
- borne_id
- borne du registre
- suivi_url
- lien de suivi public
- missions
- reference
- référence ChargeTeam
- reference_client
- votre référence
- ticket
- T-000123
- statut
- nouvelle | planifiee | en_cours | terminee | annulee | facturee
- type
- type d’intervention
- priorite
- priorité
- creee_le
- date de création
- date_planifiee
- AAAA-MM-JJ
- heure_debut
- HH:MM
- arrivee_le
- arrivée du technicien
- terminee
- oui | non
- reussie
- oui | non | vide
- technicien
- référence opaque tch_… (jamais un nom)
- site_id
- site
- site_nom
- nom du site
- ville
- ville
- code_postal
- code postal
- borne_id
- borne
- numero_serie
- n° de série
- identifiant_borne
- ChargeBox ID
- marque
- marque
- modele
- modèle
- pv_mode
- sur_place | telephone | plateforme
- pv_signe_le
- signature du PV
- pv_reserve
- oui | non
- rapport_version
- version du rapport validé
- rapport_valide_le
- validation du rapport
- tickets
- numero
- T-000123
- reference_client
- votre référence
- statut
- nouveau | pris_en_charge | planifie | en_intervention | attente_client | resolu | ferme
- priorite
- basse | normale | haute | urgente
- symptome
- symptôme
- titre
- titre
- site_id
- site
- site_nom
- nom du site
- ville
- ville
- borne_id
- borne
- numero_serie
- n° de série
- identifiant_borne
- ChargeBox ID
- missions
- nombre d’interventions liées
- ouvert_le
- ouverture
- mis_a_jour_le
- dernière mise à jour
- resolu_le
- résolution
- ferme_le
- fermeture
- rapports
- mission_reference
- référence ChargeTeam
- reference_client
- votre référence
- site_nom
- nom du site
- ville
- ville
- numero_serie
- n° de série
- rapport_version
- version
- rapport_valide_le
- validation
- pv_mode
- sur_place | telephone | plateforme
- pv_signe_le
- signature du PV
- pv_reserve
- oui | non
- pdf_url
- lien PDF signé, valable 30 jours à partir de l’export
- pdf_expire_le
- fin de validité du lien
- stabilite
- Les noms de colonnes sont stables : on en ajoute à la fin, on n’en renomme ni n’en retire.
Supervision
- principe
- Votre supervision nous transmet l’état de chaque point de charge : ChargeTeam en tire la disponibilité de votre parc (24 h, 30 jours, indisponibilités longues et leur ticket). Une borne est rattachée par son « identifiant de supervision » (registre, Mes sites). Rien n’est estimé : sans état reçu, la borne est « non supervisée ».
- endpoint
- POST https://espace.chargeteam.pro/api/v1/supervision/etats
- authentification
- Au choix : la clé d’API (« Authorization: Bearer ct_live_… »), ou un webhook signé : créez une source « Webhook signé » (Intégrations > Supervision), appelez l’URL rendue (…/etats?source=<id>) avec l’en-tête ChargeTeam-Signature « t=<horodatage>,v1=<HMAC-SHA256 hex de "<t>.<corps brut>" avec le secret whsec_ de la source> » (5 minutes de tolérance, comme nos webhooks sortants).
- corps
- {"etats": [{"identifiant": "CB-0001", "point": "1", "etat": "Faulted", "horodatage": "2026-09-26T08:00:00Z", "code_erreur": "GroundFailure"}]} ; 500 états au plus par appel ; un objet seul est accepté.
- champs
- identifiant
- obligatoire : l’identifiant de supervision de la borne (ChargeBox ID OCPP, EVSE ID…), tel qu’au registre.
- point
- facultatif : le point de charge (connecteur ou EVSE, ex. « 1 ») ; absent = la borne entière.
- etat
- obligatoire : statut OCPP 1.6 ou 2.0.1 (Available, Preparing, Charging, SuspendedEV, SuspendedEVSE, Finishing, Reserved, Occupied, Unavailable, Faulted) ou « Offline » ; ou nos valeurs : disponible, occupe, indisponible, defaut, hors_ligne.
- horodatage
- facultatif (ISO 8601 avec fuseau) : moment du CHANGEMENT d’état ; absent = maintenant.
- code_erreur
- facultatif : code d’erreur OCPP ou constructeur.
- frequence
- Envoyez chaque changement, et au moins une fois par heure l’état en cours de chaque point : au-delà de 2 h sans nouvelle, le temps n’est plus compté (« supervision muette »).
- reponse
- 200 : {"recus", "enregistres", "refuses": [{"index", "raison"}], "hors_registre": [identifiants inconnus du registre, gardés]} ; 422 si rien n’est enregistrable ; 401 clé ou signature invalide ; 429 au-delà de 120 appels par minute.
- taux
- Disponibilité = temps libre ou en charge / temps mesuré. Indisponible, en défaut et hors ligne comptent comme indisponibles.
- tickets
- La supervision ouvre un ticket sur une panne avec POST /api/v1/tickets (ou /api/v1/demandes) ; il apparaît en regard de l’indisponibilité.
- plateformes
- Sans rien développer, reliez depuis l’espace client : OCPI 2.2.1 (toute plateforme compatible), AMPECO, Monta, ChargePoint, Driivz (par OCPI), Virta (par OCPI), GreenFlux (format OCPI) (lecture toutes les 5 minutes, identifiants chiffrés).
- exemple
- curl -X POST https://espace.chargeteam.pro/api/v1/supervision/etats \ -H "Authorization: Bearer ct_live_…" -H "Content-Type: application/json" \ -d '{"etats":[{"identifiant":"CB-0001","point":"1","etat":"Available"},{"identifiant":"CB-0001","point":"2","etat":"Faulted","code_erreur":"GroundFailure"}]}'
Zapier, Make et n8n, sans connecteur à installer
Leurs modules « webhook » et « HTTP » suffisent : votre outil reçoit nos événements signés, crée des demandes avec votre clé, ou relit vos événements par curseur. Les extraits de code ci-dessous sont vérifiés contre nos signatures réelles ; les noms de menus sont ceux des outils à la date de rédaction.
Zapier
Déclencheur « Webhooks by Zapier » pour recevoir chaque étape ; action « Webhooks by Zapier » pour créer une demande.
- Recevoir les événements : Créez un Zap avec le déclencheur Webhooks by Zapier, événement « Catch Raw Hook » (il garde le corps brut, nécessaire à la signature). Copiez son URL, ajoutez-la comme webhook dans votre espace ChargeTeam (Intégrations), puis cliquez « Tester » : l’événement « test » arrive dans Zapier.
- Vérifier la signature : Ajoutez une étape Code by Zapier (JavaScript), avec trois champs d’entrée : corps (raw_body), signature (l’en-tête ChargeTeam-Signature) et secret (votre whsec_…). L’étape s’arrête si la signature est fausse.
// Code by Zapier (JavaScript). Champs d'entrée : corps (raw_body du déclencheur), // signature (en-tête ChargeTeam-Signature), secret (votre whsec_…). const crypto = require('crypto') const [t, ...v1] = String(inputData.signature || '').split(',') const ts = (/^t=(\d+)$/.exec(t || '') || [])[1] const attendu = ts ? crypto.createHmac('sha256', inputData.secret).update(ts + '.' + inputData.corps).digest() : null const egal = (p) => /^v1=[a-f0-9]{64}$/.test(p) && crypto.timingSafeEqual(Buffer.from(p.slice(3), 'hex'), attendu) if (!attendu || Math.abs(Date.now() / 1000 - Number(ts)) > 300 || !v1.some(egal)) throw new Error('Signature ChargeTeam invalide') output = [{ signature_valide: true, ...JSON.parse(inputData.corps) }] - Créer une demande depuis un autre outil : Action Webhooks by Zapier, événement « Custom Request » : POST https://espace.chargeteam.pro/api/v1/demandes ; en-têtes « Authorization: Bearer ct_live_… » (clé à portée demandes:ecrire) et « Content-Type: application/json » ; corps JSON, par exemple {"reference_client": "<votre n° de ticket>", "numero_serie": "SN123456", "description": "Borne en défaut, écran noir"}. Rejouer la même reference_client ne crée pas de doublon.
- Sans webhook : Déclencheur Webhooks by Zapier « Retrieve Poll » sur GET https://espace.chargeteam.pro/api/v1/evenements?apres=<suivant>&limite=100, clé à portée webhooks. Gardez la valeur « suivant » de chaque réponse et repassez-la au tour suivant : aucun événement manqué ni répété (30 jours de fenêtre). Clé de dédoublonnage : « id ».
Make
Module « Webhooks, Custom webhook » pour recevoir ; module « HTTP, Make a request » pour créer une demande ou relire les événements.
- Recevoir les événements : Scénario avec le module Webhooks « Custom webhook » ; copiez l’adresse du webhook dans votre espace ChargeTeam (Intégrations) et cliquez « Tester » pour que Make apprenne la structure. L’adresse est secrète : ne la partagez pas. Pour vérifier la signature dans Make, la fonction sha256 accepte une clé (HMAC) : comparez « v1 » à sha256(t + "." + corps brut ; "hex" ; votre secret).
- Créer une demande : Module HTTP « Make a request », méthode POST, corps de type Raw, contenu JSON : POST https://espace.chargeteam.pro/api/v1/demandes ; en-têtes « Authorization: Bearer ct_live_… » (clé à portée demandes:ecrire) et « Content-Type: application/json » ; corps JSON, par exemple {"reference_client": "<votre n° de ticket>", "numero_serie": "SN123456", "description": "Borne en défaut, écran noir"}. Rejouer la même reference_client ne crée pas de doublon.
- Relire les événements (recommandé avec Make) : Module HTTP « Make a request » planifié (toutes les 5 à 15 minutes) : GET https://espace.chargeteam.pro/api/v1/evenements?apres=<suivant>&limite=100, clé à portée webhooks. Gardez la valeur « suivant » de chaque réponse et repassez-la au tour suivant : aucun événement manqué ni répété (30 jours de fenêtre). Gardez « suivant » dans un Data store. La clé d’API authentifie l’appel : aucune signature à vérifier.
n8n
Nœud « Webhook » pour recevoir, nœud « Code » pour vérifier la signature, nœud « HTTP Request » pour créer une demande ou relire.
- Recevoir les événements : Nœud Webhook, méthode POST, réponse immédiate ; copiez son URL de production dans votre espace ChargeTeam (Intégrations), activez le workflow, puis « Tester ».
- Vérifier la signature : Nœud Code après le Webhook :
// Nœud Code (JavaScript, « Run Once for Each Item ») placé après le nœud Webhook (POST). // n8n auto-hébergé : autorisez le module avec NODE_FUNCTION_ALLOW_BUILTIN=crypto. const crypto = require('crypto') const secret = 'whsec_…' // de préférence une variable d'environnement n8n // ChargeTeam envoie du JSON compact : sa re-sérialisation redonne exactement le corps signé. const corps = JSON.stringify($json.body) const [t, ...v1] = String($json.headers['chargeteam-signature'] || '').split(',') const ts = (/^t=(\d+)$/.exec(t || '') || [])[1] const attendu = ts ? crypto.createHmac('sha256', secret).update(ts + '.' + corps).digest() : null const egal = (p) => /^v1=[a-f0-9]{64}$/.test(p) && crypto.timingSafeEqual(Buffer.from(p.slice(3), 'hex'), attendu) if (!attendu || Math.abs(Date.now() / 1000 - Number(ts)) > 300 || !v1.some(egal)) throw new Error('Signature ChargeTeam invalide') return { json: { signature_valide: true, ...$json.body } } - Créer une demande : Nœud HTTP Request, authentification « Header Auth » (Authorization = Bearer ct_live_…) : POST https://espace.chargeteam.pro/api/v1/demandes ; en-têtes « Authorization: Bearer ct_live_… » (clé à portée demandes:ecrire) et « Content-Type: application/json » ; corps JSON, par exemple {"reference_client": "<votre n° de ticket>", "numero_serie": "SN123456", "description": "Borne en défaut, écran noir"}. Rejouer la même reference_client ne crée pas de doublon.
- Relire les événements : Nœud Schedule Trigger puis HTTP Request : GET https://espace.chargeteam.pro/api/v1/evenements?apres=<suivant>&limite=100, clé à portée webhooks. Gardez la valeur « suivant » de chaque réponse et repassez-la au tour suivant : aucun événement manqué ni répété (30 jours de fenêtre). Gardez « suivant » avec les données statiques du workflow ($getWorkflowStaticData).
OpenAPI
Chaque route, sa portée (« x-chargeteam-portee »), ses paramètres, ses réponses, et chaque événement dans la section « webhooks » : https://espace.chargeteam.pro/api/v1/openapi.json.
Assistants IA (MCP)
Votre assistant IA (Claude, ChatGPT ou tout client compatible avec le Model Context Protocol) peut lire votre espace ChargeTeam : sites et bornes, demandes et leur suivi. Adresse du serveur : https://espace.chargeteam.pro/api/mcp
Transport HTTP « streamable » (un seul point d’accès, POST). Autorisation OAuth 2.1 : PKCE S256, enregistrement dynamique du client, paramètre resource, jetons émis pour ce seul serveur. Vous vous connectez avec votre compte ChargeTeam et choisissez ce que vous accordez.
Outils
- lister_sites_et_bornes : vos sites et bornes (lecture seule)
- lister_demandes : vos demandes, filtrées par statut ou par période (lecture seule)
- suivre_demande : statut, messages publics, missions liées et dates planifiées (lecture seule)
- lister_missions : vos missions : statut, dates planifiées, avancement, PV et rapport (lecture seule)
- obtenir_rapport : le rapport validé d’une mission et un lien personnel vers son PDF, valable une heure (lecture seule)
- preparer_demande : prépare une demande sur un site ou une borne de votre registre ; rien n’est envoyé tant que vous ne l’avez pas confirmée vous-même dans votre espace (brouillon valable 30 minutes), puis notre équipe la relit avant toute intervention
Par défaut, l’accès est en lecture seule. Préparer des demandes demande une case à cocher à part au moment de la connexion.
Jamais exposé : aucun montant, aucune note interne, aucune donnée sur les techniciens (ni nom, ni téléphone, ni position). Aucun outil n’envoie de message, d’e-mail ou de webhook, ni ne lit une adresse fournie par l’assistant.
Les textes saisis par des tiers (messages, descriptions, noms de sites) sont rendus dans un champ « texte_libre_non_fiable », nettoyés de leurs liens et balises : ce sont des données, jamais des instructions.
Limites : 60 appels par minute et par accès, 120 par minute et par société, 20 brouillons et 10 demandes confirmées par jour et par société. Jeton d’accès valable 1 heure, accès valable 90 jours au plus.
Chaque accès se voit et se révoque immédiatement dans votre espace, onglet Intégrations, rubrique Assistants IA, avec le journal des derniers appels. Notre équipe peut aussi couper un accès sur demande.
Ce que l’assistant lit part chez son éditeur (Anthropic, OpenAI…), que vous choisissez et qui agit sous votre responsabilité.
Connecter Claude
Dans Claude : Customize, puis Connectors, puis « Add custom connector ». Saisissez l’adresse du serveur, laissez les champs OAuth vides, validez puis cliquez sur Connect : la page de connexion ChargeTeam s’ouvre. Offres Free (un seul connecteur personnalisé), Pro et Max ; en Team et Enterprise, un Owner l’ajoute d’abord dans Organization settings, Connectors.
Connecter ChatGPT
Dans ChatGPT sur le web (offres Pro, Plus, Business, Enterprise et Education) : Settings, Security and login, activez Developer mode. Puis, dans Plugins, le bouton « + » crée une application en mode développeur : saisissez l’adresse du serveur et choisissez OAuth. Dans une conversation, choisissez Developer mode dans le menu « + » et sélectionnez l’application. ChatGPT demande votre confirmation avant un outil qui écrit.
Procédures relevées le 03/10/2026 dans la documentation officielle de chaque éditeur ; leurs écrans peuvent changer. Nos tests automatiques couvrent l’autorisation et les outils ; l’essai de bout en bout dans chaque assistant reste à faire de votre côté avec votre compte. claude.com/docs/connectors/custom/remote-mcp, developers.openai.com/api/docs/guides/developer-mode.
Contrat complet au format JSON : /api/v1/exigences. Une question d’intégration : écrivez-nous depuis votre espace, Messages.