Introduction
Tout ce dont vous avez besoin pour intégrer l'API Piloterr dans votre application.
Démarrez avec l'API Piloterr en quelques minutes. Envoyez des requêtes HTTP à nos points d'accès et recevez des réponses JSON structurées.
Démarrage rapide
Obtenez votre clé API
Inscrivez-vous sur votre tableau de bord et copiez votre clé API depuis la page Paramètres.
Effectuez votre première requête
Incluez votre clé dans l'en-tête x-api-key et appelez n'importe quel point d'accès :
curl "https://api.piloterr.com/v2/usage" \
-H "x-api-key: YOUR_API_KEY"Gérez la réponse
Chaque requête réussie retourne un objet JSON avec des données structurées. Consultez les pages individuelles des points d'accès pour les schémas de réponse et les exemples.
Authentification
Toutes les requêtes API doivent inclure un en-tête x-api-key. Vous pouvez trouver votre clé dans votre tableau de bord > clés API.
curl -H "x-api-key: xxxx" https://api.piloterr.com/v2/usageGardez votre clé API secrète. Ne l'exposez pas dans du code côté client ou dans des dépôts publics.
Codes de statut
Les appels synchrones sont facturés au 200. Les appels asynchrones (is_async=true) retournent un 202 (non facturé) et sont facturés lorsque la tâche se termine avec succès — enregistré comme 201 dans vos journaux de requêtes. Le polling GET /v1/jobs/{job_id} est toujours gratuit. Les tâches échouées (500) ne sont jamais facturées. La facturation du 404 varie selon le point d'accès (consultez la page de chaque point d'accès). Toutes les autres réponses 4xx/5xx sont gratuites. Si le client ferme le socket avant l'envoi d'une réponse synchrone, l'appel reste facturé lorsque le résultat est un statut facturable. Un 401 de limite de débit est une réponse JSON normale : le serveur ne coupe pas le socket.
| Code | Facturé | Statut | Action |
|---|---|---|---|
200 | Oui | Appel API réussi (synchrone) | Aucune action requise. |
201 | Oui | Tâche asynchrone terminée | Apparaît dans vos journaux de requêtes quand une tâche asynchrone se termine avec succès — c'est à ce moment que la tâche est facturée. Jamais retourné comme réponse HTTP. |
202 | Non | Accepté (asynchrone) | La tâche a été acceptée et mise en file d'attente. Interrogez GET /v1/jobs/{job_id} pour obtenir le résultat — le polling est toujours gratuit. |
400 | Non | Requête incorrecte | Vérifiez vos paramètres et leurs types. Consultez la documentation pour plus d'informations. |
401 | Non | Clé API invalide | Vérifiez votre clé API (en-tête x-api-key ou chaîne de requête x_api_key). |
401 | Non | Clé API inactive | Activez votre clé API dans la section Clés API des paramètres de votre compte. |
401 | Non | Clé API expirée | Mettez à jour votre clé API ou générez-en une nouvelle. |
401 | Non | Rate limit exceeded | Le serveur renvoie ce 401 avec un corps JSON et ne coupe pas le socket. Attendez et réessayez. Mettez à niveau votre plan ou augmentez les quotas par clé si cela se produit souvent. |
402 | Non | Payment required | Rechargez des crédits, mettez à niveau votre plan, activez le Rechargement automatique ou réglez les factures en attente. |
403 | Non | Interdit | Vérifiez vos permissions. Pour API Stats, un HTTP 403 signifie que le point d'accès n'est pas activé sur votre compte : contactez le support pour l'activer. |
404 | Selon le cas | Introuvable | La facturation est spécifique à chaque point d'accès. Consultez la page du point d'accès concerné. |
413 | Non | Charge trop volumineuse | Le fichier envoyé ou le corps de la requête dépasse la limite de taille. Consultez la documentation pour les tailles maximales. |
500 | Non | Erreur interne | Réessayez l'action ou contactez notre équipe de support. |
Consultez la page Crédits pour un détail complet par point d'accès, Stats pour la santé d'infrastructure, Clés API pour la gestion des clés, et Bonnes pratiques et Gestion des erreurs pour les recommandations d'intégration. Nouveau sur la plateforme ? Le Glossaire définit tous les termes clés.
Points d'accès
Consultez chaque point d'accès dans la Référence API, ou ouvrez-en un directement :