API publique

L’API publique permet à vos propres logiciels de dialoguer avec Service Suite : un logiciel comptable qui récupère les factures, un portail client qui crée une intervention, un tableau de bord qui suit l’état de vos équipements.

C’est une interface produit : vous travaillez avec des clients, des sites, des équipements, des ordres de service, des contrats, du stock et des factures. Vous n’avez jamais besoin de savoir comment Service Suite est construit en interne.

L’écran des clés API. Une clé agit toujours au nom d’un utilisateur choisi.

À quoi cela sert

• Garder clients et sites alignés avec votre système de gestion existant.
• Laisser un autre système créer des ordres de service — un outil de supervision, un formulaire web, un portail client.
• Lire les factures et les niveaux de stock à des fins de reporting.
• Prévenir un système externe dès qu’une intervention est terminée.

Qui peut l’utiliser

Rôle	Ce qu’il fait
Administrateur	Crée les clés, attribue les droits et révoque les clés
Votre développeur ou prestataire	Utilise la clé pour l’intégration

Prérequis : un accès administrateur à Service Suite, et quelqu’un capable de construire l’intégration. Aucune licence ni module supplémentaire n’est nécessaire.

Démarrage rapide

Adresse de base	https://<votre-adresse-service>/api/v1/
Spécification	/api/v1/openapi.json — OpenAPI 3.1
Page de documentation	/api/docs

curl https://<votre-adresse-service>/api/v1/me \
  -H "Authorization: Bearer <API_KEY>"

/me est le contrôle de santé : il prouve que la clé fonctionne et montre exactement ce qu’elle peut faire.

{
  "data": {
    "credential": {
      "name": "Comptabilité — synchronisation nocturne",
      "prefix": "a1b2c3d4",
      "scopes": ["customers:read", "invoices:read"],
      "expires_at": null
    },
    "acting_as": { "id": 42, "name": "Intégration comptabilité" },
    "api_version": "v1"
  }
}

Créer une clé

1. Allez dans Paramètres → API publique → Nouvelle clé API.

2. Donnez à la clé un nom qui indique à quoi elle sert. Ce nom apparaît dans le journal d’accès.

3. Choisissez au nom de quel utilisateur la clé agit. C’est la véritable limite de droits — voir ci-dessous.

4. Cochez les droits (scopes) dont l’intégration a besoin, et pas davantage.

5. Définissez éventuellement une date d’expiration et des plages IP autorisées.

6. Enregistrez. Le secret est affiché une seule fois. Copiez-le immédiatement dans votre coffre-fort de mots de passe.

Le secret ne peut plus être récupéré ensuite

Seule une empreinte irréversible du secret est conservée. Personne ne peut le retrouver par la suite — Digitalnatie non plus. Si vous le perdez, renouvelez la clé.

Une clé n’est pas un droit

Chaque requête s’exécute au nom de l’utilisateur choisi, avec ses droits et son périmètre de visibilité. Une clé rattachée à un technicien qui ne voit que ses propres ordres voit exactement la même chose via l’API — pas davantage.

Les droits de la clé ne peuvent donc que restreindre, jamais élargir. Créez un utilisateur dédié aux intégrations, avec exactement les droits nécessaires.

Droits (scopes)

Scope	Ce qu’il ouvre
customers:read / customers:write	Clients
locations:read / locations:write	Sites & emplacements
assets:read / assets:write	Équipements & matériel
service_orders:read / service_orders:write	Ordres de service
contracts:read	Contrats d’entretien
stock:read	Stock
invoices:read	Factures
reports:read	Données de reporting
webhooks:manage	Gestion des webhooks

Le stock et les factures sont en lecture seule en v1. Les écritures comptables et les mouvements de stock ont lieu dans Service Suite même, pas via l’API.

Ce que vous pouvez lire et modifier

Ressource	Lire	Créer	Modifier	Archiver
customers	✅	✅	✅	✅
locations	✅	—	✅	—
assets	✅	✅	✅	✅
service-orders	✅	✅	✅	—
contracts	✅	—	—	—
stock	✅	—	—	—
invoices	✅	—	—	—

GET    /api/v1/<ressource>              liste
GET    /api/v1/<ressource>/<id>         un enregistrement
POST   /api/v1/<ressource>              créer
PATCH  /api/v1/<ressource>/<id>         modifier
DELETE /api/v1/<ressource>/<id>         archiver (jamais une suppression définitive)

DELETE archive. Rien n’est jamais supprimé définitivement via l’API.

Les champs sont exposés délibérément

Chaque ressource renvoie une liste fixe de champs. Un nouveau champ dans Service Suite n’apparaît pas de lui-même dans l’API — c’est une décision délibérée champ par champ, et c’est ce qui distingue une API d’un export de base de données sur HTTP.

Pagination, filtrage et tri

curl "https://<votre-adresse-service>/api/v1/assets?customer_id=57&page=2&page_size=100&sort=-write_date" \
  -H "Authorization: Bearer <API_KEY>"

Paramètre	Par défaut	Maximum
page	1	—
page_size	50	200

Si vous demandez plus de 200, vous en obtenez 200 — pas une erreur.

Trier avec sort, plusieurs champs séparés par des virgules, - devant pour un tri décroissant. Filtrer avec les noms de filtres de la ressource ; updated_since existe sur chaque ressource et c’est ce qu’il vous faut pour une synchronisation incrémentale.

Les noms de tri et de filtre sont fixes par ressource. Un nom qui n’existe pas est refusé plutôt qu’ignoré en silence — vous repérez ainsi une faute de frappe immédiatement, au lieu de découvrir des mois plus tard que votre filtre n’a jamais fonctionné.

Réessayer sans risque

Envoyez votre propre Idempotency-Key avec chaque POST :

curl -X POST https://<votre-adresse-service>/api/v1/service-orders \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Idempotency-Key: <VALEUR_UNIQUE_PAR_REQUETE>" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": 57, "location_id": 112, "description": "Entretien annuel"}'

Si vous perdez la connexion et réessayez avec la même valeur de clé, vous récupérez le résultat d’origine au lieu d’un deuxième ordre de service. Sans cet en-tête, une requête répétée est une véritable deuxième requête.

Chaque requête renvoie également un X-Request-Id. Mentionnez-le lors d’un signalement — c’est ainsi que votre requête est retrouvée dans le journal.

Débit de requêtes

Type	Par minute
Lecture	600
Écriture	120
Gestion des webhooks	60
Authentifications échouées	20

Le compteur s’applique par clé : une intégration active ne consomme donc pas le budget d’une autre. En cas de dépassement, vous recevez 429 avec un en-tête Retry-After. Respectez-le et réessayez avec un délai croissant.

Erreurs

Code	Signification	Ce que vous faites
400	Paramètre ou champ invalide	Corrigez la requête ; la réponse nomme le champ
401	Clé absente, erronée, expirée ou révoquée	Vérifiez la clé
403	La clé n’a pas le scope, ou l’utilisateur n’a pas le droit	Attribuez le scope, ou ajustez les droits de l’utilisateur
404	N’existe pas, ou hors du périmètre de l’utilisateur	Vérifiez l’id et les droits
409	Conflit — par exemple une Idempotency-Key réutilisée avec un contenu différent	Utilisez une nouvelle valeur
429	Trop de requêtes	Attendez et réessayez

Un 403 dû à un scope manquant et un 403 dû aux droits de l’utilisateur appellent des corrections différentes. La réponse indique lequel des deux s’applique.

Webhooks

Une possibilité que vous activez vous-même

Les webhooks sont pleinement pris en charge, mais aucun n’est préconfiguré. Une adresse de réception se crée et se gère par environnement. Tant que vous n’en créez aucune, Service Suite n’envoie rien vers l’extérieur.

Plutôt que d’interroger en boucle, laissez Service Suite vous prévenir.

Événement	Quand
service_order.created	Un ordre de service a été créé
service_order.updated	Un ordre de service a été modifié
service_order.status_changed	Le statut a changé
service_order.completed	L’intervention est terminée
asset.created / asset.updated	Un équipement a été créé ou modifié
contract.created	Un contrat d’entretien a été créé
invoice.posted	Une facture a été comptabilisée

Chaque livraison porte une signature HMAC-SHA256. Vérifiez-la avant d’utiliser le contenu — c’est ainsi que vous savez que la notification provient réellement de votre environnement. Les livraisons se font en arrière-plan et sont réessayées avec un délai croissant en cas d’échec.

Votre adresse de réception doit être accessible publiquement. Les adresses sur un réseau privé sont refusées.

Les webhooks exigent un stockage chiffré

Une clé de signature doit rester lisible pour pouvoir signer : elle ne peut donc pas être hachée. Elle est de ce fait conservée chiffrée, avec une clé qui vit en dehors de la base de données. Si ce chiffrement n’est pas disponible dans un environnement, un webhook est refusé plutôt que stocké sans protection.

Cloisonnement entre environnements

Chaque client travaille dans son propre environnement cloisonné. L’API détermine cet environnement à partir de l’adresse par laquelle vous l’appelez ; aucun paramètre ne permet de changer d’environnement, et une telle tentative est refusée. De plus, chaque clé est liée à l’environnement qui l’a émise : une copie d’un environnement ne peut donc jamais être atteinte avec les clés de l’original.

Traçabilité

Chaque requête est enregistrée : horodatage, clé, méthode, ressource, code de réponse, durée et une indication d’origine. Le contenu des requêtes, les clés et les en-têtes ne sont jamais enregistrés. Le journal reste ainsi utile pour analyser un problème sans devenir lui-même une seconde copie de vos données.

Limites connues

Mentionnées plutôt que passées sous silence.

• Le stock et les factures sont en lecture seule en v1. Aucune création ni modification n’est possible via l’API.
• Les techniciens, équipes, projets et heures n’ont pas de ressource propre en v1.
• L’API ne connaît qu’une version, v1. Les changements susceptibles de casser des intégrations existantes iront dans une version suivante.

Bonnes pratiques

• Une clé par intégration, jamais une clé partagée. Vous pouvez ainsi en révoquer une sans casser les autres.
• N’attribuez que les scopes utilisés par l’intégration. Commencez en lecture seule.
• Utilisez toujours Idempotency-Key lors de la création.
• Synchronisez de façon incrémentale avec updated_since plutôt que de tout récupérer à chaque fois.
• Conservez le secret dans un coffre-fort, jamais dans le code source ni dans un fichier de configuration versionné.
• Définissez une date d’expiration pour les clés détenues par des tiers.

Étape suivante

• Droits & sécurité — quel utilisateur devient la clé
• Intégrations — connexions prêtes à l’emploi
• Automatisations — automatiser sans programmer
• Se connecter avec Microsoft ou Google