API, veebikonksud ja MCP: ühenda oma ERP päevikuga

Kui peate majapidamist ERP-süsteemis, kulude tabelis või nõustaja programmis, pole mõtet töid kaks korda sisestada. See on dokumentatsioon, millega saab päeviku, kulud ja nõuetele vastavuse seisu väljastpoolt kätte ning töid juba kasutatavast süsteemist sisse kanda.

Alus on https://agrogps-api.fly.dev/api/v1. See on töös alates 17. septembrist 2026. Vastab alati JSON-is, ka vigade korral.

Kaks viisi end tuvastada

Võti luuakse üks kord sinu sessioonist ja seda näidatakse ainult üks kord: edaspidi hoiame alles vaid selle räsi. Kui see kaob, tühistatakse see ja luuakse uus. Ainult lugemisõigusega võti, mis proovib kirjutada, saab vastuseks 403 AUT_004. Võtmed ei saa luua ega kustutada teisi võtmeid ega veebikonkse: see käib alati inimese sessiooniga.

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

Mida saab lugeda

Kirjutamisõigusega võtmega saad lisaks töid registreerida päringuga POST /sync/entries, sama kehaga, mida kasutab rakendus. Sünkroonimine käib since järgi, nii et öine protsess toob ainult muutunu.

Alusta tasuta

Allkirjastatud veebikonksud

Selle asemel, et iga viie minuti järel küsida, anname teada meie. Registreerid avaliku https URL-i ja saadame teate, kui midagi juhtub majapidamises, kus oled omanik või juhataja.

Iga saadetis sisaldab päiseid X-Agro-Event, X-Agro-Timestamp Unixi sekundites ja X-Agro-Signature, mis on HMAC-SHA256 väärtusest "<timestamp>.<cuerpo>". Kontrolli mõlemat: allkirja ja seda, et kell poleks rohkem kui viis minutit kõrvale läinud.

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

Kohaletoimetamise reeglid, selgelt öeldud, et üllatusi ei tuleks: üks katse, kuus sekundit ootamist ja kordusi ei ole. Me ei järgi ümbersuunamisi ning lükkame tagasi privaatsed, lingikohalikud ja pilve metaandmete aadressid nii URL-i registreerimisel kui ka iga saadetise DNS-i lahendamisel. Kui su süsteem vajab garantiisid, kasuta veebikonksu teatena ja päringut GET /sync/entries koos since-ga turvavõrguna: teade on viisakus, API on tõde.

MCP tehisintellekti assistentidele

Sama API on avatud ka MCP-serverina, protokollina, mida assistendid kasutavad tööriistadega ühendumiseks. Nii saab assistendilt küsida näiteks, millised majapidamised on maas, kui palju hooaeg maksma läks või mis on enne kontrolli veel täitmata.

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

Saadaolevad tööriistad: list_farms, list_entries, entry_history, list_groups, group_overview, advisor_portfolio, advisor_pending ja record_entry. Viimane töötab ainult kirjutamisõigusega võtmega, jääb ajalukku API kaudu kirjutatuna ega saada kunagi midagi ametiasutustele.

Miks API ei sobi sohki tegemiseks

Õigusliku väärtusega registri API peab taluma otsevaadet. Hispaanias lubab RD 1054/2022 pidada päevikut mis tahes infosüsteemis, mis vastab II lisa nõuetele ja on koostalitlusvõimeline SIEX-iga, ning ütleb selgelt, et andmete tõesuse eest vastutab omanik, mitte programm. Meie osa on terviklikkus ja see on koodi sisse ehitatud, igas riigis.

Vead

Alati {"code":"INT_NNN","message":"…"}, mitte kunagi jälg. Kõige sagedamini näed: AUT_003 vigane võti, AUT_004 ainult lugemisõigusega võti, AUT_429 liiga palju katseid, AUT_503 autentimine pole saadaval (see pole sama mis vale võti: proovi uuesti), INT_003 URL, mis pole https, INT_403 toiming, mis nõuab sessiooni, INT_404 võti või veebikonks, mis pole sinu oma.

Kuidas võtit saada

API kuulub ettevõtte ja nõustamise pakettide juurde. Kui sul on juba konto, loob võtme rakendusest endast. Kui kaalud liidestust enne lepingu sõlmimist, kirjuta aadressile support@agrogps.eu, milline süsteem ühendada tahad, ja anname testjuurdepääsu. Dokumentatsioon on avalik ja tasuta: eelistame, et vaataksid selle enne maksmist üle.

Alusta tasuta

Korduma kippuvad küsimused

Kas saan pidada kogu päevikut oma ERP-st rakendust avamata? Jah, registreerimiseks ja lugemiseks. Ametlik saatmine on olemas ainult Hispaanias ja nõuab saatmisõigusega inimese sessiooni. See on teadlik otsus: sellel toimingul on õiguslikud tagajärjed ja seda ei tohi käivitada automaatne protsess.

Kas andmed on minu omad? Jah. Täielik eksport on alati tasuta, ka pärast lahkumist, ja API kaudu saad täpselt sama, mida näed ekraanil, sh ajaloo ja muudatuste jälje.

Kas päringutel on piirang? ERP tavakasutusele avaldatud kvooti ei ole. Veebikonksu proovimine on piiratud kahekümne korraga kasutaja ja IP kohta iga kümne minuti jooksul, et keegi ei kasutaks funktsiooni liikluse tekitajana.

Mis juhtub, kui API-t muudate? Versioon on URL-is. Kuni v1 on avaldatud, ei eemalda me välju ega muuda olemasolevate tähendust; uus lisandub. Kui kunagi tuleb v2, elaksid need kõrvuti.

Kas MCP-server on npm-is? Veel mitte. Praegu käivitatakse see repositooriumist; avaldamise üle pole veel otsustatud. Ülal olev seadistus on see, mis toimib avaldamise päeval.

Kas see sobib paljude klientidega nõustajale? Selleks on advisor/portfolio: üks päring ütleb, millised majapidamised on ajakohased ja millistel on pooleli töid, ilma et peaks ükshaaval sisse minema.