API, webhooki i MCP: połącz swój ERP z ewidencją
Jeśli prowadzisz gospodarstwo w systemie ERP, arkuszu kosztów albo programie swojego doradcy, nie ma sensu wpisywać zabiegów dwa razy. To dokumentacja, dzięki której pobierzesz ewidencję, koszty i stan zgodności z zewnątrz oraz wprowadzisz zabiegi z systemu, którego już używasz.
Adres bazowy to https://agrogps-api.fly.dev/api/v1. Działa produkcyjnie od 17 września 2026. Zawsze odpowiada w JSON, także przy błędach.
Dwa sposoby uwierzytelnienia
| Kto wywołuje | Nagłówek | Co może |
|---|---|---|
| Aplikacja lub strona | Authorization: Bearer <sesión> | Wszystko, także tworzyć i unieważniać klucze |
| System zewnętrzny | X-API-Key: agk_… | Czytać albo czytać i zapisywać, zależnie od zakresu klucza |
Klucz tworzysz raz ze swojej sesji i pokazujemy go tylko raz: potem przechowujemy wyłącznie jego skrót. Jeśli go zgubisz, unieważniasz go i tworzysz nowy. Klucz tylko do odczytu, który próbuje zapisywać, dostaje 403 AUT_004. Klucze nie mogą tworzyć ani usuwać innych kluczy ani webhooków: to zawsze wymaga sesji człowieka.
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"}'Co możesz odczytać
| Endpoint | Zwraca |
|---|---|
GET /farms | Gospodarstwa właściciela klucza, z rolą |
GET /sync/entries?farm_id=…&since=0 | Wszystkie zabiegi ze wszystkimi polami ewidencji, stronicowane przez next |
GET /groups/:id/overview | Panel grupy: zabiegi, koszt, przychody, marża, opryskane hektary i uprawa w każdym gospodarstwie |
GET /advisor/portfolio | Portfel doradcy: które gospodarstwa są na bieżąco, a które nie |
GET /advisor/farms/:id/pending | Pola, które zostały do uzupełnienia, zabieg po zabiegu |
GET /notebook/entries/:id/history | Kto, co i kiedy zmienił w zabiegu |
Kluczem z prawem zapisu możesz też rejestrować zabiegi przez POST /sync/entries, z taką samą treścią, jakiej używa aplikacja. Synchronizacja działa przez since, więc nocny proces pobiera tylko to, co się zmieniło.
Podpisane webhooki
Zamiast pytać co pięć minut, to my dajemy znać. Rejestrujesz publiczny adres https, a my wysyłamy powiadomienie, gdy coś dzieje się w gospodarstwie, którego jesteś właścicielem lub kierownikiem.
| Zdarzenie | Kiedy się uruchamia |
|---|---|
entry.pushed | Zabiegi się synchronizują i przynajmniej jeden zostaje przyjęty |
entry.reviewed | Doradca lub właściciel zatwierdza albo oznacza zabieg |
webhook.test | Naciskasz „testuj” |
Każde doręczenie zawiera X-Agro-Event, X-Agro-Timestamp w sekundach Unix oraz X-Agro-Signature z HMAC-SHA256 z "<timestamp>.<cuerpo>". Sprawdź obie rzeczy: podpis i to, czy zegar nie rozjechał się o więcej niż pięć minut.
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"])Zasady doręczania, powiedziane jasno, żeby nie było niespodzianek: jedna próba, sześć sekund oczekiwania i bez ponowień. Nie podążamy za przekierowaniami i odrzucamy adresy prywatne, lokalne łącza i adresy metadanych chmury, zarówno przy rejestracji adresu, jak i przy rozwiązywaniu DNS przy każdym doręczeniu. Jeśli twój system potrzebuje gwarancji, traktuj webhook jako sygnał, a GET /sync/entries z since jako siatkę bezpieczeństwa: powiadomienie to uprzejmość, API to prawda.
MCP dla asystentów AI
To samo API jest dostępne jako serwer MCP, protokół, którego asystenci używają do łączenia się z narzędziami. Możesz zapytać asystenta na przykład, które gospodarstwa mają zaległości, ile kosztował sezon albo czego brakuje przed kontrolą.
{ "mcpServers": { "agro-gps": {
"command": "npx", "args": ["-y", "agro-gps-mcp"],
"env": { "AGROGPS_API_KEY": "agk_…" } } } }Dostępne narzędzia: list_farms, list_entries, entry_history, list_groups, group_overview, advisor_portfolio, advisor_pending i record_entry. Ostatnie działa tylko z kluczem do zapisu, w historii zostaje oznaczone jako zapis przez API i nigdy niczego nie wysyła do administracji.
Dlaczego API nie pozwala oszukiwać
API nad ewidencją o znaczeniu prawnym musi wytrzymać uważne spojrzenie. W Hiszpanii RD 1054/2022 pozwala prowadzić ewidencję w dowolnym systemie informatycznym, który spełnia wymogi załącznika II i wymienia dane z SIEX, i jasno mówi, że za prawdziwość odpowiada posiadacz gospodarstwa, a nie program. Naszą częścią jest integralność danych i jest ona zapisana w kodzie, w każdym kraju.
| Co ktoś mógłby próbować | Co robi API |
|---|---|
| Wpisać dziś zabieg z datą sprzed kilku miesięcy | Każdy zabieg zapisuje zadeklarowaną datę i faktyczną datę dotarcia na serwer, a historia odnotowuje liczbę dni opóźnienia |
| Wpisać zabieg z datą przyszłą | Odrzucane, jeśli wykracza ponad 24 godziny od teraz |
| Zapisywać bez człowieka za tym | Każdy zabieg ma autora, a te wprowadzone kluczem są oznaczone prefiksem tego klucza |
| Usunąć to, co przeszkadza | Nic się nie usuwa: usunięcia to nagrobki z datą |
| Automatycznie wysyłać do administracji | Oficjalne przesłanie wymaga sesji osoby z uprawnieniem: klucz dostaje 403 SIE_403 |
Oficjalne przesyłanie istnieje dziś tylko w Hiszpanii i czeka tam na zatwierdzenie region po regionie. W Polsce nie ma państwowego systemu, do którego się wysyła: przez API czytasz i zapisujesz ewidencję.
Błędy
Zawsze {"code":"INT_NNN","message":"…"}, nigdy ślad stosu. Najczęstsze: AUT_003 nieprawidłowy klucz, AUT_004 klucz tylko do odczytu, AUT_429 zbyt wiele prób, AUT_503 uwierzytelnianie niedostępne (to nie to samo co zły klucz: spróbuj ponownie), INT_003 adres, który nie jest https, INT_403 operacja wymagająca sesji, INT_404 klucz lub webhook, który nie jest twój.
Jak zdobyć klucz
API jest w planach dla firm i doradców. Jeśli masz już konto, klucz tworzysz w aplikacji. Jeśli rozważasz integrację przed zakupem, napisz na support@agrogps.eu, jaki system chcesz podłączyć, a damy ci dostęp testowy. Dokumentacja jest publiczna i bezpłatna: wolimy, żebyś ją przejrzał przed zapłatą.
Najczęstsze pytania
Czy mogę prowadzić całą ewidencję z ERP bez otwierania aplikacji? Tak, jeśli chodzi o rejestrowanie i odczyt. Nie, jeśli chodzi o oficjalne przesłanie do administracji, które wymaga sesji osoby z uprawnieniem do wysyłki. To świadoma decyzja: ta czynność ma skutki prawne i nie powinien jej uruchamiać automatyczny proces.
Czy dane są moje? Tak. Pełny eksport jest zawsze bezpłatny, także po rezygnacji, a przez API zabierasz dokładnie to samo, co widzisz na ekranie, łącznie z historią i śladem zmian.
Czy jest limit wywołań? Nie ma opublikowanego limitu dla normalnego użycia z ERP. Testowanie webhooka jest ograniczone do dwudziestu razy na użytkownika i IP co dziesięć minut, żeby nikt nie używał tej funkcji do generowania ruchu.
Co jeśli zmienicie API? Wersja jest w adresie. Dopóki v1 jest opublikowana, nie usuwamy pól ani nie zmieniamy znaczenia istniejących; nowe rzeczy dodajemy. Jeśli kiedyś pojawi się v2, obie będą działać równolegle.
Czy serwer MCP jest w npm? Jeszcze nie. Dziś uruchamia się go z repozytorium; publikacja nie została jeszcze postanowiona. Konfiguracja powyżej to ta, która zadziała w dniu publikacji.
Czy to się przyda doradcy z wieloma klientami? Po to jest advisor/portfolio: jedno wywołanie mówi, które gospodarstwa są na bieżąco, a które mają niekompletne zabiegi, bez wchodzenia do każdego z osobna.