API, webhooks og MCP: koble ERP-en din til journalen

Hvis du driver gården med et ERP-system, et kostnadsark eller rådgiverens program, gir det ingen mening å taste inn arbeidene to ganger. Dette er dokumentasjonen for å hente ut journalen, kostnadene og etterlevelsesstatusen utenfra, og for å legge inn arbeider fra systemet du allerede bruker.

Basen er https://agrogps-api.fly.dev/api/v1. Den har vært i produksjon siden 17. september 2026. Den svarer alltid med JSON, også ved feil.

To måter å identifisere seg på

Nøkkelen opprettes én gang fra økten din og vises bare én gang: etterpå lagrer vi bare hashen. Mister du den, tilbakekalles den og du lager en ny. En lesenøkkel som prøver å skrive, får 403 AUT_004. Nøkler kan ikke opprette eller slette andre nøkler eller webhooks: det skjer alltid med en persons økt.

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

Hva du kan lese

Med en skrivenøkkel kan du i tillegg registrere arbeider med POST /sync/entries, med samme innhold som appen bruker. Synkroniseringen går etter since, så en nattlig jobb henter bare det som er endret.

Kom i gang gratis

Signerte webhooks

I stedet for å spørre hvert femte minutt, sier vi fra. Du registrerer en offentlig https-URL, og vi sender et varsel når noe skjer på en gård der du er eier eller driftsleder.

Hver levering har X-Agro-Event, X-Agro-Timestamp i Unix-sekunder og X-Agro-Signature med HMAC-SHA256 av "<timestamp>.<cuerpo>". Sjekk begge deler: signaturen og at klokken ikke har gått mer enn fem minutter feil.

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

Leveringsregler, sagt tydelig så du ikke blir overrasket: ett forsøk, seks sekunders venting og ingen nye forsøk. Vi følger ikke omdirigeringer og avviser private adresser, lenkelokale adresser og skyens metadataadresser, både når URL-en registreres og når DNS slås opp for hver levering. Trenger systemet ditt garantier, bruk webhooken som varsel og GET /sync/entries med since som sikkerhetsnett: varselet er høflighet, API-et er sannheten.

MCP for KI-assistenter

Det samme API-et er tilgjengelig som MCP-server, protokollen assistenter bruker for å koble seg til verktøy. Da kan du spørre en assistent om for eksempel hvilke gårder som ligger etter, hva sesongen har kostet eller hva som mangler før en kontroll.

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

Tilgjengelige verktøy: list_farms, list_entries, entry_history, list_groups, group_overview, advisor_portfolio, advisor_pending og record_entry. Det siste fungerer bare med skrivenøkkel, blir merket i historikken som skrevet via API og sender aldri noe til myndighetene.

Hvorfor API-et ikke egner seg til juks

Et API over et register med rettslig verdi må tåle å bli sett rett i øynene. I Spania tillater RD 1054/2022 at journalen føres i et hvilket som helst datasystem som oppfyller kravene i vedlegg II og er interoperabelt med SIEX, og slår fast at det er eieren, ikke programmet, som står ansvarlig for at opplysningene er riktige. Vår del er integriteten, og den er bygget inn i koden, i alle land.

Feil

Alltid {"code":"INT_NNN","message":"…"}, aldri en stakksporing. De du oftest ser: AUT_003 ugyldig nøkkel, AUT_004 lesenøkkel, AUT_429 for mange forsøk, AUT_503 autentisering utilgjengelig (ikke det samme som feil nøkkel: prøv igjen), INT_003 URL som ikke er https, INT_403 handling som krever økt, INT_404 nøkkel eller webhook som ikke er din.

Slik får du en nøkkel

API-et følger med bedrifts- og rådgiverplanene. Har du allerede konto, lager du nøkkelen i selve appen. Vurderer du integrasjonen før du tegner avtale, skriv til support@agrogps.eu om hvilket system du vil koble til, så gir vi deg testtilgang. Dokumentasjonen er offentlig og gratis: vi vil heller at du ser på den før du betaler.

Kom i gang gratis

Vanlige spørsmål

Kan jeg føre hele journalen fra ERP-en uten å åpne appen? Ja, for å registrere og lese. Offisiell innsending finnes bare i Spania og krever økten til en person med tillatelse til å sende. Det er et bevisst valg: den handlingen har rettslige følger og skal ikke utløses av en automatisk prosess.

Er dataene mine? Ja. Full eksport er alltid gratis, også hvis du avslutter, og via API-et får du nøyaktig det samme som du ser på skjermen, inkludert historikk og endringsspor.

Er det grense for antall kall? Det er ingen publisert kvote for vanlig ERP-bruk. Testing av en webhook er begrenset til tjue ganger per bruker og IP hvert tiende minutt, så ingen bruker funksjonen til å generere trafikk.

Hva skjer hvis dere endrer API-et? Versjonen står i URL-en. Så lenge v1 er publisert, fjerner vi ikke felt og endrer ikke betydningen av dem som finnes; nytt legges til. Kommer det en gang en v2, vil de leve side om side.

Ligger MCP-serveren på npm? Ikke ennå. I dag kjøres den fra kodelageret; publisering er ikke bestemt. Oppsettet over er det som vil fungere den dagen den publiseres.

Passer dette for en rådgiver med mange kunder? Det er det advisor/portfolio er til for: ett kall forteller hvilke gårder som er à jour og hvilke som har ufullstendige arbeider, uten å gå inn i hver enkelt.