API, webhookuri și MCP: conectează-ți ERP-ul la registru
Dacă ții exploatația într-un ERP, într-un tabel de costuri sau în programul consultantului tău, nu are sens să scrii lucrările de două ori. Aceasta este documentația pentru a scoate din afară registrul, costurile și stadiul conformității, și pentru a introduce lucrări din sistemul pe care îl folosești deja.
Adresa de bază este https://agrogps-api.fly.dev/api/v1. Este în producție din 17 septembrie 2026. Răspunde mereu în JSON, și la erori.
Două moduri de identificare
| Cine apelează | Antet | Ce poate face |
|---|---|---|
| Aplicația sau site-ul | Authorization: Bearer <sesión> | Tot, inclusiv să creeze și să revoce chei |
| Un sistem extern | X-API-Key: agk_… | Citire, sau citire și scriere, după domeniul cheii |
Cheia se creează o singură dată din sesiunea ta și se afișează o singură dată: după aceea păstrăm doar hash-ul ei. Dacă o pierzi, o revoci și creezi alta. O cheie doar pentru citire care încearcă să scrie primește 403 AUT_004. Cheile nu pot crea și nici șterge alte chei sau webhookuri: asta cere întotdeauna sesiunea unei persoane.
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"}'Ce poți citi
| Endpoint | Ce întoarce |
|---|---|
GET /farms | Exploatațiile titularului cheii, cu rolul său |
GET /sync/entries?farm_id=…&since=0 | Toate lucrările cu toate câmpurile registrului, paginate prin next |
GET /groups/:id/overview | Panoul grupului: lucrări, cost, venituri, marjă, hectare tratate și cultură pe exploatație |
GET /advisor/portfolio | Portofoliul consultantului: ce exploatații sunt la zi și care nu |
GET /advisor/farms/:id/pending | Câmpurile rămase de completat, lucrare cu lucrare |
GET /notebook/entries/:id/history | Cine a schimbat ce și când într-o lucrare |
Cu o cheie de scriere poți și înregistra lucrări prin POST /sync/entries, cu același corp pe care îl folosește aplicația. Sincronizarea merge după since, așa că un proces de noapte aduce doar ce s-a schimbat.
Webhookuri semnate
În loc să întrebi la fiecare cinci minute, te anunțăm noi. Înregistrezi o adresă publică https și trimitem un aviz când se întâmplă ceva într-o exploatație unde ești proprietar sau responsabil.
| Eveniment | Când se declanșează |
|---|---|
entry.pushed | Se sincronizează lucrări și cel puțin una este acceptată |
entry.reviewed | Un consultant sau titularul aprobă ori marchează o lucrare |
webhook.test | Apeși pe test |
Fiecare livrare poartă X-Agro-Event, X-Agro-Timestamp în secunde Unix și X-Agro-Signature cu HMAC-SHA256 al "<timestamp>.<cuerpo>". Verifică ambele: semnătura și că ceasul nu s-a decalat cu mai mult de cinci minute.
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"])Regulile de livrare, spuse clar ca să nu ai surprize: o singură încercare, șase secunde de așteptare și fără reîncercări. Nu urmăm redirecționări și respingem adresele private, cele link-local și cele de metadate din cloud, atât la înregistrarea adresei, cât și la rezolvarea DNS la fiecare livrare. Dacă sistemul tău are nevoie de garanții, folosește webhookul ca semnal și GET /sync/entries cu since ca plasă de siguranță: avizul e o politețe, API-ul e adevărul.
MCP pentru asistenți AI
Același API este disponibil ca server MCP, protocolul prin care asistenții se conectează la unelte. Poți întreba un asistent, de exemplu, ce exploatații sunt în urmă, cât a costat campania sau ce lipsește înainte de un control.
{ "mcpServers": { "agro-gps": {
"command": "npx", "args": ["-y", "agro-gps-mcp"],
"env": { "AGROGPS_API_KEY": "agk_…" } } } }Unelte disponibile: list_farms, list_entries, entry_history, list_groups, group_overview, advisor_portfolio, advisor_pending și record_entry. Ultima funcționează doar cu cheie de scriere, rămâne marcată în istoric ca scriere prin API și nu trimite niciodată nimic autorităților.
De ce API-ul nu poate fi folosit pentru a trișa
Un API peste un registru cu valoare legală trebuie să reziste unei priviri atente. În Spania, RD 1054/2022 permite ținerea registrului în orice sistem informatic care îndeplinește cerințele anexei II și face schimb de date cu SIEX, și spune clar că răspunderea pentru corectitudinea datelor este a titularului, nu a programului. Partea noastră este integritatea datelor și este scrisă în cod, în toate țările.
| Ce ar putea încerca cineva | Ce face API-ul |
|---|---|
| Să noteze azi cu o dată de acum câteva luni | Fiecare lucrare păstrează data declarată și momentul real al sosirii pe server, iar istoricul notează zilele de întârziere |
| Să noteze cu o dată viitoare | Se respinge dacă depășește 24 de ore de acum |
| Să scrie fără o persoană în spate | Orice lucrare are autor, iar cele intrate cu cheie sunt marcate cu prefixul acelei chei |
| Să șteargă ce încurcă | Nu se șterge nimic: ștergerile sunt pietre funerare cu dată |
| Să trimită automat la autorități | Trimiterea oficială cere sesiunea unei persoane cu drept de trimitere: o cheie primește 403 SIE_403 |
Trimiterea oficială există azi doar în Spania, unde așteaptă aprobarea regiune cu regiune. Agro GPS nu trimite nimic către platforma ANF: prin API citești și scrii registrul.
Erori
Întotdeauna {"code":"INT_NNN","message":"…"}, niciodată o urmă de stivă. Cele pe care le vei vedea cel mai des: AUT_003 cheie invalidă, AUT_004 cheie doar pentru citire, AUT_429 prea multe încercări, AUT_503 autentificare indisponibilă (nu e același lucru cu o cheie greșită: reîncearcă), INT_003 adresă care nu e https, INT_403 operație care cere sesiune, INT_404 cheie sau webhook care nu e al tău.
Cum obții o cheie
API-ul vine cu planurile pentru firme și consultanți. Dacă ai deja cont, cheia se creează din aplicație. Dacă evaluezi integrarea înainte de a cumpăra, scrie la support@agrogps.eu ce sistem vrei să conectezi și îți dăm acces de test. Documentația este publică și gratuită: preferăm să o citești înainte să plătești.
Întrebări frecvente
Pot ține tot registrul din ERP fără să deschid aplicația? Da pentru înregistrare și citire. Nu pentru trimiterea oficială la autorități, care cere sesiunea unei persoane cu drept de trimitere. Este o decizie deliberată: actul acesta are consecințe legale și nu trebuie declanșat de un proces automat.
Datele sunt ale mele? Da. Exportul complet este mereu gratuit, și dacă renunți, iar prin API iei exact ce vezi pe ecran, inclusiv istoricul și urma modificărilor.
Există o limită de apeluri? Nu există o cotă publicată pentru utilizarea normală dintr-un ERP. Testarea unui webhook este limitată la douăzeci de ori per utilizator și IP la fiecare zece minute, ca nimeni să nu folosească funcția pentru a genera trafic.
Ce se întâmplă dacă schimbați API-ul? Versiunea este în adresă. Cât timp v1 rămâne publicată, nu scoatem câmpuri și nu schimbăm sensul celor existente; ce e nou se adaugă. Dacă va exista cândva o v2, vor funcționa în paralel.
Serverul MCP este pe npm? Încă nu. Azi rulează din depozitul de cod; publicarea nu a fost încă decisă. Configurația de mai sus este cea care va funcționa în ziua publicării.
Este bun pentru un consultant cu mulți clienți? Pentru asta există advisor/portfolio: un singur apel îți spune ce exploatații sunt la zi și care au lucrări incomplete, fără să intri în fiecare pe rând.