API, webhooks et MCP : reliez votre ERP au registre

Si vous gérez l'exploitation avec un ERP, un tableau de coûts ou le logiciel de votre conseiller, il n'y a aucune raison de saisir chaque travail deux fois. Voici la documentation pour sortir le registre, les coûts et l'état de conformité depuis l'extérieur, et pour y faire entrer des travaux depuis le système que vous utilisez déjà.

La base est https://agrogps-api.fly.dev/api/v1. Elle est en production depuis le 17 septembre 2026. Elle répond toujours en JSON, erreurs comprises.

Deux façons de s'identifier

La clé se crée une fois depuis votre session et ne s'affiche qu'une seule fois : ensuite nous ne gardons que son empreinte. Si vous la perdez, on la révoque et on en crée une autre. Une clé en lecture seule qui tente d'écrire reçoit 403 AUT_004. Les clés ne peuvent ni créer ni supprimer d'autres clés ou des webhooks : cela passe toujours par la session d'une personne.

curl -X POST https://agrogps-api.fly.dev/api/v1/api-keys \
  -H "Authorization: Bearer $SESION" \
  -H "Content-Type: application/json" \
  -d '{"name":"ERP Sage","scope":"read"}'

Ce que vous pouvez lire

Avec une clé en écriture, vous pouvez aussi enregistrer des travaux avec POST /sync/entries, avec le même corps que l'appli. La synchronisation se fait par since : un traitement de nuit ne rapatrie que ce qui a changé.

Commencer gratuitement

Webhooks signés

Au lieu de demander toutes les cinq minutes, c'est nous qui prévenons. Vous déclarez une URL https publique et nous envoyons un avis quand il se passe quelque chose dans une exploitation dont vous êtes titulaire ou gestionnaire.

Chaque envoi porte X-Agro-Event, X-Agro-Timestamp en secondes Unix et X-Agro-Signature avec le HMAC-SHA256 de "<timestamp>.<cuerpo>". Vérifiez les deux : la signature, et que l'horloge n'a pas dérivé de plus de cinq minutes.

import hmac, hashlib, time

ts = request.headers["X-Agro-Timestamp"]
assert abs(time.time() - int(ts)) < 300
esperada = "sha256=" + hmac.new(
    secreto.encode(), ts.encode() + b"." + cuerpo, hashlib.sha256
).hexdigest()
ok = hmac.compare_digest(esperada, request.headers["X-Agro-Signature"])

Les règles d'envoi, dites clairement pour éviter les surprises : une tentative, six secondes d'attente et aucune relance. Nous ne suivons pas les redirections et nous refusons les adresses privées, de lien local et de métadonnées cloud, à la déclaration de l'URL comme à la résolution DNS de chaque envoi. Si votre système a besoin de garanties, utilisez le webhook comme avis et GET /sync/entries avec since comme filet de sécurité : l'avis est une politesse, l'API fait foi.

MCP pour assistants IA

La même API est exposée comme serveur MCP, le protocole qu'utilisent les assistants pour se brancher sur des outils. Vous pouvez demander à un assistant quelles exploitations sont en retard, combien a coûté la campagne ou ce qui manque avant un contrôle.

{ "mcpServers": { "agro-gps": {
  "command": "npx", "args": ["-y", "agro-gps-mcp"],
  "env": { "AGROGPS_API_KEY": "agk_…" } } } }

Outils disponibles : list_farms, list_entries, entry_history, list_groups, group_overview, advisor_portfolio, advisor_pending et record_entry. Le dernier ne fonctionne qu'avec une clé en écriture, est marqué dans l'historique comme écriture par API et n'envoie jamais rien à l'administration.

Pourquoi l'API ne permet pas de tricher

Une API posée sur un registre qui a une valeur légale doit pouvoir se regarder en face. En Espagne, le RD 1054/2022 autorise à tenir le cahier d'exploitation avec tout logiciel qui respecte l'annexe II et qui est interopérable avec le SIEX, et précise que c'est le titulaire, pas le logiciel, qui répond de l'exactitude. Le principe est le même en France : le registre est de la responsabilité de l'exploitant. Notre part, c'est l'intégrité, et elle est inscrite dans le code.

Erreurs

Toujours {"code":"INT_NNN","message":"…"}, jamais une trace. Celles que vous verrez le plus : AUT_003 clé invalide, AUT_004 clé en lecture seule, AUT_429 trop de tentatives, AUT_503 authentification indisponible (ce n'est pas une mauvaise clé : réessayez), INT_003 URL qui n'est pas en https, INT_403 opération qui exige une session, INT_404 clé ou webhook qui n'est pas à vous.

Comment obtenir une clé

L'API est comprise dans les formules entreprise et conseil. Si vous avez déjà un compte, la clé se crée depuis l'appli. Si vous évaluez l'intégration avant de souscrire, écrivez à support@agrogps.eu en indiquant quel système vous voulez relier, et nous vous donnons un accès d'essai. La documentation est publique et gratuite : nous préférons que vous la lisiez avant de payer.

Commencer gratuitement

Questions fréquentes

Puis-je tenir tout le registre depuis mon ERP sans ouvrir l'appli ? Oui pour enregistrer et lire. Non pour une transmission officielle, qui n'existe qu'en Espagne et y exige la session d'une personne habilitée. C'est voulu : cet acte a des conséquences légales et ne doit pas partir d'un traitement automatique.

Les données sont-elles à moi ? Oui. L'export complet est toujours gratuit, même après résiliation, et par l'API vous emportez exactement ce que vous voyez à l'écran, historiques et traces de modification compris.

Y a-t-il une limite d'appels ? Il n'y a pas de quota publié pour un usage normal par un ERP. Le test d'un webhook est limité à vingt fois par utilisateur et par IP toutes les dix minutes, pour que personne ne s'en serve pour générer du trafic.

Que se passe-t-il si vous changez l'API ? La version est dans l'URL. Tant que v1 est publiée, nous ne retirons pas de champ et ne changeons pas le sens de ceux qui existent ; le nouveau s'ajoute. S'il y a un jour une v2, les deux cohabiteront.

Le serveur MCP est-il sur npm ? Pas encore. Aujourd'hui il s'exécute depuis le dépôt ; sa publication n'est pas encore décidée. La configuration ci-dessus est celle qui marchera le jour où il sera publié.

Est-ce utile pour un conseiller avec beaucoup de clients ? C'est le rôle de advisor/portfolio : un appel vous dit quelles exploitations sont à jour et lesquelles ont des travaux incomplets, sans les ouvrir une par une.