Pleaxy

Bestellungen anlegen, Rechnungen freigeben und bezahlen und den Workspace einrichten.

API-Referenz

Bestellabwicklung

Lieferanten bestätigen Bestellungen und kündigen Lieferungen an; Käufer sehen beides an der Bestellung.

Mehr zu dieser Ressource

Was ein Lieferant nach der Ausstellung zu einer Bestellung mitteilt: ob er sie annimmt, wann sie ankommt und was er versandt hat. Das ERP eines Lieferanten sendet dasselbe als cXML: Senden Sie einen ConfirmationRequest oder ShipNoticeRequest (cXML 1.2.071 Fulfill DTD) per POST an /v1/cxml/fulfillment, mit dem API-Schlüssel in X-Api-Key oder als SharedSecret des Sender und einem To-Credential mit der Domain PleaxyWorkspaceID, das den Käufer nennt; die Antwort ist ein cXML Status, und eine erneut gesendete payloadID ändert nichts. Lieferanten ohne beides können per E-Mail antworten: Jede per E-Mail an einen Lieferanten gesendete Bestellung hat eine eigene Adresse (ListPurchaseOrderEmails), an der eine Antwort oder ein cXML-Dokument bei der Bestellung abgelegt wird. Nichts davon ändert die Bestellung: Eine abgelehnte Bestellung storniert der Käufer, und eine Lieferung ist nie ein Wareneingang. Anforderer und Warenempfänger beim Käufer werden benachrichtigt, und Sync-Feed und Webhooks des Käufers erhalten purchase_order.confirmed und purchase_order.shipped.

Endpunkte

Bestellabwicklung abrufen

Gibt die Bestätigungen und Lieferungen des Lieferanten zu einer Bestellung zurück.

GET/v1/workspaces/{regionId}/purchase-orders/{poId}/fulfillment

Parameter

  • poIdstringPflicht

    Die ID der Bestellung.

  • buyerstring

    Aufrufer mit Lieferantenrolle: die Workspace-ID des Käufers, wenn zwei Käufer dieselbe ID ausgestellt haben.

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Was der Lieferant zu einer Bestellung mitgeteilt hat: seine neueste Bestätigung (Ergebnis accepted, backordered, changed, partial oder rejected, Position für Position, mit der Entscheidung des Käufers zu Änderungen), die früheren und seine Lieferungen (planned, shipped oder canceled, mit Versanddienstleister und Sendungsverfolgung). Jede Lieferung listet die dazu erfassten freigegebenen Wareneingänge auf. shippedByLine summiert die versandten Mengen; expectedDeliveryDate ist das späteste Lieferdatum, das der Lieferant angegeben hat. Ein Lieferant, bei dessen Käufern dieselbe PO-ID vorkommt, ergänzt ?buyer=<Workspace-ID des Käufers>.

Antwortfelder

  • confirmationOrderConfirmation

    Die neueste Bestätigung; fehlt, bis der Lieferant antwortet. Ihr Ergebnis gilt für die Bestellung.

  • shippedByLineArray

    Pro Position die Menge in Lieferungen mit Status shipped. Geplante und stornierte Lieferungen zählen nicht.

Fehler

  • 404 Not Found - Keine Bestellung mit dieser ID gehört Ihnen.
  • 401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
  • 403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.
GET /v1/workspaces/{regionId}/purchase-orders/{poId}/fulfillment
Anfrage
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-orders/{poId}/fulfillment" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Antwort · 200 OK
{
   "confirmation": OrderConfirmation,
   "confirmations": [
      {
         "id": "string",
         "poId": "string",
         "outcome": "accepted" | "backordered" | "changed" | "partial" | "rejected",
         "confirmId": "string",
         "deliveryDate": "YYYY-MM-DD",
         "note": "string",
         "lines": [ { "lineNo": number, "status": "accept" | "backordered" | "change" | "reject", "qty": number, "unitPrice": number, "substitute": { "supplierPartId": "string", "name": "string", "catalogItemId": "string" }, "shipmentDate": "YYYY-MM-DD", "deliveryDate": "YYYY-MM-DD", "reason": "string" } ],
         "decision": { "decision": "applied" | "declined", "at": "string", "version": number, "reason": "string" },
         "source": "portal" | "api" | "cxml",
         "createdAt": "string"
      }
   ],
   "shipNotices": [
      {
         "shipmentId": "string",
         "status": "planned" | "shipped" | "canceled",
         "shipmentDate": "YYYY-MM-DD",
         "deliveryDate": "YYYY-MM-DD",
         "carrier": "string",
         "trackingNumber": "string",
         "trackingUrl": "string",
         "lines": [ { "lineNo": number, "qty": number } ],
         "source": "portal" | "api" | "cxml",
         "createdAt": "string",
         "updatedAt": "string",
         "receipts": [ { "id": "string", "receivedAt": "YYYY-MM-DD" } ]
      }
   ],
   "shippedByLine": [ { "lineNo": number, "qty": number } ],
   "expectedDeliveryDate": "YYYY-MM-DD"
}

Änderungen der Bestätigung übernehmen

Übernimmt die geänderten Mengen und Preise des Lieferanten in die Bestellung.

POST/v1/workspaces/{regionId}/purchase-orders/{poId}/confirmations/{confirmationId}/apply

Parameter

  • poIdstringPflicht

    Die ID der Bestellung.

  • confirmationIdstringPflicht

    Die ID der Bestätigung, aus GetPurchaseOrderFulfillment.

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Übernimmt die Änderungen aus der neuesten Bestätigung des Lieferanten (Ergebnis changed) in die Positionen der Bestellung. Das ist eine gewöhnliche Positionsänderung, wie sie UpdatePurchaseOrder vornimmt: Die Bestellung erhält eine neue Version, geht erneut in die Freigabe, wenn ihre Regeln das vorsehen, und der Lieferant erhält po_changed. Antwortet mit { purchaseOrder, confirmation }, mit der übernommenen Entscheidung und der daraus entstandenen Bestellversion.

Fehler

  • 404 Not Found - Es gibt keine solche Bestellung, oder Code CONFIRMATION_NOT_FOUND.
  • 409 Conflict - Code CONFIRMATION_SUPERSEDED (der Lieferant hat seitdem erneut bestätigt), CONFIRMATION_DECIDED (bereits übernommen oder abgelehnt), NO_CHANGES oder ORDER_NOT_OPEN.
  • 401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
  • 403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.
POST /v1/workspaces/{regionId}/purchase-orders/{poId}/confirmations/{confirmationId}/apply
Anfrage
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-orders/{poId}/confirmations/{confirmationId}/apply" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Antwort · 200 OK
{
   "purchaseOrder": PurchaseOrder,
   "confirmation": OrderConfirmation
}

Änderungen der Bestätigung ablehnen

Behält die Bestellung unverändert bei, statt die Änderungen des Lieferanten zu übernehmen.

POST/v1/workspaces/{regionId}/purchase-orders/{poId}/confirmations/{confirmationId}/decline

Parameter

  • poIdstringPflicht

    Die ID der Bestellung.

  • confirmationIdstringPflicht

    Die ID der Bestätigung, aus GetPurchaseOrderFulfillment.

Body

  • reasonstring

    Begründung, bis zu 500 Zeichen. Der Lieferant sieht sie.

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Lehnt die Änderungen in der neuesten Bestätigung des Lieferanten ab. Die Bestellung ändert sich nicht; der Lieferant wird informiert, mit Ihrer Begründung, sofern Sie eine angeben. Antwortet mit der Bestätigung und ihrer Entscheidung.

Fehler

  • 404 Not Found - Es gibt keine solche Bestellung, oder Code CONFIRMATION_NOT_FOUND.
  • 409 Conflict - Code CONFIRMATION_SUPERSEDED, CONFIRMATION_DECIDED oder NO_CHANGES.
  • 401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
  • 403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.
POST /v1/workspaces/{regionId}/purchase-orders/{poId}/confirmations/{confirmationId}/decline
Anfrage
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-orders/{poId}/confirmations/{confirmationId}/decline" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{
   "reason": "string"
}
Antwort · 200 OK
OrderConfirmation

E-Mails zu einer Bestellung auflisten

Gibt die eigene E-Mail-Adresse einer Bestellung und die dort eingegangenen E-Mails zurück.

GET/v1/workspaces/{regionId}/purchase-orders/{poId}/emails

Parameter

  • poIdstringPflicht

    Die ID der Bestellung.

  • buyerstring

    Lieferanten: die Workspace-ID des Käufers, wenn zwei Käufer dieselbe ID ausgestellt haben.

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Jede per E-Mail an ihren Lieferanten gesendete Bestellung erhält eine eigene Adresse, als zweites Reply-To in der Bestell-E-Mail und auf das PDF gedruckt. Die Antwort eines Lieferanten oder ein cXML ConfirmationRequest oder ShipNoticeRequest, den sein System dorthin sendet, wird bei der Bestellung abgelegt, neueste zuerst. Ein cXML-Dokument von einem verifizierten Absender (dem Ansprechpartner des Lieferanten oder seiner Firmendomain, geprüft mit SPF, DKIM und DMARC) wird sofort erfasst (outcome applied). Eine einfache E-Mail liest der Pleaxy Assistant als Entwurf einer Bestätigung oder eines Lieferavis, und ein Dokument von einem Absender, den Pleaxy nicht verifizieren kann, wird zurückgehalten: Beide warten, bis jemand sie mit RecordPurchaseOrderEmail erfasst. address fehlt, bis die Bestellung ausgestellt ist.

Fehler

  • 404 Not Found - Es gibt keine solche Bestellung.
  • 401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
  • 403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.
GET /v1/workspaces/{regionId}/purchase-orders/{poId}/emails
Anfrage
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-orders/{poId}/emails" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Antwort · 200 OK
{
   "address": "string",
   "emails": [
      {
         "id": "string",
         "from": "string",
         "subject": "string",
         "receivedAt": "string",
         "trust": "verified" | "unverified",
         "kind": "cxml" | "text",
         "outcome": "applied" | "draft" | "held" | "noAction" | "test" | "failed" | "ignored",
         "reasonCode": "string",
         "summary": "string",
         "text": "string",
         "attachments": [ { "name": "string", "contentType": "string", "size": number } ],
         "draft": { "kind": "confirmation" | "shipNotice", "summary": "string", "confirmation": object, "shipNotice": object },
         "result": { "confirmationId": "string", "shipmentId": "string" },
         "decision": { "action": "recorded" | "dismissed", "by": "string", "at": "string" }
      }
   ]
}

E-Mail zu einer Bestellung erfassen

Erfasst den Entwurf einer E-Mail als Bestätigung oder Lieferavis des Lieferanten.

POST/v1/workspaces/{regionId}/purchase-orders/{poId}/emails/{emailId}/record

Parameter

  • poIdstringPflicht

    Die ID der Bestellung.

  • emailIdstringPflicht

    Die ID der E-Mail, aus ListPurchaseOrderEmails.

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Erfasst den Entwurf einer E-Mail mit outcome draft oder held als Auftragsbestätigung oder Lieferavis des Lieferanten, mit E-Mail als Quelle und denselben Prüfungen wie ConfirmPurchaseOrder und SendShipNotice. Beantwortet die E-Mail mit der Entscheidung. Ein Käufer muss Bestellungen bearbeiten dürfen.

Fehler

  • 400 Bad Request - Der Entwurf nennt eine unbekannte Position oder eine Position, die nicht versendet werden kann.
  • 404 Not Found - Es gibt keine solche Bestellung oder E-Mail.
  • 409 Conflict - Code EMAIL_DECIDED (bereits erfasst oder verworfen), NOTHING_TO_RECORD oder ORDER_NOT_OPEN.
  • 401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
  • 403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.
POST /v1/workspaces/{regionId}/purchase-orders/{poId}/emails/{emailId}/record
Anfrage
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-orders/{poId}/emails/{emailId}/record" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Antwort · 200 OK
InboundEmail

E-Mail zu einer Bestellung verwerfen

Lässt die Bestellung, wie sie ist, statt zu erfassen, was eine E-Mail verlangt.

POST/v1/workspaces/{regionId}/purchase-orders/{poId}/emails/{emailId}/dismiss

Parameter

  • poIdstringPflicht

    Die ID der Bestellung.

  • emailIdstringPflicht

    Die ID der E-Mail, aus ListPurchaseOrderEmails.

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Markiert eine E-Mail als verworfen: Es wird nichts erfasst. Beantwortet die E-Mail mit der Entscheidung.

Fehler

  • 404 Not Found - Es gibt keine solche Bestellung oder E-Mail.
  • 409 Conflict - Code EMAIL_DECIDED: bereits erfasst oder verworfen.
  • 401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
  • 403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.
POST /v1/workspaces/{regionId}/purchase-orders/{poId}/emails/{emailId}/dismiss
Anfrage
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-orders/{poId}/emails/{emailId}/dismiss" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Antwort · 200 OK
InboundEmail
Kontakt aufnehmen