Einkaufverwaltung – Vollständige API-Referenz

Fach-API für Einkaufsbelege: Anfrage, Mengenkontrakt, Bestellung, Abruf und die Kette bis zum Wareneingang. Basis ist https://core-backend.reybex.com/api (Staging: https://io-staging-partner.reybex.com/api). Authentifizierung wie im API: --header "authorization: Basic $TOKEN".

Verkaufsbelege stehen unter Auftragsverwaltung. Lieferanten unter Kunden- und Lieferantenverwaltung. Artikel unter Artikelstamm-Verwaltung, Stammdaten unter Prüftabellen-Verwaltung.

Alle 41 Endpunkte hängen an /api/purHead. Der normale Schreibweg ist POST /api/purHead/.

1. Grundlagen

Ein Einkaufsbeleg ist ein PurHead mit Positionen PurItem. Der Lieferant ist ein Kunde mit Kontaktart Lieferant (vendor). Die Belegart docType entscheidet, ob der Datensatz Anfrage, Mengenkontrakt, Bestellung, Abruf oder Fracht-Bestellung ist. Welche Art auf welche folgen darf, steht in PurHeadDocRule.

Die Pfeile sind die übliche fachliche Kette. Ob ein Folgebeleg erlaubt ist, entscheidet die Regel des Mandanten, gelesen über GET /api/purHead/docTypes/{id}.

1.1 Zwei Speicherformen

Aufruf	Body	Wann
`POST /api/purHead/`	Objekt unter dem Schlüssel `purHead`	Normale Anlage und Änderung
`POST /api/purHead/light`	Der Belegkopf selbst, ohne Umschlag `purHead`	Kompakte Änderung, Antwort ist die Light-Sicht
`POST /api/purHead/prepareAndCreate`	Flache Importfelder (`vendorNumber`, `docType` als Name, `items[].material` als Zeichenkette)	Import mit Code-Auflösung
`POST /api/purHead/createPurchase`	Flache Felder plus Ids für Lager, Lagerplatz und Einheit; Positionen über Varianten-`sku`	Bestellung vom Typ 2, nur wenn jede Position eine Variante hat

POST /api/purHead/ antwortet mit:

json

{ "id": 210100, "docNumber": "BE-10001" }

Die Zahlen in den Beispielen sind Beispiel-Ids eines Mandanten. Sie stammen aus einem vorherigen Lesen. In Responses liefert die API die gespeicherte id.

1.2 Suchschlüssel

Am Belegkopf von POST /api/purHead/ eine bekannte id oder einen Suchschlüssel senden.

Ziel	Suchschlüssel
Lieferant `vendor`	`customerNo`
Artikel am Kopf, falls als ToOne	`matCode`, sonst `sku`
Lager	`code`, sonst `name`
Lagerplatz	`stockplaceCode` oder `name`, immer mit `warehouse`
Währung, Einheit, Steuer, Zahlungsbedingung, Belegart	`code`, sonst `type`, sonst `name`

In items[] bleibt die Artikel-id. Ein Suchschlüssel in dieser Liste legt keine bestehende Position an. Dieselbe Regel gilt für Verkaufspositionen.

GET /api/purHead/ mit vendorId und docTypeId sowie POST /api/purHead/createFromProposal lesen den Lieferanten und die Belegart per id. Das sind Vorbelegungsaufrufe, kein Speichern.

1.3 Antwort- und Fehlerformat

Lesen eines Belegs kapselt den Datensatz:

json

{
  "data": { "id": 210100, "docNumber": "BE-10001" },
  "meta": {
    "domain": "PurHead",
    "total": 1
  }
}

meta kann requiredFields, readOnlyFields, hiddenFields, invisibleFields und purItemMetaData enthalten.

Situation	HTTP	Körper
Beleg nicht gefunden	Status aus der Ausnahme, oft 404	`{ "error": "…" }`
`POST /api/purHead/createPurchase` – doppelte `docNumber`	412	`{ "error": "…" }`
`POST /api/purHead/createPurchase` – Constraint oder zu große Daten	400	`{ "error": "…" }`
Fachlicher Abbruch	500 oder der Status der Ausnahme	`{ "error": "…" }` oder `{ "data": { "error": "…" } }`
Fehlende Anmeldung	401	—

2. Belegarten

PurDocType.type:

`type`	Bedeutung
`0`	Anfrage
`1`	Mengenkontrakt
`2`	Bestellung
`3`	Abruf
`8`	Fracht-Bestellung (Kürzel Strecke)

Bei einer Strecken-Disposition aus offenen Vorschlägen sucht die Anlage zuerst einen Belegtyp mit type 4 und verwendet sonst Typ 2. Für Typ 4 gibt es keinen eigenen Übersetzungseintrag.

Weitere Schalter der Belegart:

Feld	Wirkung
`numberRange`	Nummernkreis der `docNumber`
`useInMrp`	Belegart wird in der Disposition berücksichtigt
`isTransfer`	Umlagerungs-Einkauf; nur diese Belege erscheinen in der Transferliste
`lowerDeliveryTolerance`	Prozent, ab dem eine geringere Wareneingangsmenge die Position schließt
`upperDeliveryTolerance`	Prozent, bis zu dem eine höhere Wareneingangsmenge erlaubt ist
`isPurOrderClosedAfterFirstInbound`	Bestellung gilt nach dem ersten Wareneingang als geschlossen
`automaticOrderSendMail`	Nach dem Speichern wird der Beleg per E-Mail versendet
`checkOpenOrderToAddMaterials`	Offene Bestellung wird beim Hinzufügen von Artikeln geprüft
`invDocType`	Inventurbelegart für den Wareneingang
`scanProduct`	Scan-Vorgabe an der Wareneingangsposition

Belegarten lesen: GET /api/domains/purDocType?take=100.

3. Belegkette

PurHeadDocRule verbindet fromDocType mit toDocType. Es gibt keine Preis- oder Stücklisten-Schalter an dieser Regel. Die erlaubten Ziele eines Belegs:

GET /api/purHead/docTypes/{id}

{id} ist die Id der Quell-Belegart. Die Antwort ist eine Liste { "id", "translatedName" } der Zielarten.

3.1 Vorlage mit Vorgänger

GET /api/purHead/?vendorId={lieferantId}&docTypeId={zielArtId}&refPurHeadId={quellBelegId}

legt nichts an. Die Antwort ist ein vorbelegter Kopf: Positionen und Adressen kommen vom Vorgänger, die Belegart ist das Ziel. Speichern erfolgt danach mit POST /api/purHead/.

Dieselbe Vorlage mit Dispositionsvorschlägen: POST /api/purHead/createFromProposal.

json

{
  "vendorId": 31001,
  "docTypeId": 32002,
  "proposals": [
    { "id": 33001, "quantity": 24, "unitId": 6001 }
  ]
}

33001 ist die Id eines offenen Dispositionsvorschlags. 32002 ist die Id der Ziel-Belegart Bestellung. Der Aufruf speichert nicht.

3.2 Abhängigkeiten vor dem Speichern

Abhängigkeit	Lesen
Lieferant	`GET /api/domains/customer?customerNo=eq(L-1000)&take=1`
Belegart	`GET /api/domains/purDocType?take=100`
Währung, Zahlungsbedingung, Einheit, Steuer	Prüftabellen
Artikel, Variante, Charge	Artikelstamm
Lager und Lagerplatz	`GET /api/domains/warehouse`, `GET /api/domains/stockPlace`
Folgebelegart	`GET /api/purHead/docTypes/{quellArtId}`
Einkaufstextbausteine	`GET /api/purHead/getDefaultPurTexts/{belegartId}`
Nachschlagelisten für die Maske	`GET /api/purHead/lookupData`

lookupData liefert Einkaufs-Steuerschlüssel, Frachten, Lager sowie Positions-, Kopf- und Fracht-Rabattarten.

Fehlt die Belegart bei der Vorlage, bricht der Aufruf mit purDocType nicht gefunden ab. Fehlt der Lieferant, mit vendor.not.found.error. Fehlt der Vorgänger, mit refPurHead.not.found.error.

4. Wichtige Felder

4.1 Kopf `PurHead`

Feld	Bedeutung
`docType`	Belegart
`docNumber`	Belegnummer; ohne Wert aus dem Nummernkreis
`vendor`	Lieferant
`docDate`	Belegdatum, Standard heute
`deliveryDate`	Lieferdatum
`endDate`	Endedatum, bei Kontrakten das Laufzeitende
`requisitionDate`	Anforderungsdatum
`cargoReadyDate`, `estimatedDepartureDate`, `estimatedArrivalDate`	Bereitstellung, Abfahrt, Ankunft
`currency`, `exchangeRate`	Währung und Kurs; Kurs wird bei der Vorlage aus Hauswährung und Lieferantenwährung berechnet
`paymcond`	Zahlungsbedingung, aus dem Lieferanten vorbelegt
`description`, `notes`, `terms`, `commentLine`	Texte
`intOrderNum`	Interne Bestellnummer
`containerNumber`	Container; wird aus der Auftragsposition übernommen, wenn der Vorschlag eine hat
`deliveryStatus`	`0` offen, `1` teilweise, `2` komplett, `3` überliefert (offene Menge negativ). Die Ankunftsliste zeigt dafür die Texte Offen, Teilweise offen, Geschlossen und Zusammengefasst
`invoiceStatus`	Rechnungsstatus des Kopfes
`isSend`, `isEmailSend`, `isEdiSend`, `isPrint`	Versandkennzeichen
`isCompletedManually`	Manuell abgeschlossen
`isDelete`	Logisch gelöscht
`refPurHead`	Vorgängerbeleg
`nettAmount`, `vatAmount`, `grossAmount`, `totalAmount`, `totalDiscountAmount`	Beträge
`delivery` / `invoice` / `main*`	Adress-Snapshots, beim Anlegen aus dem Lieferanten kopiert
`items`	Positionen

4.2 Position `PurItem`

Feld	Bedeutung
`material`	Artikel, in der Liste per `id`
`position`	Positionsnummer, üblich in Zehnerschritten
`quantity`	Bestellmenge
`price`, `priceUnit`	Einkaufspreis und Preiseinheit
`unit`	Mengeneinheit
`warehouse`, `stockplace`	Lager und Lagerplatz
`variantCode`	Variantenkennung
`attributeCode`	Attributcode
`batchnum`	Charge
`expiryDate`	Mindesthaltbarkeit
`vendorMatCode`, `vendorMatName`	Artikelnummer und Name des Lieferanten
`deliveryDate`, `confirmedDeliveryDate`	Wunsch- und bestätigtes Datum
`deliveryStatus`	`0` offen, `1` teilweise, `2` geliefert, `3` überliefert
`deliveredQuantity`	Bereits eingegangene Menge
`incomingGoodQuantity`	Offene Menge analog zur Verkaufs-`openQuantity`
`isCompletedManually`	Position manuell geschlossen
`isThirdParty`	Streckengeschäft
`salItemRequirements`	Verkaufsposition, die den Bedarf ausgelöst hat
`proposal`	Dispositionsvorschlag
`containerNumber`	Container der Position
`refItem`	Vorgängerposition beim Kopieren

5. Lesen und suchen

5.1 Ein Beleg (`GET /api/purHead/{id}`)

bash

curl --header "authorization: Basic $TOKEN" \
  "https://core-backend.reybex.com/api/purHead/210100"

Unbekannte Id: Ressource nicht gefunden.

5.2 Liste (`GET /api/purHead/`)

Ohne id und ohne vendorId ist die Antwort die Einkaufsliste (purchaseList) inklusive der Verkaufsbelegnummern, die an den Positionen hängen.

Mehrere Köpfe in einem Aufruf: POST /api/purHead/list mit { "ids": [210100, 210101] }.

5.3 Suche (`GET /api/purHead/findPurchase`)

Query	Ergebnis
`docNumber=BE-10001`	`{ "id": 210100 }`
`vendorId=31001`	Offene Belege dieses Lieferanten (`deliveryStatus` unter 2) mit Gewicht und Positionszahl

5.4 Light-Sicht (`GET /api/purHead/light/{id}`)

Kompakte Positionssicht. Speichern dieser Sicht: POST /api/purHead/light mit dem Beleg als Body, nicht unter purHead. Die Antwort ist wieder die Light-Sicht. Hat die Belegart automaticOrderSendMail, geht nach dem Speichern die Bestellmail heraus.

6. Bestellung anlegen

Zuerst Lieferant, Belegart Bestellung (type 2), Artikel, Einheit, Lager und Steuer lesen. Dann speichern.

6.1 Einzelartikel

POST /api/purHead/

json

{
  "purHead": {
    "vendor": { "customerNo": "L-1000" },
    "docType": { "name": "Bestellung" },
    "currency": { "code": "EUR" },
    "paymcond": { "code": "30" },
    "docDate": "2026-10-12",
    "deliveryDate": "2026-10-20",
    "description": "Nachbestellung Tasche",
    "items": [
      {
        "position": 10,
        "quantity": 50,
        "price": 4.2,
        "priceUnit": 1,
        "material": { "id": 100100 },
        "unit": { "code": "ST" },
        "warehouse": { "code": "HAUPT" },
        "vatKey": { "code": "19" },
        "deliveryDate": "2026-10-20"
      }
    ]
  }
}

100100 ist die Id des Artikels ART-1000 aus GET /api/domains/material?matCode=eq(ART-1000)&take=1.

Response

json

{ "id": 210100, "docNumber": "BE-10001" }

6.2 Anfrage

docType.name ist der Name der Anfrage-Belegart (type 0). Der Preis darf 0 sein.

json

{
  "purHead": {
    "vendor": { "customerNo": "L-1000" },
    "docType": { "name": "Anfrage" },
    "currency": { "code": "EUR" },
    "docDate": "2026-10-12",
    "deliveryDate": "2026-11-02",
    "description": "Preisanfrage Haferdrink",
    "items": [
      {
        "position": 10,
        "quantity": 240,
        "price": 0,
        "priceUnit": 1,
        "material": { "id": 100200 },
        "unit": { "code": "ST" },
        "warehouse": { "code": "HAUPT" },
        "vatKey": { "code": "7" }
      }
    ]
  }
}

Response: { "id": 210010, "docNumber": "AF-10001" }

Daraus wird eine Bestellung in zwei Schritten. Zuerst die Vorlage, nichts wird gespeichert. 32002 ist die Bestell-Belegart, 31001 der Lieferant:

GET /api/purHead/?vendorId=31001&docTypeId=32002&refPurHeadId=210010

Dann den Kopf aus der Antwort unter purHead speichern. Mindestinhalt, wenn die Vorlage schon die Positionen enthält:

json

{
  "purHead": {
    "vendor": { "id": 31001 },
    "docType": { "id": 32002 },
    "refPurHead": { "id": 210010 },
    "currency": { "code": "EUR" },
    "items": [
      {
        "position": 10,
        "quantity": 240,
        "price": 0.89,
        "priceUnit": 1,
        "material": { "id": 100200 },
        "unit": { "code": "ST" },
        "warehouse": { "code": "HAUPT" },
        "vatKey": { "code": "7" }
      }
    ]
  }
}

6.3 Mengenkontrakt und Abruf

Kontrakt, type 1. endDate ist das Laufzeitende.

json

{
  "purHead": {
    "vendor": { "customerNo": "L-1000" },
    "docType": { "name": "Mengenkontrakt" },
    "currency": { "code": "EUR" },
    "docDate": "2026-10-12",
    "endDate": "2027-10-11",
    "description": "Jahreskontrakt Haferdrink",
    "items": [
      {
        "position": 10,
        "quantity": 2000,
        "price": 0.82,
        "priceUnit": 1,
        "material": { "id": 100200 },
        "unit": { "code": "ST" },
        "warehouse": { "code": "HAUPT" },
        "vatKey": { "code": "7" }
      }
    ]
  }
}

Response: { "id": 210020, "docNumber": "MK-10001" }

Erlaubte Ziele: GET /api/purHead/docTypes/{kontraktArtId}. Der Abruf (type 3) übernimmt einen Teil der Kontraktmenge. 32003 ist die Abruf-Belegart.

json

{
  "purHead": {
    "vendor": { "customerNo": "L-1000" },
    "docType": { "id": 32003 },
    "refPurHead": { "id": 210020 },
    "currency": { "code": "EUR" },
    "deliveryDate": "2026-10-27",
    "items": [
      {
        "position": 10,
        "quantity": 120,
        "price": 0.82,
        "priceUnit": 1,
        "material": { "id": 100200 },
        "refItem": { "id": 41021 },
        "unit": { "code": "ST" },
        "warehouse": { "code": "HAUPT" },
        "vatKey": { "code": "7" }
      }
    ]
  }
}

41021 ist die Kontraktposition. Ein Suchschlüssel an refItem legt die Vorgängerposition nicht an.

6.4 Variantenartikel

Der Kopf bleibt eine normale Bestellung. Jede Variante ist eine eigene Position mit variantCode. Die Varianten-Id stammt aus Varianten.

json

{
  "purHead": {
    "vendor": { "customerNo": "L-1000" },
    "docType": { "name": "Bestellung" },
    "currency": { "code": "EUR" },
    "items": [
      {
        "position": 10,
        "quantity": 20,
        "price": 8.5,
        "priceUnit": 1,
        "material": { "id": 100400 },
        "variantCode": "ROT-M",
        "unit": { "code": "ST" },
        "warehouse": { "code": "HAUPT" },
        "vatKey": { "code": "19" }
      },
      {
        "position": 20,
        "quantity": 15,
        "price": 8.5,
        "priceUnit": 1,
        "material": { "id": 100400 },
        "variantCode": "BLAU-L",
        "unit": { "code": "ST" },
        "warehouse": { "code": "HAUPT" },
        "vatKey": { "code": "19" }
      }
    ]
  }
}

100400 ist der Kopfartikel VAR-4000. Attributwerte an der Position liest GET /api/purHead/attribute?purItemId={id} oder ?materialId={id}.

6.5 Set-Artikel

Der Einkauf führt keine Set-Positionsliste wie der Verkauf. Der Set-Artikel wird als eine Position mit der Artikel-id des Sets bestellt. Die Stückliste bleibt am Artikel, siehe Stückliste. Komponenten, die selbst beschafft werden, sind eigene Bestellpositionen. 100300 ist SET-3000.

json

{
  "purHead": {
    "vendor": { "customerNo": "L-1000" },
    "docType": { "name": "Bestellung" },
    "currency": { "code": "EUR" },
    "deliveryDate": "2026-10-20",
    "items": [
      {
        "position": 10,
        "quantity": 25,
        "price": 3.4,
        "priceUnit": 1,
        "material": { "id": 100300 },
        "unit": { "code": "ST" },
        "warehouse": { "code": "HAUPT" },
        "vatKey": { "code": "7" }
      }
    ]
  }
}

6.6 Charge und Mindesthaltbarkeit

Am Artikel müssen isLotEnabled und bei MHD isShelfLife gesetzt sein. Charge und Datum stehen an der Einkaufsposition. Den Bestand bucht der Wareneingang, nicht das Speichern der Bestellung.

json

{
  "purHead": {
    "vendor": { "customerNo": "L-1000" },
    "docType": { "name": "Bestellung" },
    "currency": { "code": "EUR" },
    "items": [
      {
        "position": 10,
        "quantity": 24,
        "price": 0.89,
        "priceUnit": 1,
        "material": { "id": 100200 },
        "batchnum": "LOT-2026-10-A",
        "expiryDate": "2027-04-30",
        "unit": { "code": "ST" },
        "warehouse": { "code": "HAUPT" },
        "vatKey": { "code": "7" }
      }
    ]
  }
}

100200 ist LM-2000.

6.7 Preis und Menge vor dem Speichern

POST /api/purHead/findMaterial berechnet Preis, Steuer und Einheiten einer Position. Pflicht ist materialId. Weitere Felder: customerId (Lieferant), quantity, docTypeId, currencyId, docDate im Format yyyy-M-dd, variantCode, profitCenterId, refItemId, proposalId.

json

{
  "materialId": 100100,
  "customerId": 31001,
  "quantity": 50,
  "docTypeId": 32002,
  "currencyId": 1,
  "docDate": "2026-10-12",
  "variantCode": null
}

Fehlt der Artikel: material.not.found. Fehlt jede Einheit am Artikel: material.units.not.found.

Palettenvolumen: POST /api/purHead/calculatePallet mit materialId und unitId, optional quantity. Antwort: volume, palletTotal.

6.8 Ändern und löschen

Änderung: derselbe POST /api/purHead/ mit purHead.id.

json

{
  "purHead": {
    "id": 210100,
    "deliveryDate": "2026-10-24"
  }
}

Löschen: DELETE /api/purHead/ mit { "ids": [210100] }. Antwort: { "ids": [210100] }. Das Löschen ist logisch (isDelete).

7. Aus der Disposition

7.1 Vorschlag prüfen

POST /api/purHead/checkProposal

json

{ "proposalIdList": [33001, 33002] }

Antwort: { "isProposalOrdered": true }, wenn mindestens ein Vorschlag schon bestellt ist. Alternativ akzeptiert der Aufruf proposalIds.

7.2 Bestellungen aus Vorschlägen

POST /api/purHead/createOrdersFromMrp

json

{
  "proposals": [
    { "id": 33001, "quantity": 24 },
    { "id": 33002, "quantity": 10 }
  ]
}

Offene Vorschläge werden nach Lieferant, Strecke und Lieferadresse gruppiert. Pro Gruppe entsteht eine Bestellung. Strecke sucht Belegtyp 4, sonst Typ 2. Es gibt keine offenen Vorschläge: createOrdersFromMrp.no.valid.openProposals.error.

Antwort enthält purHeadIds.

Dieselbe Gruppierung als ungespeicherte Vorlage liefert POST /api/purHead/createFromProposal (Abschnitt Vorlage).

7.3 Streckengeschäft

POST /api/purHead/createDropshippingOrders

json

{ "purHeadId": 210100 }

Der Beleg muss Positionen haben, die einem Streckenlieferanten zugeordnet sind. Bleiben Positionen übrig, bricht der Aufruf ab (dropshipping.order.not.all.items.ordered). Erfolg: { "id": 210100 }, isSend wird gesetzt.

Meldungen zur Bestellung: GET /api/purHead/findCommMessagesForPurHead.

8. Wareneingang

Die Bestellung bucht keinen Bestand. Der Wareneingang liest die offenen Positionen und bucht danach über die Lager-API.

8.1 Offene Belege

GET /api/purHead/listDocumentsForArrival

Liefert ungelöschte Belege mit mindestens einer offenen, lagergeführten Position (deliveryStatus unter 2, keine Strecke). Enthalten sind Belegnummer, Lieferant, Lager, Positionszahl, Menge und die Verkaufsbelegnummern des Bedarfs.

GET /api/purHead/listForArrival ist die Ankunftsliste.

8.2 Offene Positionen

POST /api/purHead/getOpenPurItems

Mindestens eines von docNumbers, vendor.id, containerNumbers.

json

{
  "docNumbers": ["BE-10001"],
  "vendor": { "id": 31001 },
  "warehouse": { "id": 7001 }
}

Die Antwort enthält je Position matCode, openQuantity, batchnum, purItemId, Lager und Einheit.

8.3 Buchungsvorschlag

POST /api/purHead/purHeadIncomingGoods

json

{ "ids": [210100] }

ids sind Einkaufsbeleg-Ids. Die Antwort:

Feld	Inhalt
`incomingGoods[]`	Artikel, offene Menge, Charge, MHD, Variante, Lager, `purHead`, `purItem`
`incomingGoods[].moveTypeCode`	Bewegungsart `110`, sofern sie aktiv ist
`containerNumber`	Container der Positionen, kommagetrennt
`invDoctype`	Manuelle Zugangs-Belegart

Response für Bestellung 210100, Position 41011, Artikel LM-2000:

json

{
  "incomingGoods": [
    {
      "id": 100200,
      "matCode": "LM-2000",
      "name": "Haferdrink 1 l",
      "isLotEnabled": true,
      "isShelfLife": true,
      "quantity": 24,
      "batchnum": "LOT-2026-10-A",
      "expiryDate": "2027-04-30",
      "moveTypeCode": "110 Wareneingang",
      "stockMoveType": { "id": 11001, "translatedName": "110 Wareneingang", "moveTypeCode": "110" },
      "warehouseId": 7001,
      "warehouse": { "id": 7001, "translatedName": "Hauptlager" },
      "purHead": { "id": 210100, "docNumber": "BE-10001" },
      "purItem": { "id": 41011 }
    }
  ],
  "containerNumber": "",
  "invDoctype": { "id": 8801, "translatedName": "Wareneingang" }
}

Gebucht wird der Wareneingang mit diesen Zeilen über Lager und Inventur, nicht dieser Endpunkt selbst. Chargenartikel: batchnum und expiryDate aus der Position in die Buchung übernehmen. Siehe Bestand in der Artikelstamm-Verwaltung.

GET /api/purHead/getArrivals/{id} liest die bereits gebuchten Zugänge eines Belegs.

8.4 Positionen manuell schließen

POST /api/purHead/closeItems

json

{ "purItemIds": [41011, 41012] }

Jede Position mit deliveryStatus unter 2 wird auf geliefert gesetzt (deliveredQuantity = quantity, isCompletedManually). Sind danach alle Positionen des Kopfes geliefert oder gelöscht, wird der Kopf manuell abgeschlossen. Antwort: { "success": true }.

Unter- und Überlieferung ohne manuelles Schließen steuern lowerDeliveryTolerance und upperDeliveryTolerance an der Belegart. closingGap am Kopf schließt den Beleg, wenn der gelieferte Anteil den Prozentwert erreicht.

8.5 Eingangsrechnung

GET /api/purHead/getVouchers/{id} liest die dem Beleg zugeordneten Eingangsbelege.

POST /api/purHead/verificationItemList mit { "ids": [41011] } liest Rechnungsprüfungspositionen zu diesen Einkaufspositionen: Belegnummer, Status, Menge, Preis, Netto, Brutto.

9. Shortcut-Anlage

9.1 `POST /api/purHead/prepareAndCreate`

Flacher Import. Der Endpoint speichert am Ende über denselben Weg wie POST /api/purHead/.

Feld	Auflösung
`vendorNumber`	Lieferantennummer
`docType`	Name der Belegart
`currency`	Währungscode, sonst Hauswährung
`paymentCondition`	Code der Zahlungsbedingung
`profitCenter`	Code
`department`	Name oder E-Mail der Einkaufsabteilung
`language`	Sprachcode
`shipping`, `freight`	Name
`vatRate`	Steuersatz, Einkaufssteuer
`items[].material`	Zeichenkette, Artikel oder Variante
`items[].warehouse`	Lagercode
`items[].unit`	Einheitencode, sonst `ST`
`items[].quantity`, `price`, `vatRate`	Menge, Preis, Steuer der Position

vendorNumber immer setzen. Wird kein Lieferant gefunden, verwendet der Endpoint einen vorhandenen Lieferanten des Mandanten.

Ohne totalAmount werden die Kopfbeträge berechnet (calculateHeadAmounts).

json

{
  "vendorNumber": "L-1000",
  "docType": "Bestellung",
  "currency": "EUR",
  "language": "de",
  "paymentCondition": "30",
  "profitCenter": "B2B",
  "shipping": "Spedition",
  "vatRate": 19,
  "items": [
    {
      "material": "ART-1000",
      "quantity": 50,
      "price": 4.2,
      "unit": "ST",
      "warehouse": "HAUPT",
      "vatRate": 19
    }
  ]
}

Response: { "id": 210100, "docNumber": "BE-10001" }

9.2 `POST /api/purHead/createPurchase`

Legt eine Bestellung vom Typ 2 an. Die Belegnummer darf noch nicht existieren.

Feld	Pflicht	Bedeutung
`currency`	ja	Währungscode, aktiv
`vendorNo`	ja	Lieferantennummer
`warehouseId`	ja	Lager-Id
`stockplaceId`	ja	Lagerplatz-Id
`unitId`	ja	Einheits-Id, gilt für alle Positionen
`docNumber`	ja	Belegnummer, eindeutig
`docDate`, `deliveryDate`	ja	Datum
`intOrderNum`	nein	Interne Nummer
`profitCenter`	nein	Code der Profitcenter
`purDepartmentId`	nein	Id der Einkaufsabteilung
`items[].sku`	ja	SKU einer Variante
`items[].quantity`, `price`	ja	Menge und Preis

Ein Artikel ohne Variante zu dieser SKU bricht mit material variant not found ab. Steuer und Variantenkennung werden gesetzt. Für Einzelartikel ohne Variante POST /api/purHead/ verwenden.

7001 ist Lager HAUPT, 8001 Lagerplatz WE-01, 6001 Einheit Stück.

json

{
  "currency": "EUR",
  "vendorNo": "L-1000",
  "warehouseId": 7001,
  "stockplaceId": 8001,
  "unitId": 6001,
  "docNumber": "BE-10002",
  "docDate": "2026-10-12",
  "deliveryDate": "2026-10-20",
  "intOrderNum": "INT-44",
  "profitCenter": "B2B",
  "items": [
    { "sku": "VAR-4000-ROT-M", "quantity": 20, "price": 8.5 },
    { "sku": "VAR-4000-BLAU-L", "quantity": 15, "price": 8.5 }
  ]
}

Die Antwort ist der gespeicherte Beleg. Existiert BE-10002 schon, ist der Status 412.

10. E-Mail, Texte, Anhänge

Aufruf	Wirkung
`GET /api/purHead/getPurHeadEmailModel/{id}`	Betreff, Körper, Empfänger, Anhänge, Kontakte
`POST /api/purHead/sendPurHeadAsMail`	`{ "ids": [210100] }`. Antwort `success` und `failedList`
`GET /api/purHead/getPurHeadEmails`	Gesendete Mails
`GET /api/purHead/emailHistory`	Mail-Historie, optional `since`
`GET /api/purHead/getTexts/{id}`	Texte des Belegs
`GET /api/purHead/getDefaultPurTexts/{belegartId}`	Textbausteine der Belegart
`GET /api/purHead/getAttachments/{id}`	Anhänge

Hat die Belegart automaticOrderSendMail, versendet schon das Speichern die Mail.

11. Transfer, Umsatz, Lieferantenportal

Methode	Pfad	Bedeutung
`GET`	`/api/purHead/salesTransfers/purchase`	Einkaufspositionen zu einer Umlagerungs-Verkaufsposition. Query `id` ist die SalesItem-Id, `isDelivered` filtert gelieferte Zeilen. Beide Belegarten müssen `isTransfer` sein
`POST`	`/api/purHead/salesTransfers/purchase`	Dieselbe Liste mit Body `id` und `isDelivered`
`GET`	`/api/purHead/purItemTurnovers`	Positionsumsätze
`GET`	`/api/purHead/orderSalesItems`	Verkaufspositionen, die sich bestellen lassen
`GET`	`/api/purHead/quickPurHeads`	Belege des angemeldeten Lieferantenportals
`GET`	`/api/purHead/purHeadStatus`	Statusliste des Portals, Query `statusType`
`POST`	`/api/purHead/quickPurHeads`	Portal ändert eine Position: `purItem.id`, `quantity`, `price`, `deliveryDate`, `notes`, optional `isCancel`, `attributeCodes`, `shippingCost`

Die drei quick-Endpunkte gelten für das Lieferantenportal, nicht für die normale Mandanten-Integration.

12. Weitere Beispiele

12.1 Drei Positionen in einer Bestellung

Einzelartikel, Variante und Charge in einem Beleg. Die Artikel-Ids stammen aus dem vorherigen Lesen.

json

{
  "purHead": {
    "vendor": { "customerNo": "L-1000" },
    "docType": { "name": "Bestellung" },
    "currency": { "code": "EUR" },
    "paymcond": { "code": "30" },
    "docDate": "2026-10-12",
    "deliveryDate": "2026-10-20",
    "description": "Sammelbestellung KW 42",
    "items": [
      {
        "position": 10,
        "quantity": 50,
        "price": 4.2,
        "priceUnit": 1,
        "material": { "id": 100100 },
        "unit": { "code": "ST" },
        "warehouse": { "code": "HAUPT" },
        "vatKey": { "code": "19" }
      },
      {
        "position": 20,
        "quantity": 20,
        "price": 8.5,
        "priceUnit": 1,
        "material": { "id": 100400 },
        "variantCode": "ROT-M",
        "unit": { "code": "ST" },
        "warehouse": { "code": "HAUPT" },
        "vatKey": { "code": "19" }
      },
      {
        "position": 30,
        "quantity": 24,
        "price": 0.89,
        "priceUnit": 1,
        "material": { "id": 100200 },
        "batchnum": "LOT-2026-10-A",
        "expiryDate": "2027-04-30",
        "unit": { "code": "ST" },
        "warehouse": { "code": "HAUPT" },
        "vatKey": { "code": "7" }
      }
    ]
  }
}

12.2 Preis der Position ändern

210100 ist die Bestellung, 41011 die Position.

json

{
  "purHead": {
    "id": 210100,
    "items": [
      {
        "id": 41011,
        "price": 0.95,
        "isPriceSetManually": true
      }
    ]
  }
}

Preis vor dem Anlegen: POST /api/purHead/findMaterial

json

{
  "materialId": 100200,
  "customerId": 31001,
  "quantity": 24,
  "docTypeId": 32002,
  "currencyId": 1,
  "docDate": "2026-10-12",
  "variantCode": null
}

Die Antwort liefert unter anderem materialPurPrice, priceUnit und deliveryDate. Diese drei Felder übernimmt die Vorlage aus der Disposition in die Position.

12.3 Disposition bis Bestellung

Prüfung, ob die Vorschläge schon bestellt sind:

json

{ "proposalIdList": [33001, 33002] }

Antwort { "isProposalOrdered": false }. Dann speichern:

json

{
  "proposals": [
    { "id": 33001, "quantity": 24 },
    { "id": 33002, "quantity": 10 }
  ]
}

POST /api/purHead/createOrdersFromMrp. Antwort enthält purHeadIds, zum Beispiel [210100]. Strecke sucht Belegtyp 4 und fällt sonst auf Typ 2 zurück.

Dieselbe Auswahl ungespeichert vorlegen: POST /api/purHead/createFromProposal mit vendorId, docTypeId und proposals, siehe Vorlage.

12.4 Wareneingang und Rest schließen

Offene Positionen der Bestellung BE-10001:

json

{
  "docNumbers": ["BE-10001"],
  "vendor": { "id": 31001 }
}

Buchungsvorschlag: { "ids": [210100] }, Response in Buchungsvorschlag. Nach der Buchung einer Teilmenge die Restposition schließen:

json

{ "purItemIds": [41012] }

Antwort { "success": true }. Die Position gilt als geliefert, auch wenn die gebuchte Menge kleiner war.

12.5 Mail und Portal

POST /api/purHead/sendPurHeadAsMail baut die Mail aus der Vorlage der Belegart. Empfänger stehen nicht im Body.

json

{ "ids": [210100] }

json

{
  "success": true,
  "failedList": []
}

Ein Fehler: { "success": false, "failedList": [{ "purHeadId": 210100, "message": "…" }] }.

Das Lieferantenportal ändert eine Position. POST /api/purHead/quickPurHeads

json

{
  "purItem": {
    "id": 41011,
    "quantity": 20,
    "price": 0.9,
    "deliveryDate": "2026-10-28",
    "notes": "Teillieferung bestätigt",
    "shippingCost": 12
  }
}

Storno der Position im Portal: "isCancel": true statt Menge und Preis. Antwort { "success": true }. Dieser Aufruf gilt für das Portal, nicht für die Mandanten-Integration.

Staffel und Import

Staffelpreise liegen unter /api/purPriceScaled/. Der Einkaufspreis, der in den Verkauf übernommen wird, unter /api/purSalesPrice/. Der Import ist POST /api/purSalesPrice/purSalesPriceImport. Ein Skript an der Position ist POST /api/purItem/scriptBlock. Der Körper von POST /api/purPriceScaled/ und POST /api/purSalesPrice/ ist der Datensatz.

13. Endpoint-Katalog

Methode	Pfad	Bedeutung
`GET`	`/api/purHead/{id}`	Ein Beleg, Vorlage (`vendorId` + `docTypeId`) oder Liste
`POST`	`/api/purHead/list`	Mehrere Belege, Body `ids`
`POST`	`/api/purHead/`	Anlegen und ändern, Body `purHead`
`DELETE`	`/api/purHead/`	Logisch löschen, Body `ids`
`GET`	`/api/purHead/light/{id}`	Kompakte Sicht
`POST`	`/api/purHead/light`	Kompakte Sicht speichern
`POST`	`/api/purHead/prepareAndCreate`	Flacher Import
`POST`	`/api/purHead/createPurchase`	Bestellung Typ 2 über Varianten-SKU
`POST`	`/api/purHead/createFromProposal`	Ungespeicherte Vorlage aus Vorschlägen
`POST`	`/api/purHead/createOrdersFromMrp`	Bestellungen aus Vorschlägen speichern
`POST`	`/api/purHead/checkProposal`	Ob Vorschläge schon bestellt sind
`POST`	`/api/purHead/createDropshippingOrders`	Streckenbestellung anstoßen, Body `purHeadId`
`GET`	`/api/purHead/docTypes/{id}`	Erlaubte Folgebelegarten
`POST`	`/api/purHead/findMaterial`	Preis, Steuer, Einheiten einer Position
`POST`	`/api/purHead/calculatePallet`	Volumen und Paletten
`GET`	`/api/purHead/findPurchase`	Suche nach `docNumber` oder `vendorId`
`GET`	`/api/purHead/listForArrival`	Ankünfte
`GET`	`/api/purHead/listDocumentsForArrival`	Offene Belege für den Wareneingang
`POST`	`/api/purHead/getOpenPurItems`	Offene Positionen
`POST`	`/api/purHead/purHeadIncomingGoods`	Buchungsvorschlag, Body `ids`
`GET`	`/api/purHead/getArrivals/{id}`	Gebuchte Zugänge
`POST`	`/api/purHead/closeItems`	Positionen manuell schließen
`GET`	`/api/purHead/getVouchers/{id}`	Eingangsbelege
`POST`	`/api/purHead/verificationItemList`	Rechnungsprüfungszeilen, Body `ids`
`GET`	`/api/purHead/getTexts/{id}`	Texte
`GET`	`/api/purHead/getDefaultPurTexts/{id}`	Standardtexte der Belegart
`GET`	`/api/purHead/getAttachments/{id}`	Anhänge
`GET`	`/api/purHead/getPurHeadEmailModel/{id}`	Mail-Dialog
`POST`	`/api/purHead/sendPurHeadAsMail`	Belege mailen, Body `ids`
`GET`	`/api/purHead/getPurHeadEmails`	Gesendete Mails
`GET`	`/api/purHead/emailHistory`	Mail-Historie
`GET`	`/api/purHead/findCommMessagesForPurHead`	Kommunikationsmeldungen
`GET`	`/api/purHead/attribute`	Attribute einer Position oder eines Artikels
`GET`	`/api/purHead/lookupData`	Steuer, Fracht, Lager, Rabattarten
`GET`	`/api/purHead/purItemTurnovers`	Positionsumsätze
`GET`	`/api/purHead/orderSalesItems`	Bestellbare Verkaufspositionen
`GET`	`/api/purHead/salesTransfers/purchase`	Transferpositionen
`POST`	`/api/purHead/salesTransfers/purchase`	Transferpositionen
`GET`	`/api/purHead/quickPurHeads`	Lieferantenportal, Liste
`POST`	`/api/purHead/quickPurHeads`	Lieferantenportal, Position ändern
`GET`	`/api/purHead/purHeadStatus`	Lieferantenportal, Status
`POST`	`/api/purItem/scriptBlock`	Skript an der Position
`GET`	`/api/purPriceScaled/{id}`	Eine Staffel
`POST`	`/api/purPriceScaled/`	Staffel speichern
`DELETE`	`/api/purPriceScaled/{id}`	Staffel löschen
`GET`	`/api/domains/purPrice`	Einkaufsinfosätze über Generic Domain lesen
`POST`	`/api/domains/purPrice`	Einkaufsinfosätze über Generic Domain speichern
`DELETE`	`/api/domains/purPrice`	Einkaufsinfosätze über Generic Domain löschen
`GET`	`/api/domains/purPriceScaled`	Preisstaffeln über Generic Domain lesen
`GET`	`/api/domains/purPriceVariant`	Variantenpreise über Generic Domain lesen
`GET`	`/api/domains/purPriceDiscount`	Rabattstaffeln über Generic Domain lesen
`GET`	`/api/domains/purPriceAttribute`	Attributpreise über Generic Domain lesen
`GET`	`/api/purSalesPrice/{id}`	Ein Einkaufs-Verkaufspreis
`POST`	`/api/purSalesPrice/`	Preis speichern
`DELETE`	`/api/purSalesPrice/`	Preis löschen
`POST`	`/api/purSalesPrice/purSalesPriceImport`	Preise importieren
`POST`	`/api/verificationHead/importVerification`	Rechnungsprüfung aus Einkaufsdaten erzeugen
`GET`	`/api/verificationHead/getVendorList`	Lieferantenliste für die Rechnungsprüfung

14. Häufige Fehler

Meldung	Ursache
`purHead.docType.not.found.error`	Vorlage ohne gültige `docTypeId`
`vendor.not.found.error`	`vendorId` zeigt auf keinen Lieferanten
`refPurHead.not.found.error`	Vorgängerbeleg fehlt
`material.not.found`	`findMaterial` ohne Artikel
`material.units.not.found`	Artikel ohne Einheit
`createOrdersFromMrp.no.valid.openProposals.error`	Kein offener Vorschlag
`dropshipping.order.not.all.items.ordered`	Strecke konnte nicht alle Positionen zuordnen
`vendor.not.found` / `currency.is.not.found` / `warehouse.not.found` / `stockPlace.not.found` / `unit.not.found` / `purDocType.not.found`	`createPurchase` ohne Stammdaten
Belegnummer existiert	`createPurchase` mit vorhandener `docNumber`
`material variant not found with sku`	`createPurchase` mit Artikel ohne Variante
Ressource gesperrt	Gleichzeitiges Speichern, erneut versuchen

15. Ablauf Bestellung bis Wareneingang

Lieferant, Belegart Bestellung, Artikel, Einheit, Lager und Steuer lesen.
Bei Variante variantCode setzen, bei Charge batchnum und expiryDate.
POST /api/purHead/ speichern, id und docNumber merken.
Optional POST /api/purHead/sendPurHeadAsMail.
POST /api/purHead/purHeadIncomingGoods mit der Beleg-Id lesen.
Wareneingang mit Menge, Charge und Lager buchen.
Restmengen mit POST /api/purHead/closeItems abschließen, wenn keine weitere Lieferung kommt.
Eingangsbeleg über GET /api/purHead/getVouchers/{id} prüfen.

Fachlicher Hintergrund: Bestellungen, Bestellanforderungen, Lieferanten.

Einkaufverwaltung – Vollständige API-Referenz ​

1. Grundlagen ​

1.1 Zwei Speicherformen ​

1.2 Suchschlüssel ​

1.3 Antwort- und Fehlerformat ​

2. Belegarten ​

3. Belegkette ​

3.1 Vorlage mit Vorgänger ​

3.2 Abhängigkeiten vor dem Speichern ​

4. Wichtige Felder ​

4.1 Kopf PurHead ​

4.2 Position PurItem ​

5. Lesen und suchen ​

5.1 Ein Beleg (GET /api/purHead/{id}) ​

5.2 Liste (GET /api/purHead/) ​

5.3 Suche (GET /api/purHead/findPurchase) ​

5.4 Light-Sicht (GET /api/purHead/light/{id}) ​

6. Bestellung anlegen ​

6.1 Einzelartikel ​

6.2 Anfrage ​

6.3 Mengenkontrakt und Abruf ​

6.4 Variantenartikel ​

6.5 Set-Artikel ​

6.6 Charge und Mindesthaltbarkeit ​

6.7 Preis und Menge vor dem Speichern ​

6.8 Ändern und löschen ​

7. Aus der Disposition ​

7.1 Vorschlag prüfen ​

7.2 Bestellungen aus Vorschlägen ​

7.3 Streckengeschäft ​

8. Wareneingang ​

8.1 Offene Belege ​

8.2 Offene Positionen ​

8.3 Buchungsvorschlag ​

8.4 Positionen manuell schließen ​

8.5 Eingangsrechnung ​

9. Shortcut-Anlage ​

9.1 POST /api/purHead/prepareAndCreate ​

9.2 POST /api/purHead/createPurchase ​

10. E-Mail, Texte, Anhänge ​

11. Transfer, Umsatz, Lieferantenportal ​

12. Weitere Beispiele ​

12.1 Drei Positionen in einer Bestellung ​

12.2 Preis der Position ändern ​

12.3 Disposition bis Bestellung ​

12.4 Wareneingang und Rest schließen ​

12.5 Mail und Portal ​

Staffel und Import ​

13. Endpoint-Katalog ​

14. Häufige Fehler ​

15. Ablauf Bestellung bis Wareneingang ​

Einkaufverwaltung – Vollständige API-Referenz

1. Grundlagen

1.1 Zwei Speicherformen

1.2 Suchschlüssel

1.3 Antwort- und Fehlerformat

2. Belegarten

3. Belegkette

3.1 Vorlage mit Vorgänger

3.2 Abhängigkeiten vor dem Speichern

4. Wichtige Felder

4.1 Kopf `PurHead`

4.2 Position `PurItem`

5. Lesen und suchen

5.1 Ein Beleg (`GET /api/purHead/{id}`)

5.2 Liste (`GET /api/purHead/`)

5.3 Suche (`GET /api/purHead/findPurchase`)

5.4 Light-Sicht (`GET /api/purHead/light/{id}`)

6. Bestellung anlegen

6.1 Einzelartikel

6.2 Anfrage

6.3 Mengenkontrakt und Abruf

6.4 Variantenartikel

6.5 Set-Artikel

6.6 Charge und Mindesthaltbarkeit

6.7 Preis und Menge vor dem Speichern

6.8 Ändern und löschen

7. Aus der Disposition

7.1 Vorschlag prüfen

7.2 Bestellungen aus Vorschlägen

7.3 Streckengeschäft

8. Wareneingang

8.1 Offene Belege

8.2 Offene Positionen

8.3 Buchungsvorschlag

8.4 Positionen manuell schließen

8.5 Eingangsrechnung

9. Shortcut-Anlage

9.1 `POST /api/purHead/prepareAndCreate`

9.2 `POST /api/purHead/createPurchase`

10. E-Mail, Texte, Anhänge

11. Transfer, Umsatz, Lieferantenportal

12. Weitere Beispiele

12.1 Drei Positionen in einer Bestellung

12.2 Preis der Position ändern

12.3 Disposition bis Bestellung

12.4 Wareneingang und Rest schließen

12.5 Mail und Portal

Staffel und Import

13. Endpoint-Katalog

14. Häufige Fehler

15. Ablauf Bestellung bis Wareneingang