Entwicklerdokumentation

REST-API-Zugriff auf Segesio ERP, um deinen Betrieb mit anderen Systemen zu verbinden — Lesen und Schreiben, authentifiziert mit einem API-Key.

Worum es geht

Die Segesio-ERP-API lässt dich die Daten deines Kontos lesen und schreiben — Tätigkeiten, Ausgaben, Betriebsmittel, Ernten und die übrigen Betriebsmodule — direkt aus deinen eigenen Systemen, ohne über die Weboberfläche zu gehen.

Es ist keine Spiegel-API und kein Mock: Ein API-Key mit Schreibrechten ruft genau dieselben Endpunkte auf, die auch die Web-App nutzt, authentifiziert als echter Nutzer deines Kontos. Das ist eine Funktion des Enterprise-Plans.

Authentifizierung

Jede Anfrage trägt den API-Key im Header X-API-Key. Es gibt kein Login und keinen Token, der nach Minuten abläuft — der Key ist bis zu dem Ablaufdatum gültig, das ihm zugewiesen wurde.

X-API-Key: fek_a1b2c3d4e5f6...

Der vollständige Key wird nur einmal angezeigt, im Moment der Erstellung. Bewahre ihn an einem sicheren Ort auf (einem Secrets-Manager, nicht in einem Code-Repository) — wenn du ihn verlierst, musst du einen neuen erzeugen.

Einen Key erzeugen

Ein Nutzer mit Administratorrolle kann Keys unter Einstellungen → API-Keys innerhalb der Anwendung erstellen.

  1. Wähle einen aussagekräftigen Namen (zum Beispiel das System, das ihn nutzen wird).
  2. Wähle die benötigten Scopes aus — markiere nie mehr, als diese Integration tatsächlich braucht.
  3. Wenn ein Scope Schreibrechte umfasst, wähle, welches Teammitglied dieser Key repräsentiert: Schreibvorgänge laufen mit der echten Identität und den echten Berechtigungen dieser Person.
  4. Lege ein Ablaufdatum fest (es gibt einen Standardwert, falls du keinen wählst) und bestätige.

Der vollständige Key erscheint einmalig auf dem Bildschirm, direkt nach der Erstellung. Kopiere ihn, bevor du diese Ansicht schließt.

Scope-Katalog

Jeder Scope folgt demselben Format wie der Rest des Systems: Modul:Aktion. Ein Key kann nie mehr, als der Nutzer, an den er gebunden ist, manuell in der Oberfläche tun könnte.

ModulAnsehenErstellenBearbeitenHinweise
actividades✓✓✓Umfasst auch das Ändern des Status einer Tätigkeit (geplant → abgeschlossen usw.).
insumos✓✓✓
fincas✓✓✓Umfasst auch die Felder (Lotes) jedes Betriebs.
zafras✓✓✓
maquinaria✓✓✓
calibracion✓✓✓
padrones✓✓✓
rotaciones✓✓✓
suelos✓✓✓
recorridas✓✓✓
cosechas✓✓✓
ingresos✓✓✓
gastos✓✓✓Diese Berechtigung aktiviert auch den Beleg-Scan- und Zahlungsabgleich-Ablauf, nicht nur das manuelle Anlegen einer Ausgabe.
vendors✓✓—Ohne Bearbeiten — ein Lieferant kann angesehen und angelegt, aber nicht über die API geändert werden.
documentos✓✓—
trazabilidad✓——Vorerst nur lesend.
finanzas✓——Nur lesend — Finanzprojekte und Finanzierungsquellen.

Die Aktion Löschen steht keinem Key zur Verfügung, in keinem Modul — zum Löschen die normale Oberfläche verwenden.

Lesezugriff ist im Enterprise-Plan enthalten. Schreibzugriff ist eine separate Freischaltung, die unser Team auf Anfrage aktiviert — schreib uns (siehe Support weiter unten), um ihn für dein Konto zu aktivieren.

Eine Anfrage stellen

Alle Endpunkte verwenden denselben Präfix wie die echte Segesio-ERP-API. Ein Beispiel, das Anlegen einer Tätigkeit:

curl -X POST https://api.segesio.com/api/v1/activities \
  -H "X-API-Key: fek_..." \
  -H "Content-Type: application/json" \
  -d '{"lote_id":"...","tipo":"aplicacion","fecha":"2026-09-20"}'

Wenn der Key einen Schreib-Scope hat, wird die angelegte Tätigkeit dem echten Nutzer zugeschrieben, an den der Key gebunden ist — derselbe Wert, der entstünde, hätte diese Person sie über die Web-App eingegeben.

Antwort- und Fehlerformat

Erfolgreiche Antworten liefern die angelegte oder angefragte Ressource als JSON. Ein Fehler — fehlende Berechtigung, ungültige Daten, abgelaufener Key — liefert einen passenden HTTP-Statuscode und einen Body in diesem Format:

{
  "statusCode": 403,
  "message": "API key is missing required scope(s): gastos:crear",
  "error": "Forbidden"
}

Das ist das Format, das das Framework standardmäßig bei den meisten Endpunkten verwendet. Es ist noch nicht in jedem Fall zu 100 % vereinheitlicht — wir weisen darauf hin, damit deine Integration sich nicht auf eine exakte Struktur über statusCode/message hinaus verlässt.

Limits

  • Rate-Limiting pro Key (nicht pro IP-Adresse): Ein Key teilt sich dieselben Limits wie der normale App-Traffic, gruppiert nach dem Key selbst statt nach IP.
  • Jeder Key hat ein verpflichtendes Ablaufdatum — standardmäßig 90 Tage bei jedem Schreib-Scope, 180 Tage bei reinem Lesezugriff. Beim Erstellen kann ein anderer Wert gewählt werden.
  • Bis zu 30 Scopes pro Key.

Leichtgewichtige Alternative: Nur-Lese-API

Wenn du nur eine Handvoll Daten lesen musst — Betriebe, Felder, NDVI, Ernten, Wetter — ohne etwas zu schreiben, gibt es dafür eine einfachere, stabilere API mit diesen Scopes:

  • fincas:read
  • lotes:read
  • ndvi:read
  • harvest:read
  • weather:read

Das ist ein kleinerer, stabilerer Vertrag, nützlich für einfache Integrationen. Er ersetzt nicht den vollständigen Katalog oben, der tatsächlich Schreibzugriff erlaubt.

Bekannte Einschränkungen

  • Die meisten Listen-Endpunkte liefern das vollständige Ergebnis ohne Paginierung — bei großen Datenmengen über die von jedem Endpunkt akzeptierten Parameter filtern.
  • Noch keine ausgehenden Webhooks: Deine Integration muss abfragen (Polling), es gibt keine Möglichkeit, dass Segesio dich über eine Änderung benachrichtigt.
  • Das Fehlerformat ist nicht bei jedem Endpunkt zu 100 % vereinheitlicht — siehe den Hinweis unter Antwort- und Fehlerformat.
  • Keine Key-Rotation ohne Neuerstellung: Um einen Key zu rotieren, einen neuen erstellen und den alten widerrufen.

Support

Brauchst du Schreibzugriff für dein Konto, oder hast du eine konkrete Frage zu einem Endpunkt? Melde dich bei uns.

Kontakt aufnehmen →

Testen Sie Segesio mit echten Daten, ohne Kreditkarte

Gehen Sie über die Tarife, starten Sie Pro für 14 Tage und prüfen Sie, ob das erste Modul, das Sie brauchen, Ihren Betrieb wirklich besser ordnet.

Tarife und Pro-Test ansehen