API, Webhooks und MCP: Ihr ERP mit der Schlagkartei verbinden

Wenn Sie den Betrieb mit einem ERP, einer Kostentabelle oder dem Programm Ihres Beraters führen, ergibt es keinen Sinn, jede Maßnahme zweimal einzutippen. Hier ist die Dokumentation, um Schlagkartei, Kosten und Stand der Aufzeichnungen von außen abzurufen und Maßnahmen aus dem System einzuspielen, das Sie schon nutzen.

Die Basis ist https://agrogps-api.fly.dev/api/v1. Sie ist seit dem 17. September 2026 in Produktion. Sie antwortet immer mit JSON, auch bei Fehlern.

Zwei Arten, sich anzumelden

Wer ruft auf	Header	Was er darf
Die App oder das Web	`Authorization: Bearer <sesión>`	Alles, auch Schlüssel anlegen und widerrufen
Ein externes System	`X-API-Key: agk_…`	Lesen, oder lesen und schreiben, je nach Geltungsbereich des Schlüssels

Ein Schlüssel wird einmal aus Ihrer Sitzung angelegt und nur ein einziges Mal angezeigt: Danach speichern wir nur seinen Hash. Wenn Sie ihn verlieren, widerrufen Sie ihn und legen einen neuen an. Ein Nur-Lese-Schlüssel, der schreiben will, erhält 403 AUT_004. Schlüssel können weder andere Schlüssel noch Webhooks anlegen oder löschen: Dafür braucht es immer die Sitzung einer Person.

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"}'

Was Sie lesen können

Endpoint	Liefert
`GET /farms`	Die Betriebe des Schlüsselinhabers, mit seiner Rolle
`GET /sync/entries?farm_id=…&since=0`	Alle Maßnahmen mit allen Feldern, seitenweise über `next`
`GET /groups/:id/overview`	Übersicht der Gruppe: Maßnahmen, Kosten, Erlöse, Marge, behandelte Hektar und Kultur je Betrieb
`GET /advisor/portfolio`	Die Betriebe des Beraters: welche auf dem Laufenden sind und welche nicht
`GET /advisor/farms/:id/pending`	Die fehlenden Angaben, Maßnahme für Maßnahme
`GET /notebook/entries/:id/history`	Wer was wann an einer Maßnahme geändert hat

Mit einem Schreibschlüssel können Sie außerdem Maßnahmen mit POST /sync/entries erfassen, mit demselben Body, den die App verwendet. Die Synchronisation läuft über since, sodass ein nächtlicher Abgleich nur holt, was sich geändert hat.

Kostenlos starten

Signierte Webhooks

Statt alle fünf Minuten nachzufragen, sagen wir Ihnen Bescheid. Sie hinterlegen eine öffentliche https-URL, und wir schicken eine Nachricht, wenn in einem Betrieb, in dem Sie Inhaber oder Verwalter sind, etwas passiert.

Ereignis	Wann es ausgelöst wird
`entry.pushed`	Maßnahmen werden synchronisiert und mindestens eine wird angenommen
`entry.reviewed`	Ein Berater oder der Inhaber gibt eine Maßnahme frei oder markiert sie
`webhook.test`	Sie tippen auf Testen

Jede Zustellung enthält X-Agro-Event, X-Agro-Timestamp in Unix-Sekunden und X-Agro-Signature mit dem HMAC-SHA256 von "<timestamp>.<cuerpo>". Prüfen Sie beides: die Signatur und dass die Uhr nicht mehr als fünf Minuten abweicht.

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"])

Die Zustellregeln, offen gesagt, damit es keine Überraschungen gibt: ein Versuch, sechs Sekunden Wartezeit und keine Wiederholungen. Wir folgen keinen Weiterleitungen und lehnen private, link-lokale und Cloud-Metadaten-Adressen ab, sowohl beim Hinterlegen der URL als auch bei der DNS-Auflösung jeder Zustellung. Wenn Ihr System Garantien braucht, nutzen Sie den Webhook als Hinweis und GET /sync/entries mit since als Sicherheitsnetz: Der Hinweis ist Service, die API ist die Wahrheit.

MCP für KI-Assistenten

Dieselbe API steht als MCP-Server bereit, dem Protokoll, mit dem Assistenten sich an Werkzeuge anbinden. Damit können Sie einen Assistenten fragen, welche Betriebe im Rückstand sind, was das Anbaujahr gekostet hat oder was vor einer Kontrolle noch fehlt.

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

Verfügbare Werkzeuge: list_farms, list_entries, entry_history, list_groups, group_overview, advisor_portfolio, advisor_pending und record_entry. Das letzte funktioniert nur mit Schreibschlüssel, wird im Verlauf als Schreibvorgang über die API markiert und schickt nie etwas an eine Behörde.

Warum man mit der API nicht schummeln kann

Eine API auf einer Aufzeichnung mit rechtlichem Wert muss einer Prüfung standhalten. In Spanien erlaubt das RD 1054/2022, das Betriebsheft mit jedem Programm zu führen, das die Anforderungen des Anhangs II erfüllt und mit dem SIEX zusammenarbeitet, und stellt klar, dass für die Richtigkeit der Inhaber verantwortlich ist, nicht das Programm. Für Deutschland und Österreich gilt dasselbe Prinzip: Die Aufzeichnung verantwortet der Betrieb. Unser Teil ist die Integrität, und die steckt im Code.

Was jemand versuchen könnte	Was die API tut
Heute mit einem Datum von vor Monaten erfassen	Jede Maßnahme speichert das angegebene Datum und den echten Eingang auf dem Server, und der Verlauf vermerkt die Tage Verspätung
Mit einem Datum in der Zukunft erfassen	Wird abgelehnt, wenn es mehr als 24 Stunden voraus liegt
Ohne eine Person dahinter schreiben	Jede Maßnahme hat einen Urheber, und was über einen Schlüssel kommt, ist mit dessen Präfix markiert
Löschen, was stört	Nichts wird gelöscht: Löschungen sind datierte Grabsteine
Automatisch an die Behörde melden	Eine amtliche Meldung gibt es nur in Spanien, und dort steht die Zulassung je Region noch aus. Sie verlangt die Sitzung einer berechtigten Person: Ein Schlüssel erhält `403 SIE_403`. In Deutschland und Österreich gibt es nichts zu melden

Fehler

Immer {"code":"INT_NNN","message":"…"}, nie ein Stacktrace. Die häufigsten: AUT_003 ungültiger Schlüssel, AUT_004 Nur-Lese-Schlüssel, AUT_429 zu viele Versuche, AUT_503 Anmeldung nicht verfügbar (das ist nicht dasselbe wie ein falscher Schlüssel: erneut versuchen), INT_003 URL ohne https, INT_403 Vorgang, der eine Sitzung verlangt, INT_404 Schlüssel oder Webhook, der Ihnen nicht gehört.

So bekommen Sie einen Schlüssel

Die API gehört zu den Tarifen für Unternehmen und Beratung. Wenn Sie schon ein Konto haben, legen Sie den Schlüssel in der App an. Wenn Sie die Anbindung vor dem Abschluss prüfen wollen, schreiben Sie an support@agrogps.eu, welches System Sie verbinden möchten, und wir geben Ihnen einen Testzugang. Die Dokumentation ist öffentlich und kostenlos: Wir möchten lieber, dass Sie sie vor dem Bezahlen lesen.

Kostenlos starten

Häufige Fragen

Kann ich die ganze Schlagkartei aus meinem ERP führen, ohne die App zu öffnen? Zum Erfassen und Lesen ja. Für eine amtliche Meldung nein, die es ohnehin nur in Spanien gibt und die dort die Sitzung einer berechtigten Person verlangt. Das ist Absicht: Dieser Schritt hat rechtliche Folgen und soll nicht von einem automatischen Prozess ausgelöst werden.

Gehören die Daten mir? Ja. Der vollständige Export ist immer kostenlos, auch nach einer Kündigung, und über die API nehmen Sie genau das mit, was Sie auf dem Bildschirm sehen, samt Verlauf und Änderungsspur.

Gibt es ein Limit für Aufrufe? Für die normale Nutzung durch ein ERP gibt es keine veröffentlichte Quote. Das Testen eines Webhooks ist auf zwanzigmal pro Nutzer und IP alle zehn Minuten begrenzt, damit niemand die Funktion als Traffic-Quelle missbraucht.

Was passiert, wenn Sie die API ändern? Die Version steht in der URL. Solange v1 veröffentlicht ist, entfernen wir keine Felder und ändern nicht die Bedeutung der vorhandenen; Neues kommt hinzu. Sollte es einmal eine v2 geben, liefen beide nebeneinander.

Ist der MCP-Server auf npm? Noch nicht. Heute läuft er aus dem Repository; die Veröffentlichung ist noch nicht entschieden. Die Konfiguration oben ist die, die am Tag der Veröffentlichung funktionieren wird.

Taugt das für einen Berater mit vielen Kunden? Dafür gibt es advisor/portfolio: Ein Aufruf zeigt, welche Betriebe auf dem Laufenden sind und welche unvollständige Maßnahmen haben, ohne jeden einzeln zu öffnen.