API, webhookit ja MCP: liitä järjestelmäsi kirjanpitoon
Jos hoidat tilaa toiminnanohjausjärjestelmällä, kustannustaulukolla tai neuvojasi ohjelmalla, töitä ei kannata kirjata kahteen kertaan. Tämä on dokumentaatio, jolla haet kirjanpidon, kustannukset ja vaatimustenmukaisuuden tilan ulkopuolelta, ja kirjaat töitä siitä järjestelmästä, jota jo käytät.
Perusosoite on https://agrogps-api.fly.dev/api/v1. Se on ollut tuotannossa 17. syyskuuta 2026 lähtien. Se vastaa aina JSON-muodossa, myös virheissä.
Kaksi tapaa tunnistautua
| Kuka kutsuu | Otsake | Mitä se voi tehdä |
|---|---|---|
| Sovellus tai verkkosivu | Authorization: Bearer <sesión> | Kaiken, myös luoda ja perua avaimia |
| Ulkoinen järjestelmä | X-API-Key: agk_… | Lukea, tai lukea ja kirjoittaa avaimen laajuuden mukaan |
Avain luodaan kerran omasta istunnostasi ja näytetään vain kerran: sen jälkeen tallennamme vain sen tiivisteen. Jos kadotat sen, perut sen ja luot uuden. Lukuavain, joka yrittää kirjoittaa, saa vastauksen 403 AUT_004. Avaimet eivät voi luoda tai poistaa muita avaimia tai webhookeja: se vaatii aina ihmisen istunnon.
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"}'Mitä voit lukea
| Endpoint | Palauttaa |
|---|---|
GET /farms | Avaimen haltijan tilat roolin kanssa |
GET /sync/entries?farm_id=…&since=0 | Kaikki työt kaikkine kirjanpitokenttineen, sivutettuna next-kentällä |
GET /groups/:id/overview | Ryhmän näkymä: työt, kustannus, tulot, kate, käsitellyt hehtaarit ja viljelykasvi tiloittain |
GET /advisor/portfolio | Neuvojan salkku: mitkä tilat ovat ajan tasalla ja mitkä eivät |
GET /advisor/farms/:id/pending | Täyttämättömät kentät työ kerrallaan |
GET /notebook/entries/:id/history | Kuka muutti mitä ja milloin työssä |
Kirjoitusavaimella voit lisäksi kirjata töitä kutsulla POST /sync/entries, samalla sisällöllä kuin sovellus. Synkronointi kulkee since-arvon mukaan, joten yöajo hakee vain sen, mikä on muuttunut.
Allekirjoitetut webhookit
Sen sijaan, että kysyisit viiden minuutin välein, me ilmoitamme. Rekisteröit julkisen https-osoitteen, ja lähetämme ilmoituksen, kun jotain tapahtuu tilalla, jonka omistaja tai vastaava olet.
| Tapahtuma | Milloin se laukeaa |
|---|---|
entry.pushed | Töitä synkronoidaan ja vähintään yksi hyväksytään |
entry.reviewed | Neuvoja tai omistaja hyväksyy tai merkitsee työn |
webhook.test | Painat testiä |
Jokaisessa toimituksessa on X-Agro-Event, X-Agro-Timestamp Unix-sekunteina ja X-Agro-Signature, jossa on HMAC-SHA256 arvosta "<timestamp>.<cuerpo>". Tarkista molemmat: allekirjoitus ja se, ettei kello heitä yli viittä minuuttia.
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"])Toimitussäännöt selvästi sanottuna, ettei tule yllätyksiä: yksi yritys, kuuden sekunnin odotus ja ei uusintayrityksiä. Emme seuraa uudelleenohjauksia ja hylkäämme yksityiset osoitteet, linkkipaikalliset osoitteet ja pilvipalvelujen metatieto-osoitteet sekä osoitetta rekisteröitäessä että jokaisen toimituksen DNS-haussa. Jos järjestelmäsi tarvitsee takuita, käytä webhookia ilmoituksena ja kutsua GET /sync/entries arvolla since turvaverkkona: ilmoitus on kohteliaisuus, API on totuus.
MCP tekoälyavustajille
Sama API on tarjolla MCP-palvelimena, protokollana, jolla avustajat liittyvät työkaluihin. Voit kysyä avustajalta esimerkiksi, mitkä tilat ovat myöhässä, paljonko kausi on maksanut tai mitä puuttuu ennen tarkastusta.
{ "mcpServers": { "agro-gps": {
"command": "npx", "args": ["-y", "agro-gps-mcp"],
"env": { "AGROGPS_API_KEY": "agk_…" } } } }Käytettävissä olevat työkalut: list_farms, list_entries, entry_history, list_groups, group_overview, advisor_portfolio, advisor_pending ja record_entry. Viimeinen toimii vain kirjoitusavaimella, merkitään historiaan API:n kautta kirjoitetuksi eikä koskaan lähetä mitään viranomaisille.
Miksi API:lla ei voi huijata
Oikeudellisesti merkittävän kirjanpidon päällä olevan API:n on kestettävä tarkka katse. Espanjassa RD 1054/2022 sallii kirjanpidon missä tahansa tietojärjestelmässä, joka täyttää liitteen II vaatimukset ja vaihtaa tietoja SIEX-järjestelmän kanssa, ja tekee selväksi, että tietojen oikeellisuudesta vastaa tilan haltija eikä ohjelma. Meidän osuutemme on eheys, ja se on rakennettu koodiin kaikissa maissa.
| Mitä joku voisi yrittää | Mitä API tekee |
|---|---|
| Kirjata tänään kuukausia vanhalla päivämäärällä | Jokainen työ tallentaa ilmoitetun päivämäärän ja todellisen palvelimelle saapumisajan, ja historia kirjaa viivepäivät |
| Kirjata tulevalla päivämäärällä | Hylätään, jos se on yli 24 tuntia tästä hetkestä eteenpäin |
| Kirjoittaa ilman ihmistä takana | Jokaisella työllä on tekijä, ja avaimella tulleet merkitään avaimen etuliitteellä |
| Poistaa se, mikä on tiellä | Mitään ei poisteta: poistot ovat päivättyjä hautakiviä |
| Lähettää viranomaisille automaattisesti | Virallinen lähetys vaatii luvan saaneen henkilön istunnon: avain saa vastauksen 403 SIE_403 |
Virallinen lähetys on tänään olemassa vain Espanjassa, ja siellä se odottaa hyväksyntää alue kerrallaan. Suomessa ei ole minne lähettää: API:n kautta luet ja kirjoitat kirjanpitoa.
Virheet
Aina {"code":"INT_NNN","message":"…"}, ei koskaan pinojälkeä. Yleisimmät: AUT_003 virheellinen avain, AUT_004 lukuavain, AUT_429 liian monta yritystä, AUT_503 tunnistautuminen ei käytettävissä (eri asia kuin väärä avain: yritä uudelleen), INT_003 osoite, joka ei ole https, INT_403 toiminto, joka vaatii istunnon, INT_404 avain tai webhook, joka ei ole sinun.
Näin saat avaimen
API kuuluu yritys- ja neuvojapaketteihin. Jos sinulla on jo tili, luot avaimen sovelluksessa. Jos harkitset integraatiota ennen ostoa, kirjoita osoitteeseen support@agrogps.eu ja kerro, minkä järjestelmän haluat liittää, niin annamme testipääsyn. Dokumentaatio on julkinen ja maksuton: haluamme mieluummin, että luet sen ennen kuin maksat.
Usein kysyttyä
Voinko pitää koko kirjanpidon järjestelmästäni avaamatta sovellusta? Kyllä kirjaamisen ja lukemisen osalta. Ei virallisen viranomaislähetyksen osalta, joka vaatii lähetysluvan saaneen henkilön istunnon. Se on tietoinen päätös: teolla on oikeudellisia seurauksia, eikä automaattinen prosessi saa laukaista sitä.
Ovatko tiedot minun? Kyllä. Täydellinen vienti on aina maksuton, myös jos lopetat, ja API:n kautta saat täsmälleen saman kuin näet näytöllä, historia ja muutosjälki mukaan lukien.
Onko kutsuille rajaa? Tavalliselle järjestelmäkäytölle ei ole julkaistua kiintiötä. Webhookin testaus on rajattu kahteenkymmeneen kertaan käyttäjää ja IP-osoitetta kohden kymmenessä minuutissa, jottei toimintoa käytetä liikenteen tuottamiseen.
Mitä jos muutatte API:a? Versio on osoitteessa. Niin kauan kuin v1 on julkaistuna, emme poista kenttiä emmekä muuta olemassa olevien merkitystä; uutta lisätään. Jos joskus tulee v2, ne toimivat rinnakkain.
Onko MCP-palvelin npm:ssä? Ei vielä. Tänään se ajetaan koodivarastosta; julkaisusta ei ole vielä päätetty. Yllä oleva määritys on se, joka toimii julkaisupäivänä.
Sopiiko tämä neuvojalle, jolla on paljon asiakkaita? Sitä varten on advisor/portfolio: yksi kutsu kertoo, mitkä tilat ovat ajan tasalla ja missä on keskeneräisiä töitä, ilman että avaat tilat yksitellen.