ChargeTeam

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.

ChampTypeDescription
reference_clientstring, ≤ 120
site_nomstring, ≤ 200
adressestring, ≤ 300
villestring, ≤ 120
code_postalstring, ≤ 20
latitudenumber
longitudenumber
descriptionstring, ≤ 2000
typestring (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_nomstring, ≤ 160
contact_emailstring, email, ≤ 200
contact_telstring, ≤ 40
contact_terrain_nomstring, ≤ 160
contact_terrain_telstring, ≤ 40
accesstring, ≤ 500
site_en_libre_accesboolean
marquestring, ≤ 120
modelestring, ≤ 120
numero_seriestring, ≤ 120
borne_idstring, ≤ 120
courantstring (ac, dc)
site_idstring, uuid
equipement_idstring, 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énementQuand
demande.recueDemande reçue
mission.planifieeIntervention planifiée
technicien.affecteTechnicien affecté
technicien.arriveTechnicien arrivé
mission.termineeIntervention terminée
pv.signePV signé
rapport.valideRapport validé
demande.refuseeDemande refusée
mission.annuleeIntervention annulée
ticket.createdTicket ouvert
ticket.status_changedStatut du ticket changé
ticket.messageMessage 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).
pdf
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.

  1. 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.
  2. 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) }]
  3. 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.
  4. 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.

  1. 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).
  2. 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.
  3. 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.

  1. 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 ».
  2. 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 } }
  3. 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.
  4. 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.