API, webhooks en MCP: koppel je ERP aan de registratie

Als je het bedrijf runt met een ERP, een kostenoverzicht of het programma van je adviseur, heeft het geen zin elke bewerking twee keer in te typen. Dit is de documentatie om de registratie, de kosten en de stand van zaken van buitenaf op te halen, en om bewerkingen in te voeren vanuit het systeem dat je al gebruikt.

De basis is https://agrogps-api.fly.dev/api/v1. Hij draait in productie sinds 17 september 2026. Hij antwoordt altijd in JSON, ook bij fouten.

Twee manieren om je te identificeren

Een sleutel maak je één keer aan vanuit je sessie en hij wordt maar één keer getoond: daarna bewaren we alleen de hash. Ben je hem kwijt, dan trek je hem in en maak je een nieuwe. Een alleen-lezen-sleutel die probeert te schrijven krijgt 403 AUT_004. Sleutels kunnen geen andere sleutels of webhooks aanmaken of verwijderen: daarvoor is altijd de sessie van een persoon nodig.

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

Wat je kunt lezen

Met een schrijfsleutel kun je ook bewerkingen vastleggen met POST /sync/entries, met dezelfde body als de app. De synchronisatie werkt met since, zodat een nachtelijke taak alleen ophaalt wat veranderd is.

Gratis beginnen

Ondertekende webhooks

In plaats van elke vijf minuten te vragen, laten wij het weten. Je registreert een openbare https-URL en we sturen een melding als er iets gebeurt op een bedrijf waar je eigenaar of beheerder bent.

Elke levering bevat X-Agro-Event, X-Agro-Timestamp in Unix-seconden en X-Agro-Signature met de HMAC-SHA256 van "<timestamp>.<cuerpo>". Controleer beide: de handtekening, en dat de klok niet meer dan vijf minuten afwijkt.

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

De leveringsregels, duidelijk gezegd zodat er geen verrassingen zijn: één poging, zes seconden wachttijd en geen herhalingen. We volgen geen doorverwijzingen en weigeren privé-, link-local- en cloudmetadata-adressen, zowel bij het registreren van de URL als bij de DNS-resolutie van elke levering. Heeft je systeem garanties nodig, gebruik de webhook dan als seintje en GET /sync/entries met since als vangnet: het seintje is een service, de API is de waarheid.

MCP voor AI-assistenten

Dezelfde API is beschikbaar als MCP-server, het protocol waarmee assistenten zich aan tools koppelen. Zo kun je een assistent vragen welke bedrijven achterlopen, wat het seizoen gekost heeft of wat er voor een controle nog ontbreekt.

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

Beschikbare tools: list_farms, list_entries, entry_history, list_groups, group_overview, advisor_portfolio, advisor_pending en record_entry. De laatste werkt alleen met een schrijfsleutel, staat in de historie gemarkeerd als schrijven via de API en stuurt nooit iets naar de overheid.

Waarom je met de API niet kunt sjoemelen

Een API op een registratie met juridische waarde moet je recht in de ogen kunnen kijken. In Spanje staat het RD 1054/2022 toe het bedrijfsregister bij te houden met elk programma dat aan bijlage II voldoet en samenwerkt met het SIEX, en maakt het duidelijk dat de eigenaar verantwoordelijk is voor de juistheid, niet het programma. In Nederland en België geldt hetzelfde principe: de registratie is de verantwoordelijkheid van het bedrijf. Ons deel is de integriteit, en die zit in de code.

Fouten

Altijd {"code":"INT_NNN","message":"…"}, nooit een stacktrace. De meest voorkomende: AUT_003 ongeldige sleutel, AUT_004 alleen-lezen-sleutel, AUT_429 te veel pogingen, AUT_503 authenticatie niet beschikbaar (dat is niet hetzelfde als een verkeerde sleutel: probeer opnieuw), INT_003 URL die geen https is, INT_403 handeling waarvoor een sessie nodig is, INT_404 sleutel of webhook die niet van jou is.

Zo krijg je een sleutel

De API hoort bij de abonnementen voor bedrijven en adviseurs. Heb je al een account, dan maak je de sleutel aan in de app zelf. Wil je de koppeling eerst beoordelen voordat je een abonnement neemt, mail dan naar support@agrogps.eu welk systeem je wilt koppelen en we geven je testtoegang. De documentatie is openbaar en gratis: we hebben liever dat je hem leest voordat je betaalt.

Gratis beginnen

Veelgestelde vragen

Kan ik de hele registratie vanuit mijn ERP bijhouden zonder de app te openen? Ja, voor vastleggen en lezen. Niet voor officieel indienen, dat alleen in Spanje bestaat en daar de sessie van een bevoegde persoon vereist. Dat is een bewuste keuze: die handeling heeft juridische gevolgen en mag niet door een automatisch proces worden gestart.

Zijn de gegevens van mij? Ja. De volledige export is altijd gratis, ook als je opzegt, en via de API neem je precies mee wat je op het scherm ziet, inclusief historie en wijzigingsspoor.

Is er een limiet op aanroepen? Er is geen gepubliceerd quotum voor normaal gebruik door een ERP. Een webhook testen is beperkt tot twintig keer per gebruiker en IP per tien minuten, zodat niemand de functie gebruikt om verkeer te genereren.

Wat gebeurt er als jullie de API veranderen? De versie staat in de URL. Zolang v1 gepubliceerd is, halen we geen velden weg en veranderen we de betekenis van bestaande velden niet; nieuwe dingen komen erbij. Komt er ooit een v2, dan bestaan ze naast elkaar.

Staat de MCP-server op npm? Nog niet. Nu draait hij vanuit de repository; over publicatie is nog niet besloten. De configuratie hierboven is die welke werkt op de dag dat hij gepubliceerd wordt.

Werkt dit voor een adviseur met veel klanten? Daarvoor is advisor/portfolio: één aanroep vertelt je welke bedrijven bij zijn en welke onvolledige bewerkingen hebben, zonder ze een voor een te openen.