APIa, webhookak eta MCP: konektatu zure ERPa koadernora

Ustiategia ERP batekin, kostu-orri batekin edo zure aholkularitzaren programarekin eramaten baduzu, ez du zentzurik lanak bi aldiz idazteak. Hau da koadernoa, kostuak eta betetze-egoera kanpotik ateratzeko eta dagoeneko erabiltzen duzun sistematik lanak sartzeko dokumentazioa.

Oinarria https://agrogps-api.fly.dev/api/v1 da. 2026ko irailaren 17tik dago ekoizpenean. Beti JSONez erantzuten du, baita erroreetan ere.

Identifikatzeko bi modu

Gakoa behin sortzen da zure saiotik eta behin bakarrik erakusten da: gero haren hash-a baino ez dugu gordetzen. Galtzen baduzu, baliogabetu eta beste bat sortzen da. Irakurtzeko soilik den gako batek idazten saiatzen bada 403 AUT_004 jasotzen du. Gakoek ezin dute beste gako edo webhookik sortu edo ezabatu: hori beti pertsona baten saioarekin egiten da.

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

Zer irakur dezakezu

Idazteko gako batekin, gainera, lanak erregistra ditzakezu POST /sync/entries bidez, aplikazioak erabiltzen duen gorputz berarekin. Sinkronizazioa since bidez doa, beraz gaueko prozesu batek aldatu dena baino ez du ekartzen.

Hasi doan

Webhook sinatuak

Bost minuturo galdetu beharrean, guk abisatzen dizugu. https URL publiko bat ematen duzu alta, eta abisu bat bidaltzen dugu zu jabe edo arduradun zaren ustiategi batean zerbait gertatzen denean.

Bidalketa bakoitzak X-Agro-Event, X-Agro-Timestamp Unix segundotan eta X-Agro-Signature darama, "<timestamp>.<cuerpo>"-ren HMAC-SHA256arekin. Egiaztatu bi gauzak: sinadura eta erlojua bost minutu baino gehiago desbideratu ez dela.

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

Bidalketa-arauak, argi esanda ustekaberik izan ez dezazun: saiakera bat, sei segundoko itxaronaldia eta errepikapenik gabe. Ez ditugu birbideratzeak jarraitzen, eta helbide pribatuak, lotura lokalekoak eta hodeiko metadatuenak baztertzen ditugu, bai URLa alta ematean bai bidalketa bakoitzeko DNSa ebaztean. Zure sistemak bermeak behar baditu, erabili webhooka abisu gisa eta GET /sync/entries since-rekin segurtasun-sare gisa: abisua adeitasuna da, APIa egia.

MCP AA laguntzaileentzat

API bera MCP zerbitzari gisa dago eskuragarri, laguntzaileek tresnetara konektatzeko erabiltzen duten protokoloa. Laguntzaile bati galdetzeko balio du, adibidez, zein ustiategik daramaten atzerapena, zenbat kostatu den kanpaina edo zer falta den betetzeko ikuskapen baten aurretik.

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

Tresna erabilgarriak: list_farms, list_entries, entry_history, list_groups, group_overview, advisor_portfolio, advisor_pending eta record_entry. Azkenak idazteko gakoarekin bakarrik funtzionatzen du, historian API bidezko idazketa gisa markatuta geratzen da eta ez dio inoiz ezer bidaltzen administrazioari.

Zergatik ez du APIak tranparik egiteko balio

Balio juridikoa duen erregistro baten gaineko APIak aurrez aurre begiratzeko modukoa izan behar du. RD 1054/2022 dekretuak aukera ematen du koadernoa II. eranskineko baldintzak betetzen dituen eta SIEXekin elkarreragingarria den edozein sistema informatikorekin eramateko, eta argi uzten du datuen egiazkotasunaren arduraduna titularra dela, ez programa. Gure zatia osotasuna da, eta kodean dago jarrita.

Erroreak

Beti {"code":"INT_NNN","message":"…"}, inoiz ez arrasto bat. Gehien ikusiko dituzunak: AUT_003 gako baliogabea, AUT_004 irakurtzeko soilik den gakoa, AUT_429 saiakera gehiegi, AUT_503 autentifikazioa ez dago erabilgarri (ez da gako txarra bezala: saiatu berriro), INT_003 https ez den URLa, INT_403 saioa eskatzen duen eragiketa, INT_404 zurea ez den gakoa edo webhooka.

Nola lortzen da gako bat

APIa enpresa- eta aholkularitza-planekin dator. Dagoeneko kontua baduzu, gakoa aplikaziotik bertatik sortzen da. Kontratatu aurretik integrazioa baloratzen ari bazara, idatzi support@agrogps.eu helbidera zein sistema konektatu nahi duzun kontatuz, eta proba-sarbidea emango dizugu. Dokumentazioa publikoa eta doakoa da: nahiago dugu ordaindu aurretik begiratzea.

Hasi doan

Ohiko galderak

Koaderno osoa nire ERPtik eraman dezaket aplikazioa ireki gabe? Bai, erregistratzeko eta irakurtzeko. Ez administraziora bidalketa ofizialerako, bidaltzeko baimena duen pertsona baten saioa eskatzen baitu. Nahita hartutako erabakia da: ekintza horrek ondorio juridikoak ditu eta ez luke prozesu automatiko batek abiarazi behar.

Datuak nireak dira? Bai. Esportazio osoa doakoa da beti, baita baja ematen baduzu ere, eta APIaren bidez pantailan ikusten duzun gauza bera eramaten duzu, historikoak eta aldaketen arrastoa barne.

Deien mugarik ba al dago? Ez dago ERP baten ohiko erabilerarako argitaratutako kuotarik. Webhook bat probatzea bai dago mugatuta, hogei aldiz erabiltzaile eta IP bakoitzeko hamar minuturo, inork funtzioa trafiko-igorle gisa erabil ez dezan.

Zer gertatzen da APIa aldatzen baduzue? Bertsioa URLan doa. v1 argitaratuta dagoen bitartean, ez dugu eremurik kentzen ezta daudenen esanahia aldatzen ere; berria gehitu egiten da. Egunen batean v2 bat balego, elkarrekin biziko lirateke.

MCP zerbitzaria npm-n dago? Oraindik ez. Gaur biltegitik exekutatzen da; argitaratzea erabakitzeko dago. Goiko konfigurazioa da argitaratzen den egunean funtzionatuko duena.

Balio al du bezero asko dituen aholkulari batentzat? Horretarako dago advisor/portfolio: dei batek esaten dizu zein ustiategi dauden egunean eta zeinek dituzten lan osatugabeak, banan-banan sartu gabe.