API, webhook e MCP: collega il tuo gestionale al quaderno

Se gestisci l'azienda con un gestionale, un foglio dei costi o il programma del tuo consulente, non ha senso digitare ogni lavorazione due volte. Questa è la documentazione per tirare fuori il quaderno, i costi e lo stato di conformità dall'esterno, e per far entrare lavorazioni dal sistema che usi già.

La base è https://agrogps-api.fly.dev/api/v1. È in produzione dal 17 settembre 2026. Risponde sempre in JSON, anche negli errori.

Due modi per identificarsi

La chiave si crea una volta dalla tua sessione e si mostra una sola volta: dopo conserviamo solo il suo hash. Se la perdi, si revoca e se ne crea un'altra. Una chiave di sola lettura che prova a scrivere riceve 403 AUT_004. Le chiavi non possono creare né cancellare altre chiavi o webhook: per questo serve sempre la sessione di una persona.

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

Cosa puoi leggere

Con una chiave di scrittura puoi anche registrare lavorazioni con POST /sync/entries, con lo stesso corpo che usa l'app. La sincronizzazione va per since, quindi un processo notturno scarica solo ciò che è cambiato.

Inizia gratis

Webhook firmati

Invece di chiedere ogni cinque minuti, ti avvisiamo noi. Registri un URL https pubblico e mandiamo un avviso quando succede qualcosa in un'azienda di cui sei titolare o gestore.

Ogni invio porta X-Agro-Event, X-Agro-Timestamp in secondi Unix e X-Agro-Signature con l'HMAC-SHA256 di "<timestamp>.<cuerpo>". Controlla entrambe le cose: la firma e che l'orologio non si sia spostato di più di cinque minuti.

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

Le regole di consegna, dette chiaramente per evitare sorprese: un tentativo, sei secondi di attesa e nessun nuovo tentativo. Non seguiamo reindirizzamenti e rifiutiamo indirizzi privati, link-local e di metadati cloud, sia quando registri l'URL sia quando risolviamo il DNS di ogni invio. Se il tuo sistema ha bisogno di garanzie, usa il webhook come avviso e GET /sync/entries con since come rete di sicurezza: l'avviso è una cortesia, l'API è la verità.

MCP per assistenti IA

La stessa API è esposta come server MCP, il protocollo che gli assistenti usano per collegarsi agli strumenti. Serve a chiedere a un assistente quali aziende sono in ritardo, quanto è costata la campagna o cosa manca prima di un controllo.

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

Strumenti disponibili: list_farms, list_entries, entry_history, list_groups, group_overview, advisor_portfolio, advisor_pending e record_entry. L'ultimo funziona solo con una chiave di scrittura, resta segnato nello storico come scrittura via API e non invia mai nulla alla pubblica amministrazione.

Perché l'API non serve per imbrogliare

Un'API su un registro con valore legale deve poter essere guardata in faccia. In Spagna, il RD 1054/2022 permette di tenere il quaderno con qualsiasi programma che rispetti l'allegato II e sia interoperabile con il SIEX, e chiarisce che della veridicità risponde il titolare, non il programma. In Italia vale lo stesso principio: il registro è responsabilità dell'azienda. La nostra parte è l'integrità, ed è scritta nel codice.

Errori

Sempre {"code":"INT_NNN","message":"…"}, mai una traccia. Quelli che vedrai di più: AUT_003 chiave non valida, AUT_004 chiave di sola lettura, AUT_429 troppi tentativi, AUT_503 autenticazione non disponibile (non è una chiave sbagliata: riprova), INT_003 URL che non è https, INT_403 operazione che richiede una sessione, INT_404 chiave o webhook che non è tuo.

Come si ottiene una chiave

L'API è inclusa nei piani per aziende e per consulenti. Se hai già un account, la chiave si crea dall'app. Se stai valutando l'integrazione prima di abbonarti, scrivi a support@agrogps.eu raccontando quale sistema vuoi collegare e ti diamo un accesso di prova. La documentazione è pubblica e gratuita: preferiamo che tu la legga prima di pagare.

Inizia gratis

Domande frequenti

Posso tenere tutto il quaderno dal mio gestionale senza aprire l'app? Sì per registrare e leggere. No per un invio ufficiale, che esiste solo in Spagna e lì richiede la sessione di una persona autorizzata. È una scelta voluta: quell'atto ha conseguenze legali e non deve partire da un processo automatico.

I dati sono miei? Sì. L'esportazione completa è sempre gratuita, anche dopo la disdetta, e con l'API ti porti via esattamente ciò che vedi a schermo, storico e traccia delle modifiche compresi.

C'è un limite di chiamate? Non c'è una quota pubblicata per l'uso normale di un gestionale. La prova di un webhook è limitata a venti volte per utente e IP ogni dieci minuti, perché nessuno usi la funzione per generare traffico.

Cosa succede se cambiate l'API? La versione è nell'URL. Finché v1 resta pubblicata non togliamo campi né cambiamo il significato di quelli esistenti; il nuovo si aggiunge. Se un giorno ci fosse una v2, convivrebbero.

Il server MCP è su npm? Non ancora. Oggi si esegue dal repository; la pubblicazione è ancora da decidere. La configurazione qui sopra è quella che funzionerà il giorno in cui sarà pubblicato.

Serve a un consulente con molti clienti? È a questo che serve advisor/portfolio: una chiamata ti dice quali aziende sono in regola e quali hanno lavorazioni incomplete, senza aprirle una per una.