API, webhooks και MCP: σύνδεσε το ERP σου με το ημερολόγιο

Αν διαχειρίζεσαι την εκμετάλλευση με ένα ERP, ένα φύλλο κόστους ή το πρόγραμμα του συμβούλου σου, δεν έχει νόημα να πληκτρολογείς τις εργασίες δύο φορές. Αυτή είναι η τεκμηρίωση για να βγάζεις απ' έξω το ημερολόγιο, τα κόστη και την κατάσταση συμμόρφωσης, και για να περνάς εργασίες από το σύστημα που ήδη χρησιμοποιείς.

Η βάση είναι https://agrogps-api.fly.dev/api/v1. Είναι σε παραγωγή από τις 17 Σεπτεμβρίου 2026. Απαντά πάντα σε JSON, και στα σφάλματα.

Δύο τρόποι ταυτοποίησης

Το κλειδί δημιουργείται μία φορά από τη σύνδεσή σου και εμφανίζεται μόνο μία φορά: μετά κρατάμε μόνο το hash του. Αν το χάσεις, ανακαλείται και φτιάχνεις άλλο. Ένα κλειδί μόνο ανάγνωσης που προσπαθεί να γράψει παίρνει 403 AUT_004. Τα κλειδιά δεν μπορούν να δημιουργούν ή να διαγράφουν άλλα κλειδιά ή webhooks: αυτό γίνεται πάντα με τη σύνδεση ενός ανθρώπου.

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

Τι μπορείς να διαβάσεις

Με κλειδί εγγραφής μπορείς επιπλέον να καταχωρείς εργασίες με POST /sync/entries, με το ίδιο σώμα που χρησιμοποιεί η εφαρμογή. Ο συγχρονισμός γίνεται με since, οπότε μια νυχτερινή διεργασία φέρνει μόνο ό,τι άλλαξε.

Ξεκίνα δωρεάν

Υπογεγραμμένα webhooks

Αντί να ρωτάς κάθε πέντε λεπτά, σε ειδοποιούμε εμείς. Καταχωρούμε μια δημόσια διεύθυνση https και στέλνουμε ειδοποίηση όταν συμβαίνει κάτι σε εκμετάλλευση όπου είσαι ιδιοκτήτης ή υπεύθυνος.

Κάθε αποστολή φέρει X-Agro-Event, X-Agro-Timestamp σε δευτερόλεπτα Unix και X-Agro-Signature με το HMAC-SHA256 του "<timestamp>.<cuerpo>". Έλεγξε και τα δύο: την υπογραφή και ότι το ρολόι δεν έχει αποκλίνει πάνω από πέντε λεπτά.

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

Κανόνες αποστολής, ξεκάθαρα για να μην έχεις εκπλήξεις: μία προσπάθεια, έξι δευτερόλεπτα αναμονή και χωρίς επαναλήψεις. Δεν ακολουθούμε ανακατευθύνσεις και απορρίπτουμε ιδιωτικές διευθύνσεις, διευθύνσεις τοπικής σύνδεσης και μεταδεδομένων cloud, τόσο κατά την καταχώρηση της διεύθυνσης όσο και στην επίλυση DNS κάθε αποστολής. Αν το σύστημά σου χρειάζεται εγγυήσεις, χρησιμοποίησε το webhook ως ειδοποίηση και το GET /sync/entries με since ως δίχτυ ασφαλείας: η ειδοποίηση είναι ευγένεια, η API είναι η αλήθεια.

MCP για βοηθούς ΤΝ

Η ίδια API εκτίθεται ως διακομιστής MCP, το πρωτόκολλο με το οποίο οι βοηθοί συνδέονται σε εργαλεία. Χρησιμεύει για να ρωτάς έναν βοηθό πράγματα όπως ποιες εκμεταλλεύσεις καθυστερούν, πόσο κόστισε η καλλιεργητική περίοδος ή τι λείπει πριν από έναν έλεγχο.

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

Διαθέσιμα εργαλεία: list_farms, list_entries, entry_history, list_groups, group_overview, advisor_portfolio, advisor_pending και record_entry. Το τελευταίο λειτουργεί μόνο με κλειδί εγγραφής, σημειώνεται στο ιστορικό ως εγγραφή μέσω API και δεν στέλνει ποτέ τίποτα στη διοίκηση.

Γιατί η API δεν κάνει για κόλπα

Μια API πάνω σε ένα αρχείο με νομική αξία πρέπει να αντέχει να την κοιτάξεις κατάματα. Στην Ισπανία, το RD 1054/2022 επιτρέπει να τηρείται το ημερολόγιο με οποιοδήποτε σύστημα πληροφορικής πληροί τις απαιτήσεις του παραρτήματος II και είναι διαλειτουργικό με το SIEX, και ξεκαθαρίζει ότι υπεύθυνος για την ακρίβεια είναι ο κάτοχος, όχι το πρόγραμμα. Το ίδιο ισχύει παντού: το δικό μας κομμάτι είναι η ακεραιότητα, και είναι γραμμένη στον κώδικα.

Σφάλματα

Πάντα {"code":"INT_NNN","message":"…"}, ποτέ ίχνος στοίβας. Αυτά που θα δεις πιο συχνά: AUT_003 μη έγκυρο κλειδί, AUT_004 κλειδί μόνο ανάγνωσης, AUT_429 πάρα πολλές προσπάθειες, AUT_503 η ταυτοποίηση δεν είναι διαθέσιμη (δεν είναι το ίδιο με λάθος κλειδί: ξαναδοκίμασε), INT_003 διεύθυνση που δεν είναι https, INT_403 ενέργεια που απαιτεί σύνδεση, INT_404 κλειδί ή webhook που δεν είναι δικό σου.

Πώς παίρνεις κλειδί

Η API περιλαμβάνεται στα πακέτα για επιχειρήσεις και συμβούλους. Αν έχεις ήδη λογαριασμό, το κλειδί δημιουργείται από την ίδια την εφαρμογή. Αν αξιολογείς τη σύνδεση πριν αγοράσεις, γράψε στο support@agrogps.eu ποιο σύστημα θέλεις να συνδέσεις και σου δίνουμε δοκιμαστική πρόσβαση. Η τεκμηρίωση είναι δημόσια και δωρεάν: προτιμάμε να τη δεις πριν πληρώσεις.

Ξεκίνα δωρεάν

Συχνές ερωτήσεις

Μπορώ να τηρώ όλο το ημερολόγιο από το ERP μου χωρίς να ανοίγω την εφαρμογή; Ναι για καταχώριση και ανάγνωση. Όχι για την επίσημη αποστολή στη διοίκηση, που υπάρχει μόνο στην Ισπανία και απαιτεί τη σύνδεση ανθρώπου με άδεια αποστολής. Είναι σκόπιμη απόφαση: αυτή η πράξη έχει νομικές συνέπειες και δεν πρέπει να την ενεργοποιεί μια αυτόματη διεργασία.

Τα δεδομένα είναι δικά μου; Ναι. Η πλήρης εξαγωγή είναι πάντα δωρεάν, και αν ακυρώσεις, και μέσω της API παίρνεις ακριβώς ό,τι βλέπεις στην οθόνη, μαζί με το ιστορικό και το ίχνος των αλλαγών.

Υπάρχει όριο κλήσεων; Δεν υπάρχει δημοσιευμένο όριο για κανονική χρήση από ένα ERP. Η δοκιμή ενός webhook περιορίζεται σε είκοσι φορές ανά χρήστη και IP κάθε δέκα λεπτά, ώστε κανείς να μη χρησιμοποιεί τη λειτουργία ως πηγή κίνησης.

Τι γίνεται αν αλλάξετε την API; Η έκδοση είναι στη διεύθυνση. Όσο η v1 παραμένει δημοσιευμένη, δεν αφαιρούμε πεδία ούτε αλλάζουμε τη σημασία όσων υπάρχουν· τα νέα προστίθενται. Αν κάποτε υπάρξει v2, θα συνυπάρχουν.

Ο διακομιστής MCP είναι στο npm; Όχι ακόμη. Σήμερα εκτελείται από το αποθετήριο· η δημοσίευση δεν έχει αποφασιστεί. Η παραπάνω ρύθμιση είναι αυτή που θα λειτουργεί τη μέρα που θα δημοσιευτεί.

Κάνει για σύμβουλο με πολλούς πελάτες; Γι' αυτό υπάρχει το advisor/portfolio: μία κλήση σου λέει ποιες εκμεταλλεύσεις είναι ενημερωμένες και ποιες έχουν ελλιπείς εργασίες, χωρίς να μπαίνεις σε κάθε μία.