AGRARMONITOR
API docs by Redocly

AGRARMONITOR API (1.0.0)

Download OpenAPI specification:

Sie dient zum Datenaustausch zwischen verschiedenen Programmen im landwirtschaftlichen Bereich und der Betriebsorganisationssoftware Agrarmonitor der betriko GmbH.

API nutzen

Der Zugang zur API wird individuell freigeschaltet. Wenden Sie sich dazu gerne an unseren Ansprechpartner Pascal Bemmann.

API URL

Auf die API-Adresse kann ausschließlich per SSL zugegriffen werden.

https://api.agrarmonitor.de

HTTP Verben

Wir nutzen HTTP Verben.

Verb Beschreibung
GET Gibt einen oder mehrere Datensätze zurück. Bei Erfolg wird mit HTTP Status Code 200 geantwortet.
POST Erstellt einen Datensatz. Bei Erfolg wird mit HTTP Status Code 201 geantwortet.
PUT Aktualisiert einen Datensatz. Bei Erfolg wird mit HTTP Status Code 200 geantwortet.
DELETE Löscht einen Datensatz. Bei Erfolg wird mit HTTP Status Code 200 oder 204 geantwortet.

Status Codes

Die API wird mit folgenden Status Codes antworten:

Code Beschreibung
200 Success
201 Success - new resource created (POST)
204 Success - no content to return (DELETE)
400 Bad Request - request couldn't be parsed
401 Unauthorized - missing API-Token
403 Forbidden - invalid API-Token or unapproved app
404 Not Found - method exists, but no record found
422 Unprocessable Entity - validation errors
429 Rate Limit Exceeded
500 Server Error - please open a support issue

Benötigte Header

Der Accept-Header wird benötigt, damit die Daten im richtigen Format ausgegeben werden. Der Authorization-Header ist optional. Der API-Token kann auch als GET-Parameter übergeben werden.

Header Value
Accept application/json
Authorization Bearer [api_token]

Autorisierung

Der Zugriff auf die API erfolgt per API-Token, den Sie von einem Agrarmonitor Benutzer erhalten können. Dabei gibt es verschiedene Typen von API-Token:

Typ Beschreibung
System Zugriff auf alle Endpunkte und Datensätze eines Agrarmonitor Systems
Kunde Zugriff auf Datensätze des Kunden, z.B. Ackerschlagkartei. In einem Agrarmonitor-System werden verschiedene Kunden (Geschäftspartner des Inhabers des Agrarmonitor-Systems) verwaltet, Ackerschläge sind jeweils einem Kunden zugeordnet.
Maschine Senden von Maschinendaten und -beschreibung
Waage Auslösen von Wägungen der angebundenen Waage

Rate Limiting

Die Anzahl der Anfragen ist auf 60 Anfragen pro Minute begrenzt. Gezählt wird je API-Token; bei nicht authentifizierten Anfragen je IP-Adresse.

Jede Antwort enthält den aktuellen Stand des Kontingents:

Header Beschreibung
X-RateLimit-Limit Maximale Anzahl an Anfragen pro Minute
X-RateLimit-Remaining Verbleibende Anfragen im aktuellen Zeitfenster

Ist das Kontingent erschöpft, antwortet die API mit HTTP Status Code 429 und zusätzlich diesen Headern:

Header Beschreibung
Retry-After Sekunden bis zur nächsten erlaubten Anfrage
X-RateLimit-Reset Unix-Zeitstempel, ab dem wieder Anfragen möglich sind 
{
    "message": "Too Many Attempts."
}

Seiten

Die Antworten der meisten GET Anfragen sind auf mehrere Seiten aufgeteilt. Es werden standardmäßig 15 Datensätze pro Seite ausgegeben.

{
    "data": [
        {
            "...": "..."
        }
    ],
    "links": {
        "first": "https://api.agrarmonitor.de/v1/ackerschlaege?page=1",
        "last": "https://api.agrarmonitor.de/v1/ackerschlaege?page=12",
        "prev": null,
        "next": "https://api.agrarmonitor.de/v1/ackerschlaege?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 12,
        "path": "https://api.agrarmonitor.de/v1/ackerschlaege",
        "per_page": 15,
        "to": 15,
        "total": 18975
    }
}

Ackerschläge

Alle Ackerschläge abrufen

Authorizations:
BearerAuth
query Parameters
ist_aktiv
integer
Default: 1
Enum: -1 0 1

Nach Aktiv-Status filtern: 1 = nur aktive, 0 = nur inaktive, -1 = keine Einschränkung. Ohne Angabe werden nur aktive Ackerschläge geliefert.

kunde_id
integer

Nach einem Kunden filtern

erntejahr
integer

Jahr der Abernte (0 = noch nicht beendet)

page
integer >= 1
Default: 1

Abzurufende Seite. Werte kleiner als 1 werden auf 1 zurückgesetzt. Liegt die angeforderte Seite hinter der letzten, wird die letzte Seite geliefert.

per_page
integer >= 1
Default: 15

Anzahl der Einträge je Seite. Werte kleiner als 1 werden auf den Standardwert zurückgesetzt.

Responses

Response Schema: application/json
object
object
Array of objects (Ackerschlag)

Response samples

Content type
application/json
{}

Ackerschlag abrufen

Authorizations:
BearerAuth
path Parameters
id
required
integer

ID des Ackerschlags

Responses

Response Schema: application/json
object (Ackerschlag)

Response samples

Content type
application/json
{
  • "data": {
    • "id": 83934,
    • "nummer": "12-3 b",
    • "bezeichnung": "Am Hof",
    • "gueltigkeit_start": "2014-02-15",
    • "gueltigkeit_ende": "0000-00-00",
    • "groesse_in_ha": 3.566,
    • "entfernung_in_km": 0.482,
    • "erntejahr": 2021,
    • "ist_aktiv": true,
    • "ist_spur": false,
    • "kunde": {
      }
    }
}

Ackerschlagkartei

Ackerschläge zusammen mit ihren Ackerschlaganfahrten (Bearbeitungen inkl. Leistung, Mitarbeiter und Artikelbewegungen).

Alle Ackerschläge mit Ackerschlaganfahrten auflisten

Authorizations:
BearerAuth
query Parameters
ist_aktiv
boolean
Example: ist_aktiv=true

Aktive oder inaktive Ackerschläge filtern

kunde_id
integer
Example: kunde_id=12345

Nach einem Kunden filtern

erntejahr
integer
Example: erntejahr=2022

Jahr, in dem der Ackerschlag abgeerntet wird oder wurde. Ist 0, wenn die Frucht nicht beendet ist.

page
integer >= 1
Default: 1

Abzurufende Seite. Werte kleiner als 1 werden auf 1 zurückgesetzt. Liegt die angeforderte Seite hinter der letzten, wird die letzte Seite geliefert.

per_page
integer >= 1
Default: 15

Anzahl der Einträge je Seite. Werte kleiner als 1 werden auf den Standardwert zurückgesetzt.

Responses

Response Schema: application/json
object
object
Array of objects (AckerschlagWithKartei)

Response samples

Content type
application/json
{
  • "data": [
    • {
      }
    ],
  • "links": {},
  • "meta": {}
}

Einen Ackerschlag und alle Ackerschlaganfahrten zu diesem Ackerschlag anzeigen

Authorizations:
BearerAuth
path Parameters
id
required
integer
Example: 83934

ID des Ackerschlags

query Parameters
auftrag_abgerechnet
integer
Example: auftrag_abgerechnet=0

Nur Anfahrten aus Aufträgen mit diesem Abrechnungsstatus (0 = nicht abgerechnet, 1 = abgerechnet).

auftrag_tage_nach_beendet
integer
Example: auftrag_tage_nach_beendet=30

Nur Anfahrten aus Aufträgen, die vor höchstens so vielen Tagen beendet wurden.

auftrag_gruene_haken
string
Example: auftrag_gruene_haken=1

Nur Anfahrten aus Aufträgen mit den angegebenen grünen Haken (Freigabestatus des Auftrags).

Responses

Response Schema: application/json
object (AckerschlagWithKartei)

Response samples

Content type
application/json
{
  • "data": {
    • "id": 83934,
    • "nummer": "12-3 b",
    • "bezeichnung": "Am Hof",
    • "gueltigkeit_start": "2014-02-15",
    • "gueltigkeit_ende": "0000-00-00",
    • "groesse_in_ha": 3.566,
    • "entfernung_in_km": 0.482,
    • "erntejahr": 2021,
    • "ist_aktiv": true,
    • "ist_spur": false,
    • "kunde": {
      },
    • "ackerschlag_anfahrten": [
      ]
    }
}

Artikel

Alle Artikel abrufen

Authorizations:
BearerAuth
query Parameters
page
integer >= 1
Default: 1

Abzurufende Seite. Werte kleiner als 1 werden auf 1 zurückgesetzt. Liegt die angeforderte Seite hinter der letzten, wird die letzte Seite geliefert.

per_page
integer >= 1
Default: 15

Anzahl der Einträge je Seite. Werte kleiner als 1 werden auf den Standardwert zurückgesetzt.

Responses

Response Schema: application/json
object
object
Array of objects (Artikel)

Response samples

Content type
application/json
{}

Artikel abrufen

Authorizations:
BearerAuth
path Parameters
id
required
integer

ID des Artikels

Responses

Response Schema: application/json
object (Artikel)

Response samples

Content type
application/json
{
  • "data": {
    • "id": 83934,
    • "nummer": "12-3 b",
    • "bezeichnung": "Am Hof",
    • "indikation": "Herbizid",
    • "zulassungsnummer": "034107-00",
    • "einheit": {
      },
    • "typ": {
      }
    }
}

Aufträge

Ein Arbeitseinsatz eines Mitarbeiters mit einer Maschinenkombination

Alle Aufträge abrufen

Authorizations:
BearerAuth
query Parameters
ackerschlag_id
integer
kunde_ids
Array of integers
leistungsnummern
Array of strings
zeitpunkt_ab
string

Format: Y-m-d H:i:s

zeitpunkt_bis
string

Format: Y-m-d H:i:s

page
integer >= 1
Default: 1

Abzurufende Seite. Werte kleiner als 1 werden auf 1 zurückgesetzt. Liegt die angeforderte Seite hinter der letzten, wird die letzte Seite geliefert.

per_page
integer >= 1
Default: 15

Anzahl der Einträge je Seite. Werte kleiner als 1 werden auf den Standardwert zurückgesetzt.

Responses

Response Schema: application/json
object
object
Array of objects (Auftrag)

Response samples

Content type
application/json
{
  • "data": [
    • {
      }
    ],
  • "links": {},
  • "meta": {}
}

Auftrag abrufen

Authorizations:
BearerAuth
path Parameters
id
required
integer

Responses

Response Schema: application/json
object (Auftrag)

Response samples

Content type
application/json
{
  • "data": {
    • "id": 83934,
    • "zeitpunkt_auftrag_start": "2022-09-29 12:37:00",
    • "zeitpunkt_arbeit_start": "2022-09-29 13:37:00",
    • "zeitpunkt_arbeit_ende": "2022-09-29 14:37:00",
    • "zeitpunkt_auftrag_ende": "2022-09-29 15:37:00"
    }
}

Kontrakte

Alle offenen Kontrakte abrufen

Authorizations:
BearerAuth

Responses

Response Schema: application/json
Array of objects (Deliverycontract)

Response samples

Content type
application/json
{
  • "data": [
    • {
      }
    ]
}

Kunden / Lieferanten

Alle Kunden abrufen

Authorizations:
BearerAuth
query Parameters
page
integer >= 1
Default: 1

Abzurufende Seite. Werte kleiner als 1 werden auf 1 zurückgesetzt. Liegt die angeforderte Seite hinter der letzten, wird die letzte Seite geliefert.

per_page
integer >= 1
Default: 15

Anzahl der Einträge je Seite. Werte kleiner als 1 werden auf den Standardwert zurückgesetzt.

Responses

Response Schema: application/json
object
object
Array of objects (Kunde)

Response samples

Content type
application/json
{}

Kunde / Lieferant abrufen

Authorizations:
BearerAuth
path Parameters
id
required
integer

Responses

Response Schema: application/json
object (Kunde)

Response samples

Content type
application/json
{
  • "data": {
    • "id": 48759,
    • "kundennummer": "20022",
    • "firma": "Max Mustermann GmbH",
    • "anrede": "Herr",
    • "vorname": "Max",
    • "nachname": "Mustermann",
    • "strasse": "Hauptstraße 1",
    • "plz": "12345",
    • "ort": "Berlin",
    • "land_iso_3166": "DE",
    • "email": "max@mustermann.de",
    • "ist_aktiv": true,
    • "hit_zid_nummer": "27605LWK12345678"
    }
}

Maschinen

Maschine registrieren

Authorizations:
BearerAuth
Request Body schema: application/json
required
hersteller_token
required
string

Hersteller Token (von Agrarmonitor)

provider_id
required
string

URN/ID der Maschine beim Hersteller

Array of objects <= 2 items

Responses

Response Schema: application/json
success
boolean
access_token
string

Request samples

Content type
application/json
{
  • "hersteller_token": "4E11067D-15FC-B3BB-6007-C2AE6F5E7E36",
  • "provider_id": "urn:betriko:123456",
  • "maschinen": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "access_token": "g7B9uB1CraRw89Kd36rTSt5j40QsYkhnYrmi8nr0w1HlgHHX3XnKqPuJZ1Yy"
}

Maschinendaten senden

Authorizations:
BearerAuth
Request Body schema: application/json
required
provider_id
required
string

URN/ID der Maschine beim Hersteller

required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "provider_id": "urn:betriko:123456",
  • "data": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "success": true
}

Waage

Befehle abrufen

Authorizations:
BearerAuth

Responses

Response Schema: application/json
id
integer
bga_id
integer
name
string
object
erstellt_am
string
antwort_am
string
ausgefuehrt_am
string
hat_fehler
integer
antwort
object or null
abgeschlossen
integer

Response samples

Content type
application/json
{
  • "id": 246,
  • "bga_id": 1,
  • "name": "Waegung_ausloesen",
  • "data": {
    • "bga_id": 1,
    • "bga_kennung": "001",
    • "kennzeichen": "BETRIKO-200-4",
    • "hat_leergewicht": false,
    • "leergewicht": 0,
    • "ist_fremdwaegung": false,
    • "taste": 3,
    • "betriko_waage": 1,
    • "artikel": {
      },
    • "lagerplatz": {
      }
    },
  • "erstellt_am": "2021-04-15 05:32:48",
  • "antwort_am": "-0001-11-30 00:00:00",
  • "ausgefuehrt_am": "-0001-11-30 00:00:00",
  • "hat_fehler": 0,
  • "antwort": null,
  • "abgeschlossen": 0
}

Befehl aktualisieren

Authorizations:
BearerAuth
path Parameters
id
required
integer
Request Body schema: application/json
required
hat_fehler
integer
object

Responses

Response Schema: text/html
string

Request samples

Content type
application/json
{
  • "hat_fehler": 0,
  • "antwort": {
    • "fehler": 0,
    • "datum": "19.02.21",
    • "zeit": "10:27",
    • "lfdnr": 17,
    • "nettogewicht": 34511,
    • "einheit": "kg",
    • "leergewicht": null,
    • "kennzeichen": "BETRIKO-200-1",
    • "artikel": null,
    • "waegungskennzeichen": "E",
    • "datei": "bilder/001-17.jpg",
    • "datei_hinten": "bilder/001-17_hinten.jpg"
    }
}

Response samples

Content type
text/html
Antwort von API {waegungskennzeichen}