API, tīmekļa āķi un MCP: savieno savu ERP ar žurnālu

Ja saimniecību ved ERP sistēmā, izmaksu tabulā vai sava konsultanta programmā, nav jēgas darbus ievadīt divreiz. Šī ir dokumentācija, lai no ārpuses iegūtu žurnālu, izmaksas un atbilstības stāvokli un lai ievadītu darbus no sistēmas, ko jau lieto.

Bāze ir https://agrogps-api.fly.dev/api/v1. Tā darbojas kopš 2026. gada 17. septembra. Vienmēr atbild JSON formātā, arī kļūdu gadījumā.

Divi veidi, kā sevi identificēt

Atslēgu izveido vienreiz no savas sesijas, un to parāda tikai vienu reizi: pēc tam glabājam tikai tās jaucējvērtību. Ja to pazaudē, to atsauc un izveido jaunu. Tikai lasīšanas atslēga, kas mēģina rakstīt, saņem 403 AUT_004. Atslēgas nevar veidot vai dzēst citas atslēgas vai tīmekļa āķus: to vienmēr dara ar cilvēka sesiju.

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

Ko vari lasīt

Ar rakstīšanas atslēgu vari arī reģistrēt darbus ar POST /sync/entries, ar to pašu pieprasījuma ķermeni, ko izmanto lietotne. Sinhronizācija notiek pēc since, tāpēc nakts process ielādē tikai to, kas mainījies.

Sākt bez maksas

Parakstīti tīmekļa āķi

Tā vietā, lai jautātu ik pēc piecām minūtēm, mēs paziņojam paši. Reģistrē publisku https URL, un mēs sūtām ziņu, kad kaut kas notiek saimniecībā, kurā esi īpašnieks vai pārvaldnieks.

Katrā piegādē ir X-Agro-Event, X-Agro-Timestamp Unix sekundēs un X-Agro-Signature ar HMAC-SHA256 no "<timestamp>.<cuerpo>". Pārbaudi abus: parakstu un to, ka pulkstenis nav aizgājis vairāk par piecām minūtēm.

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

Piegādes noteikumi, skaidri pateikti, lai nebūtu pārsteigumu: viens mēģinājums, sešas sekundes gaidīšanas un bez atkārtojumiem. Mēs nesekojam pāradresācijām un noraidām privātas, saites lokālās un mākoņa metadatu adreses gan reģistrējot URL, gan atrisinot DNS katrai piegādei. Ja tavai sistēmai vajag garantijas, izmanto tīmekļa āķi kā paziņojumu un GET /sync/entries ar since kā drošības tīklu: paziņojums ir pieklājība, API ir patiesība.

MCP MI asistentiem

Tā pati API ir pieejama kā MCP serveris, protokols, ar ko asistenti pieslēdzas rīkiem. Ar to vari pajautāt asistentam, piemēram, kuras saimniecības kavējas, cik izmaksāja sezona vai kas vēl jāaizpilda pirms pārbaudes.

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

Pieejamie rīki: list_farms, list_entries, entry_history, list_groups, group_overview, advisor_portfolio, advisor_pending un record_entry. Pēdējais darbojas tikai ar rakstīšanas atslēgu, vēsturē tiek atzīmēts kā ieraksts caur API un nekad neko nesūta iestādēm.

Kāpēc API neder krāpšanai

API reģistram ar juridisku nozīmi jābūt tādai, ko var aplūkot bez bailēm. Spānijā RD 1054/2022 ļauj vest žurnālu jebkurā informācijas sistēmā, kas atbilst II pielikuma prasībām un ir sadarbspējīga ar SIEX, un skaidri nosaka, ka par datu patiesumu atbild īpašnieks, nevis programma. Mūsu daļa ir integritāte, un tā ir iebūvēta kodā, visās valstīs.

Kļūdas

Vienmēr {"code":"INT_NNN","message":"…"}, nekad izsekošana. Biežākās: AUT_003 nederīga atslēga, AUT_004 tikai lasīšanas atslēga, AUT_429 pārāk daudz mēģinājumu, AUT_503 autentifikācija nav pieejama (tas nav tas pats, kas slikta atslēga: mēģini vēlreiz), INT_003 URL, kas nav https, INT_403 darbība, kurai vajag sesiju, INT_404 atslēga vai tīmekļa āķis, kas nav tavs.

Kā iegūt atslēgu

API ir iekļauta uzņēmumu un konsultāciju plānos. Ja tev jau ir konts, atslēgu izveido pašā lietotnē. Ja izvērtē integrāciju pirms līguma, raksti uz support@agrogps.eu, kuru sistēmu vēlies pieslēgt, un mēs dosim testa piekļuvi. Dokumentācija ir publiska un bezmaksas: labāk, lai to apskati pirms maksāšanas.

Sākt bez maksas

Biežāk uzdotie jautājumi

Vai varu vest visu žurnālu no sava ERP, neatverot lietotni? Jā, reģistrēšanai un lasīšanai. Oficiāla nosūtīšana pastāv tikai Spānijā un prasa cilvēka sesiju ar sūtīšanas atļauju. Tas ir apzināts lēmums: šai darbībai ir juridiskas sekas, un to nedrīkst iedarbināt automātisks process.

Vai dati ir mani? Jā. Pilns eksports vienmēr ir bez maksas, arī pēc atteikšanās, un caur API tu saņem tieši to pašu, ko redzi ekrānā, ieskaitot vēsturi un izmaiņu pēdas.

Vai ir izsaukumu limits? ERP parastai lietošanai publicētas kvotas nav. Tīmekļa āķa pārbaude ir ierobežota līdz divdesmit reizēm uz lietotāju un IP ik pēc desmit minūtēm, lai neviens funkciju neizmantotu kā datplūsmas ģeneratoru.

Kas notiek, ja maināt API? Versija ir URL. Kamēr v1 ir publicēta, mēs nenoņemam laukus un nemainām esošo nozīmi; jaunais tiek pievienots. Ja kādreiz būs v2, tās pastāvētu līdzās.

Vai MCP serveris ir npm? Vēl nē. Pašlaik to palaiž no repozitorija; par publicēšanu vēl nav lemts. Augstāk redzamā konfigurācija ir tā, kas darbosies publicēšanas dienā.

Vai tas der konsultantam ar daudziem klientiem? Tam ir advisor/portfolio: viens izsaukums pasaka, kuras saimniecības ir kārtībā un kurām ir nepabeigti darbi, neieejot katrā atsevišķi.