API et webhooks

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.

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.

* 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":"noc@exemple.fr"}'

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":"noc@exemple.fr"}'

regle

Une demande est relue par notre équipe avant toute affectation : rien ne part vers un technicien sans validation humaine.

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.

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.

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_…>

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.

verification

Refusez un horodatage de plus de 5 minutes et comparez la signature à temps constant.

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

Prénom I.

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

absent

Aucun montant, jamais.

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
function verifier(secret, corps, entete) {
  const m = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(entete || '')
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false
  const attendu = createHmac('sha256', secret).update(m[1] + '.' + corps).digest()
  return timingSafeEqual(attendu, Buffer.from(m[2], '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:
    m = re.fullmatch(r"t=(\d+),v1=([a-f0-9]{64})", entete or "")
    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 hmac.compare_digest(attendu, m.group(2))

À 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.

• 400 : corps illisible (JSON invalide).
• 401 : clé absente, inconnue ou révoquée.
• 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.
• 5xx : incident de notre côté ; rejouez l’appel avec le même « reference_client », il ne créera pas de doublon.

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

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.

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

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.

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.

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 ; statuts, messages publics de l’équipe et rapport validé reviennent chez vous.

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.

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"}]}'