API externe
Connectez vos systèmes à une organisation grâce à l’API externe TARGPatrol. Ce guide couvre accès, authentification et intégration sûre. Les champs et exemples propres aux opérations restent dans la référence API.
Disponibilité et clés API
L’API externe est disponible avec Base et Enterprise, pas Free. Le Propriétaire crée et gère les jetons dans l’application web. Chaque clé identifie une organisation ; ce n’est ni un mot de passe personnel ni un ID/PIN mobile.
Connectez-vous sur le web et ouvrez la bonne organisation en tant que Propriétaire.
Ouvrez Gestion → API externe puis Ajouter un jeton.
Donnez un nom clair à l’intégration, enregistrez le jeton et copiez la clé.
Stockez-la dans un gestionnaire de secrets côté serveur. Préférez des jetons séparés par intégration et révoquez ceux devenus inutiles.
Authentifier les requêtes
Envoyez des requêtes HTTPS à l’hôte indiqué dans la référence avec le chemin de base /api/v1. Transmettez la clé dans l’en-tête x-api-key. Une connexion au web n’authentifie pas une requête externe. Ne placez pas de clé dans une URL, du code navigateur, une capture, un dépôt public ou les journaux.
1x-api-key: <YOUR_API_KEY>Utiliser la référence et tester sans risque
Dans la référence, vérifiez méthode, chemin, champs requis et schéma de réponse de l’opération.
Commencez par une lecture et vérifiez l’organisation des résultats. Les essais interactifs peuvent toucher des données réelles.
Suivez la pagination, les filtres et le tri propres à l’opération ; les valeurs par défaut peuvent varier.
Avant d’écrire, vérifiez la sémantique POST, PUT ou PATCH et les valeurs omises, null ou vides. Testez d’abord dans une organisation de test.
Gérez les erreurs réseau et serveur. Ne répétez pas aveuglément les créations et ne consignez ni clés ni données personnelles.
Référence API et explorateur interactif
Résoudre les problèmes d’accès
Pour 401, vérifiez x-api-key et l’existence du jeton. Pour 403, vérifiez l’abonnement et les conditions de l’opération. Pour 404, vérifiez URL, identifiant et organisation ; pour 400, format et validation. Remplacez toute clé divulguée et mettez à jour les intégrations concernées.
Nouveautés de la référence API
1.1
La référence 1.1 a rendu lastName obligatoire lors de la création d’un utilisateur et corrigé le nom du champ d’affectation aux sites en locationIds. Consultez le schéma utilisateur actuel pour préparer vos requêtes.
1.2
La référence 1.2 a ajouté des URL de téléchargement signées et temporaires pour les pièces jointes de l’ancien module Issues, avec des URL de miniatures lorsqu’elles sont disponibles. Les liens doivent être utilisés avant leur expiration.
1.3
La référence 1.3 a ajouté la consultation et la création de commentaires pour les tâches, les incidents et l’ancien module Issues, ainsi que la modification et la suppression des commentaires créés via l’API. Les pièces jointes existantes peuvent être consultées et téléchargées ; cette API ne permet pas d’ajouter des pièces jointes ni de modifier les commentaires créés par les utilisateurs de l’application.
1.4
La référence 1.4 a ajouté les métadonnées et la validation des téléphones internationaux des utilisateurs. Consultez les schémas actuels pour les règles exactes des requêtes et mises à jour.
1.5
La référence 1.5 a ajouté l’historique de modifications par enregistrement en lecture seule. Les ajouts suivants documentent les historiques Utilisateur, Site et Point, ainsi que l’ordre des points et les opérations de réorganisation/déplacement. Consultez la référence actuelle pour la compatibilité et les opérations prises en charge.
1.6
La référence 1.6 documente les récurrences calendaires avec un fuseau horaire explicite et un modèle local de début et de fin enregistré. Consultez le schéma actuel avant de créer ou modifier une série.
1.7
La référence 1.7 ajoute la lecture des événements de géorepérage et les champs associés des sites et utilisateurs, et harmonise les opérations de tags prises en charge. L’authentification et /api/v1 ne changent pas. Consultez la référence actuelle pour les schémas, droits et validations ; cette mise à jour n’inclut pas les webhooks de géorepérage.
Il s’agit de versions de référence/schéma, pas de nouveaux préfixes URL : le chemin reste /api/v1. Ce résumé ne remplace pas un journal complet des modifications. Les webhooks se configurent séparément pour les mises à jour événementielles.