Partner-API v1 · stabil

agrar online Partner-API

Verbinde dein DMS, CRM, ERP oder Shop-System mit agrar online. Ein REST-Endpoint, 27 Routen, 8 Scopes — in 5 Minuten zum ersten Call.

Quickstart · 5 Minuten

Von 0 auf API in drei Schritten

Keine SDKs, keine Token-Tausch-Tänze. Ein API-Key, ein Header, eine Antwort.

1

API-Key holen

In agrar online einloggen → Optionen → API-Zugänge → „Neuen API-Key erstellen". Scopes pro Key wählen (z.B. nur kunden:read).

Der Key wird genau einmal angezeigt. Format: ak_…. Sicher speichern, nicht ins Git checken.
2

Ersten Request machen

HTTP-GET auf /api/v1/kunden mit dem X-API-Key-Header. Beispiel-Snippets unten in cURL, JavaScript, Python und PHP.

Rate-Limit: 10.000 Anfragen/Tag pro Key. Bei Überschreitung kommt 429.
3

Antwort interpretieren

Jede Liste kommt als { data: [...], count: N }. Einzel-Resources als reines Objekt. Fehler als { error: 'CODE', message: '…' }.

Bei 401 ist der Key falsch, bei 403 fehlt der Scope, bei 404 existiert die Resource nicht.
curl -X GET "https://api.agrar.online/api/v1/kunden?limit=10" \
  -H "X-API-Key: ak_dein_api_key_hier" \
  -H "Accept: application/json"
const res = await fetch('https://api.agrar.online/api/v1/kunden?limit=10', {
  headers: {
    'X-API-Key': process.env.AGRAR_API_KEY,
    'Accept': 'application/json',
  },
});
const json = await res.json();
console.log(json.data); // Array mit den ersten 10 Kunden
import os, requests

r = requests.get(
    "https://api.agrar.online/api/v1/kunden",
    params={"limit": 10},
    headers={"X-API-Key": os.environ["AGRAR_API_KEY"]},
    timeout=15,
)
r.raise_for_status()
for kunde in r.json()["data"]:
    print(kunde["kundennummer"], kunde["name"])
<?php
$ch = curl_init("https://api.agrar.online/api/v1/kunden?limit=10");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "X-API-Key: " . getenv("AGRAR_API_KEY"),
        "Accept: application/json",
    ],
]);
$json = json_decode(curl_exec($ch), true);
print_r($json["data"]);

Beispiel-Antwort

{
  "data": [
    {
      "id": 42,
      "kundennummer": "K-1042",
      "name": "Musterhof Schmidt GbR",
      "typ": "VK",
      "email": "info@musterhof.example",
      "telefon": "+49 5021 123456",
      "strasse": "Dorfstraße 12",
      "plz": "31515",
      "ort": "Wunstorf",
      "land": "DE",
      "aktiv": true
    }
  ],
  "count": 1
}
Was du damit baust

Use Cases — aus der Praxis

Die häufigsten Integrations-Muster die Partner mit der API bauen. Die Endpoint-Patterns unten sind in der interaktiven Doku verlinkt.

👥

Kunden synchronisieren

Stammdaten zwischen ERP, CRM oder Shop-System abgleichen. Auto-Pricing, kundennr-Mapping und Idempotenz inklusive.

GET /kundenPOST /kundenPUT /kunden/{id}
📄

Belege als PDF abholen

Finalisierte Rechnungen und Lieferscheine als archiviertes PDF (DMS-Pattern) — plus Polling-Endpoint fuer neue Dokumente.

GET /belege/{id}/pdfGET /dokumente?since=...
📥

Wareneingang automatisch buchen

EL/ER-Belege per POST anlegen — Charge-Anlage, MHD, Herkunft, Lager-Buchung greifen automatisch. Mit external_ref idempotent.

POST /belege (Typ EL/ER)
📊

Bestaende in Echtzeit abfragen

Charge-genaue Bestaende pro Artikel oder Partner. Inklusive Filter auf Bestand>0 und Genealogie-Tree.

GET /chargen?mit_bestand=true
🚚

Annahmescheine fuers Lager

Externe Waage oder Spedition pingt direkt rein — Annahmescheine landen im Rohwaren-Modul und werden vom Personal weiter bearbeitet.

POST /annahmescheineGET /wiegungen
📑

Kontrakte ueberwachen

Status, Restmenge und Faelligkeiten von Kontrakten in BI- oder Reporting-Tools ziehen — read-only und ohne Risiko.

GET /kontrakte
🏭

Produktionsauftraege erfassen

PA-Anlage mit Inputs/Outputs aus dem MES oder Rezeptur-System. Genealogie + Bewertungs-Anteile kommen automatisch.

POST /produktionsauftraege
🌍

Stammdaten-Lookups

Laender-Codes, Steuersaetze oder Artikelgruppen fuer Frontend-Dropdowns — leichtgewichtige Read-Only-Endpoints.

GET /artikelgruppenGET /laender
Authentifizierung & Limits

Sicher und transparent

API-Key per Header, klare Scopes pro Zweck, harte Tageslimits — eine pragmatische OAuth-Alternative.

🔑 Authentifizierung

Jeder Request braucht den Header:

X-API-Key: ak_xxxxxxxxxxxxxxxx
  • Key wird im SHA-256-Hash in der DB gespeichert
  • Pro Key: Firma + Scopes + Rate-Limit-Counter
  • Sofort deaktivierbar im SU-Portal
  • Audit-Log pro Request für 90 Tage

Rate Limits

Pro API-Key:

  • 10.000 Anfragen/Tag — reset um 00:00 UTC
  • Bei Überschreitung: 429 Rate-Limited
  • Bei kritischen Endpoints zusätzlich IP-Limit (10/min)

Für höhere Limits oder Enterprise-Pakete: support@agrar.online

🎯 Scopes — Pro Key wählbar

Jeder Scope schaltet eine Endpoint-Gruppe frei. Least-Privilege: nur das gewähren, was die Integration wirklich braucht.

kunden:read Kunden-Stammdaten lesen
kunden:write Kunden anlegen / aktualisieren
artikel:read Artikel-Stamm + Preise lesen
belege:read Belege + archivierte PDFs lesen
belege:write Belege anlegen / aktualisieren (alle Typen)
chargen:read Chargen + Bestaende lesen
chargen:write Chargen direkt anlegen (Migration)
dokumente:write Anhaenge an Kunden / Artikel hochladen
Referenz

Alle Endpoints (interaktiv)

Mit dem „Authorize"-Button oben rechts deinen API-Key eintragen, dann kannst du jeden Endpoint direkt aus dem Browser ausprobieren.