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

Um die API nutzen zu können, müssen Sie sich registrieren. Melden Sie sich dafür bei uns.

Kontakt

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

{"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": {"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"
}
}
],
"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": 18
}
}

Ackerschlag abrufen

Authorizations:

BearerAuth

path Parameters

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": {"id": 48759,
"firma": "Max Mustermann GmbH"
}
}
}

Alle Ackerschläge mit Ackerschlaganfahrten auflisten

Authorizations:

BearerAuth

query Parameters

ist_aktiv	boolean
kunde_id	integer
erntejahr	integer
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": [{"id": 83934,
"bezeichnung": "Am Hof",
"ackerschlag_anfahrten": [{"id": 83934,
"zeitpunkt_start": "2019-10-07 10:02:00",
"bearbeitete_flaeche_in_ha": 12.34,
"auftrag_id": 12345
}
]
}
],
"links": {"first": "https://api.agrarmonitor.de/v1/ackerschlaege/ackerschlagkartei?page=1",
"last": "https://api.agrarmonitor.de/v1/ackerschlaege/ackerschlagkartei?page=12",
"prev": null,
"next": "https://api.agrarmonitor.de/v1/ackerschlaege/ackerschlagkartei?page=2"
},
"meta": {"current_page": 1,
"from": 1,
"last_page": 12,
"path": "https://api.agrarmonitor.de/v1/ackerschlaege/ackerschlagkartei",
"per_page": 15,
"to": 15,
"total": 18975
}
}

Einen Ackerschlag mit allen Ackerschlaganfahrten anzeigen

Authorizations:

BearerAuth

path Parameters

required

integer

query Parameters

auftrag_abgerechnet	integer Anfahrten nach Abrechnungsstatus des Auftrags einschränken
auftrag_tage_nach_beendet	integer Nur Anfahrten aus Aufträgen, die vor höchstens so vielen Tagen beendet wurden
auftrag_gruene_haken	string Anfahrten nach den grünen Haken des Auftrags einschränken

Responses

Response Schema: application/json

object (AckerschlagWithKartei)

Response samples

Content type

application/json

{"data": {"id": 83934,
"bezeichnung": "Am Hof",
"ackerschlag_anfahrten": [{"id": 83934,
"zeitpunkt_start": "2019-10-07 10:02:00",
"bearbeitete_flaeche_in_ha": 12.34,
"auftrag_id": 12345
}
]
}
}

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

{"data": [{"id": 83934,
"nummer": "12-3 b",
"bezeichnung": "Am Hof",
"indikation": "Herbizid",
"zulassungsnummer": "034107-00",
"einheit": {"id": 1,
"bezeichnung_kurz": "kg",
"bezeichnung": "Kilogramm"
},
"typ": {"id": 3,
"bezeichnung": "Pflanzenschutzmittel"
}
}
],
"links": {"first": "https://api.agrarmonitor.de/v1/artikel?page=1",
"last": "https://api.agrarmonitor.de/v1/artikel?page=12",
"prev": null,
"next": "https://api.agrarmonitor.de/v1/artikel?page=2"
},
"meta": {"current_page": 1,
"from": 1,
"last_page": 12,
"path": "https://api.agrarmonitor.de/v1/artikel",
"per_page": 15,
"to": 15,
"total": 18975
}
}

Artikel abrufen

Authorizations:

BearerAuth

path Parameters

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": {"id": 1,
"bezeichnung_kurz": "kg",
"bezeichnung": "Kilogramm"
},
"typ": {"id": 3,
"bezeichnung": "Pflanzenschutzmittel"
}
}
}

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": [{"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",
"ackerschlaege": [{"id": 83934,
"bezeichnung": "Am Hof",
"ackerschlag_anfahrt": {"id": 83934,
"ackerschlagzeit_effektiv_in_industriestunden": 1.23,
"bearbeitete_flaeche_in_ha": 1.23,
"zeitpunkt_start": "2022-09-29 12:37:00",
"zeitpunkt_ende": "2022-09-29 13:37:00"
}
}
],
"artikel_bewegungen": [ ],
"leistungsempfaenger": {"id": 48759,
"firma": "Max Mustermann GmbH"
},
"leistung": {"id": 121001,
"nummer": "121001",
"bezeichnung": "Aussaat konventionell"
},
"rechnungsempfaenger": {"id": 48759,
"firma": "Max Mustermann GmbH"
},
"standorte": [{"lat": 51.875747,
"lng": 12.901292,
"zeitpunkt": "2022-09-29 12:37:17"
}
],
"zugmaschine": {"id": 1,
"nummer": "Z-123",
"bezeichnung": "Zugmaschine"
}
}
],
"links": {"first": "https://api.agrarmonitor.de/v1/auftraege?page=1",
"last": "https://api.agrarmonitor.de/v1/auftraege?page=12",
"prev": null,
"next": "https://api.agrarmonitor.de/v1/auftraege?page=2"
},
"meta": {"current_page": 1,
"from": 1,
"last_page": 12,
"path": "https://api.agrarmonitor.de/v1/auftraege",
"per_page": 15,
"to": 15,
"total": 18975
}
}

Auftrag abrufen

Authorizations:

BearerAuth

path Parameters

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": [{"UUID": "0191746e-183c-7c58-a851-c48e61033ee5",
"timestamp": 1694037600,
"status": "Offen",
"internalNumber": "ABC-123",
"externalNumber": "ABC-123",
"deliveryPeriodStart": 1694037600,
"deliveryPeriodEnd": 1694037600,
"type": "sales",
"quantity": 123.45,
"openQuantity": 12.34,
"purchasePrice": 123.45,
"sellingPrice": 234.56,
"customer": {"UUID": "0191746e-183c-7c58-a851-c48e61033ee5",
"name": "Max Mustermann GmbH",
"number": "ABC-123",
"street": "Hauptstraße 1",
"zip": "12345",
"city": "Berlin",
"countryISO3166": "DE"
},
"company": {"name": "Max Mustermann GmbH",
"street": "Hauptstraße 1",
"zip": "12345",
"city": "Berlin",
"countryISO3166": "DE"
},
"commodity": {"UUID": "0191746e-183c-7c58-a851-c48e61033ee5",
"name": "Kartoffeln",
"unit": {"abbreviation": "t",
"baseUnit": {"abbreviation": "t"
}
}
},
"notes": [{"timestamp": 1675261920,
"content": "Dies ist eine Notiz",
"name": "Mustermann, Max"
}
]
}
]
}

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

{"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"
}
],
"links": {"first": "https://api.agrarmonitor.de/v1/kunden?page=1",
"last": "https://api.agrarmonitor.de/v1/kunden?page=12",
"prev": null,
"next": "https://api.agrarmonitor.de/v1/kunden?page=2"
},
"meta": {"current_page": 1,
"from": 1,
"last_page": 12,
"path": "https://api.agrarmonitor.de/v1/kunden",
"per_page": 15,
"to": 15,
"total": 18975
}
}

Kunde / Lieferant abrufen

Authorizations:

BearerAuth

path Parameters

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

Payload

Content type

application/json

{"hersteller_token": "4E11067D-15FC-B3BB-6007-C2AE6F5E7E36",
"provider_id": "urn:betriko:123456",
"maschinen": [{"eigenschaften": {"bezeichnung": "Maschine XYZ",
"nummer": "123-b 4",
"baujahr": 2022,
"seriennummer": "ABCD-123456",
"leergewicht_in_kg": 12345,
"ist_zugmaschine": true,
"isobus_device_designator": "ISOBUS Maschinen Bezeichnung",
"isobus_device_serial_number": "ISOBUS Maschinen Seriennummer",
"individuell": [{"bezeichnung": "Hersteller",
"wert": "betriko GmbH"
}
]
},
"zuordnungen": [{"value_token": "123-b 4",
"value_bezeichnung": "Betriebsstunden",
"value_absolut": true,
"einheit_anzeige_kurz": "h",
"umrechnungsfaktor": 1,
"versatz": 0,
"anzahl_nachkommastellen": 1,
"ddi": 123
}
]
}
]
}

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

Payload

Content type

application/json

{"provider_id": "urn:betriko:123456",
"data": [{"timestamp": "2021-10-29T12:34:56Z",
"value_token": "ddi_493",
"value": "1234,56",
"value_name": "Betriebsstunden",
"value_absolut": true
}
]
}

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": {"id": 0,
"bezeichnung": ""
},
"lagerplatz": {"id": 0,
"bezeichnung": ""
}
},
"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

required

integer

Request Body schema: application/json
required

hat_fehler	integer
	object

Responses

Response Schema: text/html

string

Request samples

Payload

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}