Documentation pour développeurs

L'API de Segesio ERP vous permet de lire et d'écrire les données de votre compte — activités, dépenses, intrants, récoltes, et le reste des modules opérationnels — depuis vos propres systèmes, sans passer par l'interface web.

Ce n'est ni une API miroir ni une simulation : une clé API avec un scope d'écriture appelle exactement les mêmes points de terminaison que l'application web, authentifiée avec l'identité d'un utilisateur réel de votre compte. C'est une fonctionnalité du plan Enterprise.

Chaque requête porte la clé API dans l'en-tête X-API-Key. Il n'y a ni connexion ni jeton qui expire en quelques minutes — la clé est valide jusqu'à la date d'expiration qui lui a été attribuée.

La clé complète ne s'affiche qu'une seule fois, au moment de sa création. Conservez-la dans un endroit sûr (un gestionnaire de secrets, pas un dépôt de code) — si vous la perdez, il faudra en générer une nouvelle.

Un utilisateur avec un rôle d'administrateur peut créer des clés depuis Paramètres → Clés API, dans l'application.

1. Choisissez un nom explicite (par exemple, le système qui va l'utiliser).
2. Sélectionnez les scopes nécessaires — ne cochez jamais plus que ce que cette intégration utilise réellement.
3. Si un scope concerne l'écriture, choisissez quel membre de votre équipe cette clé représente : les écritures s'exécutent avec l'identité et les permissions réelles de cette personne.
4. Définissez une expiration (une valeur par défaut est proposée si vous n'en choisissez pas) et confirmez.

La clé complète apparaît une seule fois à l'écran, juste après sa création. Copiez-la avant de fermer cette vue.

Chaque scope suit le même format que le reste du système : module:action. Une clé ne peut jamais faire plus que ce que l'utilisateur auquel elle est liée pourrait faire manuellement dans l'interface.

L'action supprimer n'est jamais disponible pour aucune clé, sur aucun module — pour supprimer quelque chose, passez par l'interface normale.

L'accès en lecture est inclus dans le plan Enterprise. L'accès en écriture est une activation distincte, activée par notre équipe sur demande — contactez-nous (voir Support, ci-dessous) pour l'activer sur votre compte.

Tous les points de terminaison utilisent le même préfixe que l'API réelle de Segesio ERP. Un exemple, créer une activité :

Lorsque la clé a un scope d'écriture, l'activité créée est attribuée à l'utilisateur réel auquel la clé est liée — la même valeur que si cette personne l'avait saisie depuis le web.

Les réponses réussies renvoient la ressource créée ou demandée au format JSON. Une erreur — permission manquante, donnée invalide, clé expirée — renvoie un code HTTP correspondant et un corps dans ce format :

C'est le format que le framework utilise par défaut sur la plupart des points de terminaison. Il n'est pas encore standardisé à 100 % dans tous les cas — nous le signalons pour que votre intégration ne dépende pas d'une structure exacte au-delà de statusCode/message.

• Limitation de débit par clé (pas par adresse IP) : une clé partage les mêmes limites que le trafic normal de l'application, regroupées par la clé elle-même plutôt que par IP.
• Chaque clé a une expiration obligatoire — 90 jours par défaut si elle a un scope d'écriture, 180 jours si elle est en lecture seule. Vous pouvez choisir une valeur différente à la création.
• Jusqu'à 30 scopes par clé.

Si vous n'avez besoin de lire qu'une poignée de données — exploitations, parcelles, NDVI, récoltes, météo — sans rien écrire, il existe une API plus simple et plus stable conçue pour cela, avec ces scopes :

• fincas:read
• lotes:read
• ndvi:read
• harvest:read
• weather:read

C'est un contrat plus restreint et plus stable, utile pour des intégrations simples. Il ne remplace pas le catalogue complet ci-dessus, qui permet réellement d'écrire.

• La plupart des points de terminaison de liste renvoient le résultat complet, sans pagination — pour de gros volumes, filtrez avec les paramètres acceptés par chaque point de terminaison.
• Pas encore de webhooks sortants : votre intégration doit interroger l'API (polling), Segesio n'a aucun moyen de vous notifier d'un changement.
• Le format d'erreur n'est pas standardisé à 100 % sur tous les points de terminaison — voir la note dans Format des réponses et des erreurs.
• Pas de rotation de clé sans recréation : pour faire tourner une clé, il faut en créer une nouvelle et révoquer l'ancienne.

Besoin que nous activions l'écriture sur votre compte, ou une question précise sur un point de terminaison ? Contactez-nous.