API, webhooks и MCP: свържи своя ERP с дневника
Ако водиш стопанството в ERP, в таблица с разходи или в програмата на своя консултант, няма смисъл да въвеждаш дейностите два пъти. Това е документацията как отвън да вземеш дневника, разходите и състоянието на изпълнение на изискванията и как да въвеждаш дейности от системата, която вече използваш.
Основният адрес е https://agrogps-api.fly.dev/api/v1. В производство е от 17 септември 2026 г. Винаги отговаря с JSON, включително при грешки.
Два начина за удостоверяване
| Кой извиква | Заглавка | Какво може |
|---|---|---|
| Приложението или сайтът | Authorization: Bearer <sesión> | Всичко, включително създаване и отмяна на ключове |
| Външна система | X-API-Key: agk_… | Четене, или четене и запис според обхвата на ключа |
Ключът се създава веднъж от твоята сесия и се показва само веднъж: след това пазим само неговия 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"}'Какво можеш да четеш
| Endpoint | Връща |
|---|---|
GET /farms | Стопанствата на притежателя на ключа и ролята му |
GET /sync/entries?farm_id=…&since=0 | Всички дейности с всички полета, на страници чрез next |
GET /groups/:id/overview | Табло на групата: дейности, разход, приходи, марж, третирани хектари и култура по стопанство |
GET /advisor/portfolio | Портфейл на консултанта: кои стопанства са изрядни и кои не |
GET /advisor/farms/:id/pending | Полетата, които липсват, дейност по дейност |
GET /notebook/entries/:id/history | Кой какво и кога е променил в дейност |
С ключ за запис можеш също да въвеждаш дейности чрез POST /sync/entries, със същото тяло, което използва приложението. Синхронизацията става чрез since, така че нощен процес взема само промененото.
Подписани webhooks
Вместо да питаш на всеки пет минути, ние те известяваме. Регистрираме публичен адрес https и изпращаме известие, когато нещо се случи в стопанство, където си собственик или управител.
| Събитие | Кога се задейства |
|---|---|
entry.pushed | Синхронизират се дейности и поне една е приета |
entry.reviewed | Консултант или титулярът одобрява или отбелязва дейност |
webhook.test | Натискаш тест |
Всяка доставка носи 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"])Правила за доставка, казани ясно, за да няма изненади: един опит, шест секунди изчакване и без повторения. Не следваме пренасочвания и отхвърляме частни адреси, адреси за локална връзка и за метаданни в облака, както при регистрацията на адреса, така и при DNS разрешаването на всяка доставка. Ако системата ти има нужда от гаранции, използвай webhook като известие, а GET /sync/entries със since като предпазна мрежа: известието е любезност, истината е API.
MCP за AI асистенти
Същото 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, и ясно казва, че за достоверността отговаря титулярът, а не програмата. Това важи навсякъде: нашата част е целостта и тя е записана в кода.
| Какво би могъл да опита някой | Какво прави API |
|---|---|
| Да запише днес с дата отпреди месеци | Всяка дейност пази декларираната дата и реалното пристигане на сървъра, а историята записва дните закъснение |
| Да запише с бъдеща дата | Отхвърля се, ако надхвърля 24 часа от сега |
| Да пише без човек зад това | Всяка дейност има автор, а влезлите с ключ са отбелязани с префикса на ключа |
| Да изтрие неудобното | Нищо не се изтрива: изтриванията са надгробни записи с дата |
| Да изпрати автоматично на администрацията | Официалното подаване (съществува само в Испания) изисква сесия на упълномощен човек: ключът получава 403 SIE_403 |
Грешки
Винаги {"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, без да отварям приложението? Да, за въвеждане и четене. Не за официалното подаване към администрацията, което съществува само в Испания и изисква сесия на човек с право да подава. Това е съзнателно решение: този акт има правни последици и не бива да се задейства от автоматичен процес. Предварителното уведомяване по ЕПОРД в България също не се прави от Agro GPS.
Данните мои ли са? Да. Пълният експорт винаги е безплатен, дори ако се откажеш, и през API вземаш точно това, което виждаш на екрана, включително историята и следата от промени.
Има ли ограничение на извикванията? Няма публикувана квота за нормална употреба от ERP. Тестът на webhook е ограничен до двадесет пъти на потребител и IP на всеки десет минути, за да не се използва функцията като източник на трафик.
Какво става, ако промените API? Версията е в адреса. Докато v1 е публикувана, не махаме полета и не променяме смисъла на съществуващите; новото се добавя. Ако някога има v2, двете ще съществуват паралелно.
MCP сървърът в npm ли е? Още не. Днес се стартира от хранилището; публикуването още не е решено. Конфигурацията по-горе е тази, която ще работи в деня на публикуването.
Става ли за консултант с много клиенти? За това е advisor/portfolio: едно извикване ти казва кои стопанства са изрядни и кои имат непълни дейности, без да отваряш всяко поотделно.