API, webhooks e MCP: ligue o seu ERP ao caderno

Se gere a exploração com um ERP, uma folha de custos ou o programa do seu consultor, não faz sentido escrever cada trabalho duas vezes. Esta é a documentação para tirar o caderno, os custos e o estado de cumprimento a partir de fora, e para introduzir trabalhos a partir do sistema que já usa.

A base é https://agrogps-api.fly.dev/api/v1. Está em produção desde 17 de setembro de 2026. Responde sempre em JSON, também nos erros.

Duas formas de se identificar

A chave cria-se uma vez a partir da sua sessão e mostra-se uma única vez: depois só guardamos o seu hash. Se a perder, revoga-se e cria-se outra. Uma chave só de leitura que tente escrever recebe 403 AUT_004. As chaves não podem criar nem apagar outras chaves nem webhooks: isso exige sempre a sessão de uma pessoa.

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

O que pode ler

Com uma chave de escrita pode também registar trabalhos com POST /sync/entries, com o mesmo corpo que a app usa. A sincronização faz-se por since, por isso um processo noturno só traz o que mudou.

Começar grátis

Webhooks assinados

Em vez de perguntar a cada cinco minutos, avisamos nós. Regista um URL https público e enviamos um aviso quando acontece algo numa exploração onde é titular ou gestor.

Cada entrega leva X-Agro-Event, X-Agro-Timestamp em segundos Unix e X-Agro-Signature com o HMAC-SHA256 de "<timestamp>.<cuerpo>". Verifique as duas coisas: a assinatura e que o relógio não se desviou mais de cinco minutos.

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

As regras de entrega, ditas com clareza para não haver surpresas: uma tentativa, seis segundos de espera e sem novas tentativas. Não seguimos redirecionamentos e recusamos endereços privados, de ligação local e de metadados de nuvem, tanto ao registar o URL como ao resolver o DNS de cada entrega. Se o seu sistema precisa de garantias, use o webhook como aviso e GET /sync/entries com since como rede de segurança: o aviso é uma cortesia, a API é a verdade.

MCP para assistentes de IA

A mesma API está exposta como servidor MCP, o protocolo que os assistentes usam para se ligarem a ferramentas. Serve para perguntar a um assistente que explorações estão atrasadas, quanto custou a campanha ou o que falta preencher antes de uma inspeção.

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

Ferramentas disponíveis: list_farms, list_entries, entry_history, list_groups, group_overview, advisor_portfolio, advisor_pending e record_entry. A última só funciona com chave de escrita, fica marcada no histórico como escrita por API e nunca envia nada à administração.

Porque é que a API não serve para fazer batota

Uma API sobre um registo com valor legal tem de poder ser olhada de frente. Em Espanha, o RD 1054/2022 permite levar o caderno com qualquer sistema informático que cumpra os requisitos do anexo II e seja interoperável com o SIEX, e deixa claro que o responsável pela veracidade é o titular, não o programa. Em Portugal vale o mesmo princípio: o registo é da responsabilidade da exploração. A nossa parte é a integridade, e está escrita no código.

Erros

Sempre {"code":"INT_NNN","message":"…"}, nunca um rastreio. Os que mais vai ver: AUT_003 chave inválida, AUT_004 chave só de leitura, AUT_429 demasiadas tentativas, AUT_503 autenticação indisponível (não é o mesmo que chave errada: volte a tentar), INT_003 URL que não é https, INT_403 operação que exige sessão, INT_404 chave ou webhook que não é seu.

Como se obtém uma chave

A API vem com os planos para empresas e consultoria. Se já tem conta, a chave cria-se na própria app. Se está a avaliar a integração antes de contratar, escreva para support@agrogps.eu a dizer que sistema quer ligar e damos-lhe acesso de teste. A documentação é pública e gratuita: preferimos que a leia antes de pagar.

Começar grátis

Perguntas frequentes

Posso levar o caderno inteiro a partir do meu ERP sem abrir a app? Sim para registar e ler. Não para um envio oficial, que só existe em Espanha e aí exige a sessão de uma pessoa autorizada. É uma decisão deliberada: esse ato tem consequências legais e não deve ser disparado por um processo automático.

Os dados são meus? Sim. A exportação completa é sempre gratuita, também se cancelar, e pela API leva exatamente o mesmo que vê no ecrã, incluindo o histórico e o rasto de alterações.

Há limite de chamadas? Não há quota publicada para o uso normal de um ERP. Testar um webhook está limitado a vinte vezes por utilizador e IP a cada dez minutos, para que ninguém use a função para gerar tráfego.

O que acontece se mudarem a API? A versão vai no URL. Enquanto v1 estiver publicada, não retiramos campos nem mudamos o significado dos que existem; o novo acrescenta-se. Se um dia houver uma v2, conviveriam.

O servidor MCP está no npm? Ainda não. Hoje executa-se a partir do repositório; a publicação ainda está por decidir. A configuração acima é a que vai funcionar no dia em que for publicado.

Isto serve a um consultor com muitos clientes? É para isso que existe advisor/portfolio: uma chamada diz-lhe que explorações estão em dia e quais têm trabalhos incompletos, sem as abrir uma a uma.