Documentation de l’API

Shifton Tâches permet d’automatiser le travail avec la plateforme et de la connecter à des services externes via une API ouverte. L’API donne accès à toutes les entités clés — tâches, clients, employés, checklists, inventaire, zones de service, documents Documents financiers et rapports — Shifton peut donc être relié à vos systèmes RH, de paie et d’analytique, ainsi qu’aux services internes de l’entreprise.

La documentation est publiée en deux versions :

🚀 Nouvelle documentation — la version à jour du référentiel, avec une structure actualisée et les méthodes les plus récentes : 👉 https://api2.shifton.com/openapi/
📄 Ancienne documentation — la version précédente (toujours prise en charge pour les intégrations existantes) : 👉 https://api2.shifton.com/docs/

Les deux versions peuvent être ouvertes directement depuis l’application — dans la section Developer, sur l’onglet Aperçu, avec les boutons «Nouvelle documentation» et «Ancienne documentation».

La documentation est disponible en deux langues. Dans le coin supérieur droit de la page de la nouvelle documentation se trouve un sélecteur EN / RU — la langue choisie est mémorisée.

Comment obtenir une clé API

La clé API se crée dans l’application elle-même :

Ouvrez la section Developer.
Passez à l’onglet Clés API («Clés API»).
Cliquez sur «Créer une clé API».

Que remplir lors de la création de la clé

Le panneau latéral Créer une clé API s’ouvre avec les champs suivants :

Titre — le nom de la clé, champ obligatoire. Nommez-la selon son usage, afin de savoir plus tard ce qu’il faut désactiver : «Export vers 1C», «Rapports pour l’analytique».
Expire à — la date après laquelle la clé cessera d’être valide. Si le champ reste vide, la durée de validité est illimitée.
Accès — l’étendue des droits de la clé :
Full access (act as me) — la clé fonctionne en votre nom et avec vos droits.
Autorisations restreintes — un ensemble limité d’autorisations que vous choisissez vous-même.

Cliquez sur Ajouter pour créer la clé, ou sur Annuler pour fermer le panneau.

📷 *Capture du panneau de création de clé — à prendre sur la production*

La clé est créée pour une entreprise précise et ne fonctionne qu’avec ses données. Elle peut être révoquée à tout moment — la révocation prend effet immédiatement, et toutes les requêtes suivantes effectuées avec cette clé renverront l’erreur 401.

Important : la clé créée n’est affichée qu’une seule fois. Copiez-la immédiatement et conservez-la en lieu sûr — il est impossible de l’obtenir à nouveau. Si la clé est perdue, créez-en une nouvelle et révoquez l’ancienne.

Autorisation

Toutes les requêtes vers l’API sont signées par la clé dans l’en-tête :

Authorization: Bearer {your_API_key}

Adresse de base de l’API :

https://api2.shifton.com/work/1.0.0

Une requête sans clé valide renvoie 401 et le corps {"message":"Unauthenticated."}.

Première requête

Par exemple, pour obtenir la liste des employés de l’entreprise (remplacez {companyId} par l’ID de votre entreprise) :

GET https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees
Authorization: Bearer {your_API_key}
Accept: application/json

La même chose avec curl :

curl -H "Authorization: Bearer {your_API_key}" \
     -H "Accept: application/json" \
     https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees

L’ID de l’entreprise est visible dans la barre d’adresse de l’application : app.shifton.com/c/8397/... — le nombre après /c/.

Ce qui est accessible via l’API

Le référentiel couvre plus de 360 méthodes. Principales sections pour le service sur le terrain :

Tâches — /companies/{companyId}/tasks : création, modification, statuts, fichiers des tâches.
Liste de choses à faire (To Do) — /companies/{companyId}/todo.
Clients — /companies/{companyId}/clients, ainsi que les adresses et les champs personnalisés des clients.
Checklists — /companies/{companyId}/checklists.
Zones de service — /companies/{companyId}/tasks/service-areas.
Compétences — /companies/{companyId}/skills.
Employés — /companies/{companyId}/employees : ajout, modification, départ et réintégration.
Inventaire — articles, catégories, kits et stocks dans les entrepôts.
Documents financiers — devis, ordres de travail, factures, reçus, compteurs de documents et logo.
Rapports — export des données de travail et de présence.

Sont également accessibles les plannings et les postes, les congés et les demandes d’absence, la présence, la facturation et la facturation des SMS, les notifications et les modules.

Webhooks

Si, au lieu d’interroger régulièrement l’API, vous préférez recevoir les événements au moment où ils se produisent, utilisez les webhooks — onglet Webhooks dans la section Developer. Shifton enverra lui-même une requête à votre adresse dès que l’événement voulu se produira ; la liste des événements pris en charge est renvoyée par une méthode distincte.

Codes d’erreur

L’API Shifton utilise les codes de statut HTTP standard :

200 — la requête a abouti.
201 — l’objet a été créé avec succès.
400 — paramètres de requête incorrects.
401 — erreur d’autorisation : la clé n’a pas été transmise, elle n’est pas valide ou elle a été révoquée.
403 — accès refusé.
404 — ressource introuvable (le plus souvent une faute de frappe dans l’adresse de la méthode).
500 — erreur du serveur.

Conseils d’utilisation

Pour les nouvelles intégrations, utilisez la nouvelle documentation — l’ancienne est conservée pour les intégrations déjà en service.
Pour tester les requêtes, Postman ou curl sont pratiques — ils permettent de voir la réponse sans écrire une seule ligne de code.
Ne conservez pas la clé en clair dans le code et ne la transmettez pas à des tiers : la clé donne accès aux données de l’entreprise.
Respectez les limites de fréquence des requêtes (rate limits) — les dépasser peut entraîner un blocage temporaire de l’accès à l’API.

Questions fréquentes

Question : Où obtenir une clé API ? Réponse : Dans l’application : section Developer → onglet Clés API → bouton «Créer une clé API». La clé est délivrée pour l’entreprise en cours.

Question : J’ai fermé la fenêtre sans copier la clé. Où la voir ? Réponse : Nulle part — la clé n’est affichée qu’une seule fois et n’est pas redélivrée. Créez une nouvelle clé et révoquez l’ancienne.

Question : Comment révoquer une clé tombée en de mauvaises mains ? Réponse : Supprimez-la sur l’onglet Clés API. La révocation prend effet immédiatement : toutes les requêtes effectuées avec cette clé renverront aussitôt 401.

Question : Quelle différence entre «Full access» et «Restricted permissions» ? Réponse : Full access (act as me) donne à la clé les mêmes droits que les vôtres. Autorisations restreintes permet de n’accorder à la clé que l’ensemble d’autorisations choisi — c’est plus sûr pour une intégration qui n’a besoin que d’une partie des données.

Question : Peut-on limiter la durée de validité de la clé ? Réponse : Oui, avec le champ Expire à lors de la création. S’il n’est pas rempli, la clé est valable sans limite de durée.

Question : Une même clé fonctionne-t-elle pour plusieurs entreprises ? Réponse : Non. La clé est rattachée à l’entreprise dans laquelle elle a été créée et ne fonctionne qu’avec ses données. Pour une autre entreprise, créez une clé distincte.

Question : Quelle est l’adresse de base de l’API ? Réponse : https://api2.shifton.com/work/1.0.0. Vient ensuite le chemin de la méthode, par exemple /companies/{companyId}/tasks.

Question : Où trouver l’ID de l’entreprise pour les requêtes ? Réponse : Il figure dans la barre d’adresse de l’application juste après /c/ — par exemple, dans app.shifton.com/c/8397/tasks l’identifiant de l’entreprise est 8397.

Question : Quelle version de la documentation utiliser ? Réponse : Pour les nouvelles intégrations — la nouvelle (api2.shifton.com/openapi). L’ancienne (api2.shifton.com/docs) est prise en charge pour les intégrations existantes.

Question : Existe-t-il une documentation en russe ? Réponse : Oui. Sur la page de la nouvelle documentation, dans le coin supérieur droit, se trouve le sélecteur EN / RU.

Question : Avec quoi tester les requêtes vers l’API ? Réponse : Le plus pratique est Postman ou curl — ils permettent d’envoyer des requêtes et de voir les réponses sans écrire de code.

Question : Pourquoi ai-je une erreur 401 alors que j’ai copié la clé ? Réponse : Vérifiez que la clé est transmise dans l’en-tête Authorization précédée du mot Bearer, que la clé n’a pas été révoquée et que sa durée de validité n’a pas expiré.

Question : Pourquoi ai-je une erreur 404 ? Réponse : Le plus souvent l’adresse est erronée : la partie de base doit être https://api2.shifton.com/work/1.0.0, et le chemin de la méthode doit contenir le bon {companyId}.

Question : Que peut-on automatiser via l’API ? Réponse : La création et la modification des tâches, la gestion des clients et de leurs adresses, les checklists, les zones de service, les compétences, les employés, l’inventaire, les documents Documents financiers et l’export des rapports, ainsi que les plannings, les postes et les congés.

Question : Peut-on recevoir les événements de Shifton sans interroger l’API ? Réponse : Oui, il existe pour cela les webhooks — onglet Webhooks dans la section Developer.

Question : Le changement de mot de passe affecte-t-il l’intégration ? Réponse : Non. Les intégrations fonctionnent avec une clé API, et non avec le mot de passe du compte.