{"openapi":"3.0.3","info":{"title":"agrar online Partner-API","version":"1.0.0","description":"Die agrar online Partner-API ermöglicht externen Systemen (DMS, CRM, ERP etc.) den kontrollierten Zugriff auf Ihre Daten.\n\n**Auth:** X-API-Key Header. Verwaltung unter Optionen → API-Zugänge.\n\n**Mandantentrennung:** Jeder Key ist exklusiv einer Firma zugeordnet.\n\n**Rate Limit:** 10.000 Anfragen/Tag.","contact":{"name":"agrar online Support","url":"https://agrar.online"}},"servers":[{"url":"https://api.agrar.online","description":"agrar online Produktion"},{"url":"https://api.agrar.dev","description":"agrar.dev (DEV)"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API-Key aus Optionen → API-Zugänge (Format: ak_...)"}},"schemas":{"Kunde":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"kundennr":{"type":"string","description":"Kundennummer (mandantenweit eindeutig)"},"name":{"type":"string"},"nachname_firma":{"type":"string"},"anrede":{"type":"string"},"vorname":{"type":"string"},"email":{"type":"string"},"telefon":{"type":"string"},"telefon2":{"type":"string"},"strasse":{"type":"string"},"plz":{"type":"string"},"ort":{"type":"string"},"staat":{"type":"string","description":"ISO-3166-1-alpha-2-Laendercode (z.B. \"DE\")"},"status":{"type":"string"},"partner_typen":{"type":"array","items":{"type":"string"},"description":"Rollen des Partners, z.B. [\"kunde\",\"lieferant\"]"},"zahlungsziel_tage":{"type":"integer","format":"int32"},"ust_id":{"type":"string"},"skonto_tage":{"type":"integer","format":"int32"},"skonto_prozent":{"type":"string","format":"decimal"}}},"KundeListe":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Kunde"}},"count":{"type":"integer"}}},"Artikel":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"artikelnummer":{"type":"string"},"artikelnr":{"type":"string"},"bezeichnung":{"type":"string"},"bezeichnung2":{"type":"string"},"einheit":{"type":"string"},"preis":{"type":"string","format":"decimal","description":"VK-Preis (netto), Dezimalzahl als String"},"ep_netto":{"type":"string","format":"decimal"},"mwst_satz":{"type":"string","format":"decimal"},"ean":{"type":"string"},"artikelgruppe_id":{"type":"integer","format":"int32"},"status":{"type":"string"},"chargenpflichtig":{"type":"boolean"},"langtext":{"type":"string"},"gruppe":{"type":"string","description":"Name der Artikelgruppe (JOIN)"}}},"ArtikelListe":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Artikel"}},"count":{"type":"integer"}}},"Artikelgruppe":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"name":{"type":"string"},"kuerzel":{"type":"string"},"nummer":{"type":"integer","format":"int32"},"mwst_satz":{"type":"string","format":"decimal"}}},"ArtikelgruppeListe":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Artikelgruppe"}},"count":{"type":"integer"}}},"BelegPosition":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"beleg_id":{"type":"integer","format":"int32"},"artikel_id":{"type":"integer","format":"int32"},"bezeichnung":{"type":"string"},"bezeichnung2":{"type":"string"},"langtext":{"type":"string"},"menge":{"type":"string","format":"decimal"},"einheit":{"type":"string"},"einzelpreis":{"type":"string","format":"decimal"},"ep_netto":{"type":"string","format":"decimal"},"mwst_satz":{"type":"string","format":"decimal"},"gesamtpreis":{"type":"string","format":"decimal"},"rabatt_prozent":{"type":"string","format":"decimal"},"position":{"type":"integer","format":"int32"},"charge_id":{"type":"integer","format":"int32"},"kontrakt_id":{"type":"string","format":"uuid"},"kontrakt_position_id":{"type":"string","format":"uuid"},"kostenstelle":{"type":"string"},"niederlassung_id":{"type":"integer","format":"int32"},"lagerhalle_id":{"type":"integer","format":"int32"},"artikel_name":{"type":"string","description":"Artikel-Bezeichnung (JOIN)"}}},"Beleg":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"beleg_nummer":{"type":"string"},"beleg_typ":{"type":"string","description":"Belegart-Kuerzel (z.B. VR/ER/VL/EL)"},"status":{"type":"string"},"beleg_datum":{"type":"string","format":"date-time"},"lieferdatum":{"type":"string","format":"date-time"},"leistung_von":{"type":"string","format":"date-time"},"leistung_bis":{"type":"string","format":"date-time"},"summe_netto":{"type":"string","format":"decimal"},"summe_mwst":{"type":"string","format":"decimal"},"summe_brutto":{"type":"string","format":"decimal"},"kunde_id":{"type":"integer","format":"int32"},"notizen":{"type":"string"},"zahlungsziel_tage":{"type":"integer","format":"int32"},"zahlungsbedingung":{"type":"string"},"skonto_tage":{"type":"integer","format":"int32"},"skonto_prozent":{"type":"string","format":"decimal"},"external_ref":{"type":"string","description":"Externe Referenz (Idempotenz-Schluessel bei Beleg-Anlage)"},"fremdbelegnummer":{"type":"string"},"ist_gutschrift":{"type":"boolean"},"lieferadresse_id":{"type":"string","format":"uuid"},"liefertermin":{"type":"string","format":"date-time"},"kontaktperson":{"type":"string"},"niederlassung_id":{"type":"integer","format":"int32"},"lagerhalle_id":{"type":"integer","format":"int32"},"pdf_url":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"kunden_name":{"type":"string","description":"Kundenname (JOIN)"},"positionen":{"type":"array","items":{"$ref":"#/components/schemas/BelegPosition"},"description":"Positionen — nur im Detail (/belege/{id})"}}},"BelegListe":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Beleg"}},"count":{"type":"integer"}}},"Kontrakt":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kontrakt_nr":{"type":"string"},"kontrakt_typ":{"type":"string"},"partner_id":{"type":"integer","format":"int32"},"gueltig_von":{"type":"string","format":"date-time"},"gueltig_bis":{"type":"string","format":"date-time"},"erfassungsdatum":{"type":"string","format":"date-time"},"gesamtmenge":{"type":"string","format":"decimal"},"gesamtmenge_einheit":{"type":"string"},"mengenart":{"type":"string"},"paritat":{"type":"string"},"zahlungsbedingung":{"type":"string"},"erntejahr":{"type":"integer","format":"int32"},"erledigt":{"type":"boolean"},"notizen":{"type":"string"},"referenz":{"type":"string"},"partner_name":{"type":"string","description":"Partnername (JOIN)"}}},"KontraktListe":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Kontrakt"}},"count":{"type":"integer"}}},"Charge":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"charge_nr":{"type":"string"},"fremde_charge_nr":{"type":"string"},"mhd":{"type":"string","format":"date-time","description":"Mindesthaltbarkeitsdatum"},"herkunftsland":{"type":"string"},"einheit":{"type":"string"},"eingang_menge":{"type":"string","format":"decimal"},"eingang_ep":{"type":"string","format":"decimal"},"eingang_quelle":{"type":"string"},"eingang_beleg_id":{"type":"string"},"artikel_id":{"type":"integer","format":"int32"},"partner_id":{"type":"integer","format":"int32"},"artikel_bezeichnung":{"type":"string"},"artikelnr":{"type":"string"},"partner_name":{"type":"string"},"bestand":{"type":"string","format":"decimal","description":"Aktueller Bestand (Summe der Bewegungen)"}}},"Wiegung":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"wiegeschein_nr":{"type":"string"},"status":{"type":"string"},"richtung":{"type":"string","description":"eingang / ausgang"},"kennzeichen":{"type":"string"},"fahrer":{"type":"string"},"gewicht_erst_kg":{"type":"string","format":"decimal"},"gewicht_zweit_kg":{"type":"string","format":"decimal"},"gewicht_netto_kg":{"type":"string","format":"decimal"},"ts_erst":{"type":"string","format":"date-time"},"ts_zweit":{"type":"string","format":"date-time"},"partner_id":{"type":"integer","format":"int32"},"artikel_id":{"type":"integer","format":"int32"},"charge_id":{"type":"integer","format":"int32"},"niederlassung_id":{"type":"integer","format":"int32"},"lagerhalle_id":{"type":"integer","format":"int32"},"kontrakt_id":{"type":"string","format":"uuid"},"beleg_id":{"type":"integer","format":"int32"},"partner_name":{"type":"string"},"artikel_bezeichnung":{"type":"string"},"charge_nr":{"type":"string","description":"Charge-Nummer (nur im Detail)"}}},"Annahmeschein":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"belegnummer":{"type":"string"},"status":{"type":"string"},"lieferdatum":{"type":"string","format":"date-time"},"anliefermenge_kg":{"type":"string","format":"decimal"},"netto_menge_kg":{"type":"string","format":"decimal"},"netto_betrag":{"type":"string","format":"decimal"}}},"AnnahmescheinListe":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Annahmeschein"}},"count":{"type":"integer"}}},"PaInput":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"pa_id":{"type":"integer","format":"int32"},"artikel_id":{"type":"integer","format":"int32"},"charge_id":{"type":"integer","format":"int32"},"soll_menge":{"type":"string","format":"decimal"},"ist_menge":{"type":"string","format":"decimal"},"einheit":{"type":"string"},"position":{"type":"integer","format":"int32"},"bemerkung":{"type":"string"},"artikel_bezeichnung":{"type":"string"},"artikelnr":{"type":"string"},"charge_nr":{"type":"string"},"fremde_charge_nr":{"type":"string"}}},"PaOutput":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"pa_id":{"type":"integer","format":"int32"},"artikel_id":{"type":"integer","format":"int32"},"soll_menge":{"type":"string","format":"decimal"},"ist_menge":{"type":"string","format":"decimal"},"einheit":{"type":"string"},"position":{"type":"integer","format":"int32"},"bemerkung":{"type":"string"},"artikel_bezeichnung":{"type":"string"},"artikelnr":{"type":"string"},"neue_charge_nr":{"type":"string"}}},"Produktionsauftrag":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"pa_nummer":{"type":"string"},"rezeptur_id":{"type":"integer","format":"int32"},"rezeptur_version":{"type":"integer","format":"int32"},"produktions_datum":{"type":"string","format":"date-time"},"niederlassung_id":{"type":"integer","format":"int32"},"lagerhalle_id":{"type":"integer","format":"int32"},"status":{"type":"string"},"bezeichnung":{"type":"string"},"bemerkung":{"type":"string"},"geplant_am":{"type":"string","format":"date-time"},"gestartet_am":{"type":"string","format":"date-time"},"erledigt_am":{"type":"string","format":"date-time"},"rezeptur_bezeichnung":{"type":"string"},"rezeptur_typ":{"type":"string"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/PaInput"},"description":"Einsatzstoffe — nur im Detail"},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/PaOutput"},"description":"Erzeugnisse — nur im Detail"}}},"Dokument":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"beleg_typ":{"type":"string"},"beleg_nummer":{"type":"string"},"beleg_datum":{"type":"string","format":"date-time"},"status":{"type":"string"},"summe_brutto":{"type":"string","format":"decimal"},"summe_netto":{"type":"string","format":"decimal"},"summe_mwst":{"type":"string","format":"decimal"},"kunde_id":{"type":"integer","format":"int32"},"kunde_name":{"type":"string"},"pdf_archiv_count":{"type":"string","description":"Anzahl archivierter PDFs (als String)"},"pdf_letztes":{"type":"string","format":"date-time"},"pdf_url":{"type":"string","description":"Link zum PDF-Endpoint, falls archiviert"}}},"Land":{"type":"object","properties":{"iso2":{"type":"string","description":"ISO-3166-1 alpha-2"},"iso3":{"type":"string","description":"ISO-3166-1 alpha-3"},"name_de":{"type":"string"},"eu_mitglied":{"type":"boolean"}}},"LandListe":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Land"}},"count":{"type":"integer"}}},"BelegPdf":{"type":"object","properties":{"beleg_id":{"type":"integer","format":"int32"},"dateiname":{"type":"string"},"mime_type":{"type":"string"},"datei_base64":{"type":"string","description":"PDF-Inhalt Base64-codiert"},"erstellt_am":{"type":"string","format":"date-time"}}},"Fehler":{"type":"object","properties":{"error":{"type":"string"}}},"SchreibFehler":{"type":"object","properties":{"error":{"type":"string","description":"Maschinen-lesbarer Fehlercode (z.B. KUNDE_FEHLT)"},"message":{"type":"string"}},"additionalProperties":true},"SchreibErgebnis":{"type":"object","description":"Bestaetigung der internen Engine (Durchreiche): enthaelt mindestens die ID und die fachliche Nummer des Datensatzes.","properties":{"id":{"type":"integer"}},"additionalProperties":true},"ApiInfo":{"type":"object","properties":{"api":{"type":"string"},"version":{"type":"string"},"docs":{"type":"string"},"spec":{"type":"string"},"auth":{"type":"string"},"endpoints":{"type":"array","items":{"type":"string"}}}}}},"security":[{"ApiKeyAuth":[]}],"paths":{"/api/v1/kunden":{"get":{"tags":["Kunden"],"summary":"Kunden abrufen","description":"Scope: kunden:read","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"suche","in":"query","schema":{"type":"string"},"description":"Freitextsuche nach Name/E-Mail"},{"name":"partner_typ","in":"query","schema":{"type":"string","enum":["kunde","lieferant","spediteur"]},"description":"Filtert auf Partner mit dieser Rolle (partner_typen)."},{"name":"limit","in":"query","schema":{"type":"integer","default":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Kundenliste","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KundeListe"}}}},"401":{"description":"Ungültiger Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}},"403":{"description":"Fehlender Scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}}}},"post":{"tags":["Kunden"],"summary":"Kunden anlegen","description":"Scope: kunden:write — Routet via intern geroutet auf /kunden, alle Defaults (kundennr-Generierung, staat='DE', zahlungsziel_tage=30, partner_typen=['kunde']) greifen. Mit `kundennr` im Body kann eine manuelle Nummer vergeben werden — bei Duplikat in der Firma kommt 409 KUNDENNR_BEREITS_VERGEBEN.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["nachname_firma"],"properties":{"kundennr":{"type":"string","description":"Optional. Wenn weggelassen: auto-generiert als K-{1000+count+1}. Bei Duplikat: 409."},"nachname_firma":{"type":"string","description":"Pflicht. Firmenname oder Nachname. Alias `name` wird als Fallback akzeptiert."},"name":{"type":"string","description":"Alias zu nachname_firma (Abwaertskompatibilitaet)."},"anrede":{"type":"string","enum":["Herr","Frau","Firma"]},"vorname":{"type":"string"},"strasse":{"type":"string"},"plz":{"type":"string"},"ort":{"type":"string"},"staat":{"type":"string","default":"DE"},"email":{"type":"string"},"telefon":{"type":"string"},"telefon2":{"type":"string"},"zahlungsziel_tage":{"type":"integer","default":30},"steuernummer":{"type":"string"},"ust_id":{"type":"string"},"betriebsnummer":{"type":"string"},"iban":{"type":"string"},"bic":{"type":"string"},"vb_id":{"description":"Vertriebler-ID oder -Name (gegen stammdaten typ=vertriebler aufgeloest).","oneOf":[{"type":"integer"},{"type":"string"}]},"partner_typen":{"type":"array","items":{"type":"string","enum":["kunde","lieferant"]},"default":["kunde"]},"notizen":{"type":"string"}}}}}},"responses":{"201":{"description":"Angelegter Kunde","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchreibErgebnis"}}}},"400":{"description":"Validierungsfehler (z.B. NAME_FEHLT)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchreibFehler"}}}},"409":{"description":"KUNDENNR_BEREITS_VERGEBEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchreibFehler"}}}},"401":{"description":"Ungültiger Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}}}}},"/api/v1/kunden/{id}":{"get":{"tags":["Kunden"],"summary":"Kunden abrufen (Einzeln)","description":"Scope: kunden:read","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Kundendaten","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Kunde"}}}},"404":{"description":"Nicht gefunden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}}}},"put":{"tags":["Kunden"],"summary":"Kunden aktualisieren","description":"Scope: kunden:write — COALESCE-Update: nur mitgesendete Felder werden geaendert.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"},"telefon":{"type":"string"},"strasse":{"type":"string"},"plz":{"type":"string"},"ort":{"type":"string"},"staat":{"type":"string","description":"ISO-3166-1-alpha-2 (Alias `land` wird akzeptiert)."}}}}}},"responses":{"200":{"description":"Aktualisierter Kunde","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Kunde"}}}},"404":{"description":"Nicht gefunden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}}}}},"/api/v1/kunden/{id}/dokumente":{"post":{"tags":["Kunden"],"summary":"Dokument hochladen","description":"Scope: dokumente:write — Base64-codiert","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["dateiname","inhalt_base64"],"properties":{"dateiname":{"type":"string"},"inhalt_base64":{"type":"string","description":"Base64-codierter Dateiinhalt"},"beschreibung":{"type":"string"}}}}}},"responses":{"201":{"description":"Hochgeladen","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchreibErgebnis"}}}},"404":{"description":"Kunde nicht gefunden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchreibFehler"}}}}}}},"/api/v1/artikel":{"get":{"tags":["Artikel"],"summary":"Artikel abrufen","description":"Scope: artikel:read","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"suche","in":"query","schema":{"type":"string"}},{"name":"gruppe_id","in":"query","schema":{"type":"integer"}},{"name":"limit","in":"query","schema":{"type":"integer","default":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Artikelliste (nur status=aktiv)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArtikelListe"}}}}}}},"/api/v1/artikelgruppen":{"get":{"tags":["Artikel"],"summary":"Artikelgruppen","description":"Scope: artikelgruppen:read","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Artikelgruppen-Liste","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArtikelgruppeListe"}}}}}}},"/api/v1/belege":{"get":{"tags":["Belege"],"summary":"Belege abrufen","description":"Scope: belege:read","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"typ","in":"query","schema":{"type":"string","enum":["AN","AU","LS","RE","BS","EL","ER"]}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"von","in":"query","schema":{"type":"string","format":"date"}},{"name":"bis","in":"query","schema":{"type":"string","format":"date"}},{"name":"kunden_id","in":"query","schema":{"type":"integer"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Belegliste","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BelegListe"}}}}}},"post":{"tags":["Belege"],"summary":"Beleg anlegen (z.B. EK-Lieferschein, VK-Lieferschein aus Jira-Push)","description":"Scope: belege:write — Routet via intern geroutet auf /belege, alle Hooks (Charge-Anlage, Lager-Buchung, Steuer-Logik) greifen automatisch.\n\n**Dashboard-Modus (Jira-Integration etc.)**: statt interner IDs koennen `kundennummer` + pro Position `artikelnr` mitgegeben werden — beide werden auf die internen IDs aufgeloest, bei unbekannten Werten kommt 400 (`KUNDE_NICHT_GEFUNDEN` / `ARTIKEL_NICHT_GEFUNDEN`).\n\n**Auto-Pricing**: wenn `ep_netto` pro Position nicht gesetzt ist, wird der Preis aus dem Artikel-Stamm gezogen — bei `staffelpreise_aktiv=true` aus der passenden Staffel (groesste `ab_menge` <= position.menge). `mwst_satz` wird genauso aus dem Stamm uebernommen wenn nicht gesetzt. Mit `auto_price: false` im Body abschaltbar.\n\n**Idempotenz**: mit `external_ref` (z.B. Jira-Issue-Key) liefert ein zweiter Aufruf den bestehenden Beleg zurueck (Antwort enthaelt `idempotent: true`).\n\nPro Position koennen optional `fremde_charge_nr`, `mhd`, `herkunftsland`, `biozertifikat_id` mitgegeben werden — bei chargenpflichtigen Artikeln wird die Charge mit diesen Infos angelegt.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["beleg_typ","items"],"properties":{"beleg_typ":{"type":"string","enum":["AN","AU","LS","RE","BS","EL","ER"],"description":"AN=Angebot, AU=Auftrag, LS=Lieferschein, RE=Rechnung, BS=Bestellung, EL=EK-Lieferschein, ER=EK-Rechnung"},"kunden_id":{"type":"integer","description":"Beleg-Partner (Kunde oder Lieferant je nach Typ). Alternative: kundennummer."},"kundennummer":{"type":"string","description":"Statt kunden_id: Auflösung ueber die Kundennummer (kundennr). Nur eine der beiden Angaben noetig."},"external_ref":{"type":"string","description":"Externe Referenz (z.B. Jira-Issue-Key). Macht den Push idempotent — zweiter Call mit derselben Ref liefert bestehenden Beleg mit `idempotent:true` zurueck."},"auto_price":{"type":"boolean","default":true,"description":"Wenn true (default) und ep_netto pro Position fehlt: Preis aus artikel.ep_netto / artikel_staffelpreise ableiten. Auf false setzen wenn der Caller selbst preist."},"beleg_datum":{"type":"string","format":"date"},"notizen":{"type":"string"},"niederlassung_id":{"type":"integer"},"lagerhalle_id":{"type":"integer"},"fremdbelegnummer":{"type":"string","description":"Externe Beleg-Nr des Lieferanten/Partners"},"vb_id":{"description":"Vertriebler/Vertreter — entweder die interne stammdaten-ID (Integer) oder der **Name** als String. Wird gegen stammdaten WHERE typ='vertriebler' aufgeloest. Bei unbekanntem Wert wird NULL gespeichert (keine 400). Nuetzlich wenn das Dashboard nur den Namen aus dem externen System kennt.","oneOf":[{"type":"integer"},{"type":"string"}]},"items":{"type":"array","items":{"type":"object","required":["menge"],"properties":{"artikel_id":{"type":"integer","description":"Interne Artikel-ID. Alternative: artikelnr (Stammdaten-Lookup)."},"artikelnr":{"type":"string","description":"Statt artikel_id: Auflösung ueber die Artikelnummer aus dem Stamm. Bei unbekannter Nummer 400 ARTIKEL_NICHT_GEFUNDEN."},"menge":{"type":"number"},"einheit":{"type":"string"},"ep_netto":{"type":"number","description":"Optional. Wenn weggelassen + auto_price=true: aus Stamm/Staffel berechnet."},"mwst_satz":{"type":"number","default":7,"description":"Optional. Wenn weggelassen: aus artikel.mwst_satz uebernommen."},"rabatt_prozent":{"type":"number"},"bezeichnung":{"type":"string"},"bezeichnung2":{"type":"string"},"langtext":{"type":"string"},"fremde_charge_nr":{"type":"string","description":"Charge-Nr beim Lieferanten (nur EK)"},"mhd":{"type":"string","format":"date","description":"Mindesthaltbarkeit (nur EK)"},"herkunftsland":{"type":"string","description":"ISO-Code (nur EK)"},"biozertifikat_id":{"type":"integer","description":"Biozert-Verknuepfung (nur EK)"},"charge_id":{"type":"integer","description":"Bei VK: konkrete Charge auswaehlen (sonst per /chargen/verfuegbar suchen)"}}}}}}}}},"responses":{"201":{"description":"Beleg angelegt mit beleg_nummer + id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchreibErgebnis"}}}},"200":{"description":"Idempotenz-Treffer: bestehender Beleg (external_ref), Feld `idempotent=true`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Beleg"}}}},"400":{"description":"Validierungsfehler (z.B. Charge fehlt fuer chargenpflichtigen Artikel)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchreibFehler"}}}}}}},"/api/v1/belege/{id}":{"get":{"tags":["Belege"],"summary":"Beleg + Positionen","description":"Scope: belege:read","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Beleg mit Positionen","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Beleg"}}}},"404":{"description":"Nicht gefunden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}}}},"put":{"tags":["Belege"],"summary":"Beleg aktualisieren","description":"Scope: belege:write — Body siehe POST","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Aktualisiert","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchreibErgebnis"}}}},"404":{"description":"Nicht gefunden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchreibFehler"}}}}}}},"/api/v1/belege/{id}/pdf":{"get":{"tags":["Belege"],"summary":"Archiviertes PDF holen (DMS)","description":"Scope: belege:read — liefert das aktuellste archivierte PDF (datei_base64) eines finalisierten Belegs.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Archiviertes PDF als JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BelegPdf"}}}},"404":{"description":"Kein archiviertes PDF — bitte zuerst im UI oeffnen oder /belege/:id/pdf-speichern aufrufen","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}}}}},"/api/v1/dokumente":{"get":{"tags":["Belege"],"summary":"Liste aller neuen Dokumente seit Datum (DMS)","description":"Scope: belege:read — typischer DMS-Polling-Endpunkt: liefert finalisierte Belege seit `since` mit pdf_url-Verweis.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"since","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Stichdatum YYYY-MM-DD"},{"name":"typen","in":"query","schema":{"type":"string"},"description":"Komma-separierte Beleg-Typen, z.B. RE,GS"},{"name":"status","in":"query","schema":{"type":"string"},"description":"Optionaler Status-Filter"}],"responses":{"200":{"description":"Liste neuer Dokumente (roh-Array)","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Dokument"}}}}}}}},"/api/v1/chargen":{"get":{"tags":["Chargen"],"summary":"Chargen abrufen","description":"Scope: chargen:read — Liste aller Chargen mit aktuellem Bestand.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"artikel_id","in":"query","schema":{"type":"integer"}},{"name":"partner_id","in":"query","schema":{"type":"integer"}},{"name":"mit_bestand","in":"query","schema":{"type":"boolean"},"description":"Wenn true, nur Chargen mit Bestand>0"},{"name":"limit","in":"query","schema":{"type":"integer","default":200}}],"responses":{"200":{"description":"Chargen-Liste mit Bestand (roh-Array)","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Charge"}}}}}}},"post":{"tags":["Chargen"],"summary":"Charge anlegen (Stand-Alone)","description":"Scope: chargen:write — fuer Daten-Migration (Anfangs-Bestaende). Fuer echte Wareneingaenge besser POST /api/v1/belege (EL/ER) verwenden — der legt die Charge inline an UND bucht den Lager-Zugang.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["artikel_id"],"properties":{"artikel_id":{"type":"integer"},"charge_nr":{"type":"string","description":"Optional — sonst auto"},"fremde_charge_nr":{"type":"string"},"mhd":{"type":"string","format":"date"},"herkunftsland":{"type":"string","description":"ISO-Code (DE,IT,FR,...)"},"biozertifikat_id":{"type":"integer"},"eingang_menge":{"type":"number"},"eingang_ep":{"type":"number"},"einheit":{"type":"string"},"niederlassung_id":{"type":"integer"},"lagerhalle_id":{"type":"integer"},"partner_id":{"type":"integer"},"eingang_quelle":{"type":"string","enum":["beleg","produktion","manuell"],"default":"manuell"}}}}}},"responses":{"201":{"description":"Charge angelegt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchreibErgebnis"}}}},"400":{"description":"artikel_id fehlt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchreibFehler"}}}}}}},"/api/v1/produktionsauftraege":{"get":{"tags":["Produktion"],"summary":"PA abrufen","description":"Scope: produktion:read","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["schwebend","geplant","in_bearbeitung","erledigt","storniert"]}},{"name":"datum_von","in":"query","schema":{"type":"string","format":"date"}},{"name":"datum_bis","in":"query","schema":{"type":"string","format":"date"}},{"name":"artikel_id","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"PA-Liste (roh-Array)","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Produktionsauftrag"}}}}}}},"post":{"tags":["Produktion"],"summary":"PA anlegen","description":"Scope: produktion:write — Body wird an internen /produktionsauftraege weitergeleitet.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rezeptur_id":{"type":"integer","description":"Wenn gesetzt, werden Inputs/Outputs aus Rezeptur skaliert"},"faktor":{"type":"number","default":1},"produktions_datum":{"type":"string","format":"date"},"niederlassung_id":{"type":"integer"},"lagerhalle_id":{"type":"integer"},"bezeichnung":{"type":"string"},"bemerkung":{"type":"string"},"zugewiesen_an":{"type":"integer"}}}}}},"responses":{"201":{"description":"PA angelegt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchreibErgebnis"}}}}}}},"/api/v1/produktionsauftraege/{id}":{"get":{"tags":["Produktion"],"summary":"PA Detail (mit Inputs/Outputs)","description":"Scope: produktion:read","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"PA + inputs[] + outputs[]","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Produktionsauftrag"}}}},"404":{"description":"Nicht gefunden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}}}}},"/api/v1/annahmescheine":{"get":{"tags":["Rohwaren"],"summary":"Annahmescheine","description":"Scope: rohwaren:read","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"von","in":"query","schema":{"type":"string","format":"date"}},{"name":"bis","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Annahmescheine-Liste","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnnahmescheinListe"}}}}}}},"/api/v1/kontrakte":{"get":{"tags":["Kontrakte"],"summary":"Kontrakte","description":"Scope: kontrakte:read","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Kontrakte-Liste","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KontraktListe"}}}}}}},"/api/v1/wiegungen":{"get":{"tags":["Waage"],"summary":"Wiegungen abrufen","description":"Scope: waage:read","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["offen","fertig","storno"]}},{"name":"von","in":"query","schema":{"type":"string","format":"date"}},{"name":"bis","in":"query","schema":{"type":"string","format":"date"}},{"name":"partner_id","in":"query","schema":{"type":"integer"}},{"name":"limit","in":"query","schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"Wiegungs-Liste (roh-Array)","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Wiegung"}}}}}}},"post":{"tags":["Waage"],"summary":"Erstwiegung anlegen","description":"Scope: waage:write — externe Waagen-Software pusht eine Erstwiegung rein. Fields: waage_id, gewicht_erst_kg, kennzeichen, fahrer, partner_id, richtung, artikel_id, niederlassung_id, lagerhalle_id, charge_id, kontrakt_id, kontrakt_position_id, fremdwiegung, bemerkung.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["waage_id","gewicht_erst_kg","partner_id"],"properties":{"waage_id":{"type":"integer"},"gewicht_erst_kg":{"type":"number"},"kennzeichen":{"type":"string"},"fahrer":{"type":"string"},"partner_id":{"type":"integer"},"artikel_id":{"type":"integer"},"richtung":{"type":"string","enum":["eingang","ausgang",""]},"niederlassung_id":{"type":"integer"},"lagerhalle_id":{"type":"integer"},"charge_id":{"type":"integer"},"kontrakt_id":{"type":"integer"},"kontrakt_position_id":{"type":"integer"},"fremdwiegung":{"type":"boolean"},"bemerkung":{"type":"string"}}}}}},"responses":{"201":{"description":"Erstwiegung gespeichert mit wiegeschein_nr + id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchreibErgebnis"}}}}}}},"/api/v1/wiegungen/{id}":{"get":{"tags":["Waage"],"summary":"Wiegung Detail","description":"Scope: waage:read","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Wiegung mit Partner/Artikel/Charge-Namen","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Wiegung"}}}},"404":{"description":"Nicht gefunden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}}}}},"/api/v1/wiegungen/{id}/zweitwiegung":{"put":{"tags":["Waage"],"summary":"Zweitwiegung abschliessen","description":"Scope: waage:write — schliesst eine offene Wiegung mit Endgewicht ab. Auto-Richtung wird ermittelt aus Erst-/Zweitwiegung-Differenz wenn nicht explizit gesetzt.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["gewicht_zweit_kg"],"properties":{"gewicht_zweit_kg":{"type":"number"},"charge_id":{"type":"integer"},"kontrakt_id":{"type":"integer"},"kontrakt_position_id":{"type":"integer"},"niederlassung_id":{"type":"integer"},"lagerhalle_id":{"type":"integer"},"richtung":{"type":"string","enum":["eingang","ausgang"]}}}}}},"responses":{"200":{"description":"Wiegung fertig mit Netto-Gewicht und ermittelter Richtung","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchreibErgebnis"}}}},"400":{"description":"Wiegung nicht im Zustand offen","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchreibFehler"}}}}}}},"/api/v1/laender":{"get":{"tags":["Sonstiges"],"summary":"Länderliste","description":"Kein Scope erforderlich — nur gültiger API-Key","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Länder mit ISO-Codes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LandListe"}}}}}}},"/api/v1":{"get":{"tags":["Info"],"summary":"API-Info","description":"Gibt API-Version, Endpunkte und Docs-URL zurück (kein Auth nötig)","responses":{"200":{"description":"API-Info","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiInfo"}}}}}}}}}