ConnectCloud Developers

Send a purchase order to its distributor through EGIS (tenant:egis-order:send)

POST /api/trade/v1/purchase-orders/{id}/egis

Module: Trade · operationId: sendEgisOrder · Tag: Procurement · Auth: access token (Authorization: Bearer <accessToken>)

Orders at the distributor through EGIS (always an online order, transmitted to the distributor). The order number goes to EGIS as partner order number, which EGIS accepts once: an order is sent at most once, and a send whose answer got lost is repaired by sending again (EGIS answers that it knows the number, the order is looked up and stored). The EGIS order number and status are stored at the order (egis); a draft becomes open. The status, confirmations, delivery notes and invoices are then followed every 30 minutes; delivery notes go to the delivery note processing (inbound-delivery-notes, source egis). An order that lacks data is answered 422 with the preview; an order locked by a running workflow (e.g. an approval) is not sent (423).

Parameters

Name In Type Required Description
id path string (uuid) yes

Request body

application/json

  • comment (string): Order remark; EGIS requires it when a price deviates from the EGIS price. (max length 200)
  • completeShipment (boolean): Complete delivery wanted (supported by some distributors).
  • licence (EgisLicenceData): One set of licence data per order (articles of the types LIC, HLI, EHV, EHS; serial numbers and purchase date for CPS and EHS). Which fields a distributor needs depends on the distributor and the article.
    • authorizationNumber (string): Authorization number of the licence.
    • authorizationValidFrom (string (date)): First day of the authorization.
    • authorizationValidTo (string (date)): Last day of the authorization.
    • city (string): City.
    • contactName (string): Name of the contact person.
    • countryCode (string): Country code (ISO 3166-1 alpha-2). (max length 2)
    • domain (string): Domain of the licensee.
    • email (string): E-mail address.
    • name (string): Name of the licensee.
    • phone (string): Phone number.
    • postalCode (string): Postal code.
    • purchaseDate (string (date)): Purchase date of the licence.
    • resellerEmail (string): E-mail of the reseller.
    • serialNumbers (string): Separated by semicolons.
    • street (string): Street and house number.
  • lines (array of object): Completes purchase order lines; lines not named are resolved in EGIS.
    • lineId (string (uuid), required): Id of the purchase order line.
    • customerEmail (string (email)): Required for ESD articles. (max length 50)
    • pcsNumber (string): EGIS article number (PCS). (max length 10)
    • supplierArticleNumber (string): The distributor's article number (else found in EGIS). (max length 25)
  • requestedDeliveryDate (string (date)): Requested delivery date.

Example:

{
  "comment": "Lieferung bitte an Lager 2",
  "completeShipment": false,
  "lines": [
    {
      "customerEmail": "it@kunde.example",
      "lineId": "3f2b8e8a-1c4d-4f7e-9a0b-2c3d4e5f6a7b"
    }
  ]
}

Responses

  • 200 Sent (application/json)
  • 400 Error (application/json)
  • 401 No valid session or bearer token (no body).
  • 403 Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (application/json)
  • 404 Not found in the tenant. (application/json)
  • 409 Sent already (also by mail, recorded by hand or through a distributor API, unless that send failed), or not a draft or open order. (application/json)
  • 422 EGIS is not set up (egis_not_available), or the order lacks data EGIS needs (not_ready, details.preview names it). (application/json)
  • 423 An active workflow locks the transaction. (application/json)
  • 502 A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (application/json)

Fields of the 200 answer:

  • createdAt (string (date-time)): When the purchase order was created.
  • currency (string): Currency (ISO 4217).
  • dropShip (object): Drop shipment: the customer's delivery address (name, company, street, zip, city, country); the supplier delivers there and no stock is booked.
  • egis (EgisOrder): The order as EGIS knows it (sent through EGIS), with the distributor's follow-up documents.
    • cargoInsurance (number): Cargo insurance charged.
    • confirmations (array of object): Order confirmations of the distributor.
      • date (string (date)): Date of the confirmation.
      • distributorOrderNumber (string): The distributor's order number.
      • id (integer): EGIS id of the confirmation.
      • lines (array of object): Confirmed lines.
        • deliveryDate (string (date)): Expected delivery date.
        • position (integer): Purchase order line.
        • quantity (number): Planned delivery quantity.
        • supplierArticleNumber (string): The distributor's article number.
        • unitPrice (number): Confirmed net unit price.
    • deliveryNotes (array of object): Delivery notes of the distributor.
      • date (string (date)): Date of the delivery note.
      • deliveryNoteId (string (uuid)): The inbound delivery note made from it.
      • id (string): EGIS delivery note id.
      • lines (array of object): Delivered lines.
        • description (string): Description of the article.
        • ean (string): EAN (GTIN) of the article.
        • mpn (string): Manufacturer part number.
        • position (integer): Position number of the line.
        • quantity (number): Quantity delivered.
        • serialNumbers (array of string): Serial numbers.
        • supplierArticleNumber (string): The distributor's article number.
        • unit (string): Unit of measure.
      • number (string): The distributor's delivery note number.
      • packages (array of object): Packages of the shipment.
        • number (string): Tracking number of the package.
        • trackingUrl (string (uri)): Tracking link of the package.
      • shipper (string): Carrier of the shipment.
    • distributorId (string): EGIS distributor number.
    • distributorName (string): Name of the distributor the order went to.
    • distributorOrderNumber (string): The distributor's own order number (also stored as the external number of the order when empty).
    • freightCharge (number): Freight including additional charges.
    • invoices (array of object): Structured invoice data of the distributor (no invoice document); a second source of the purchase order check of inbound invoices.
      • currency (string): Currency (ISO 4217).
      • date (string (date)): Invoice date.
      • grossAmount (number): Gross amount of the invoice.
      • id (integer): EGIS id of the invoice.
      • lines (array of object): Invoiced lines.
        • description (string): Description of the article.
        • netTotal (number): Net total of the line.
        • position (integer): Purchase order line; missing for lines that were not ordered (freight, insurance).
        • quantity (number): Quantity invoiced.
        • supplierArticleNumber (string): The distributor's article number.
        • taxRate (number): Percent.
        • unitPrice (number): Net unit price.
      • netAmount (number): Net amount of the invoice.
      • number (string): The distributor's invoice number.
      • vatAmount (number): VAT amount of the invoice.
    • link (string (uri)): The order in the EGIS web application.
    • orderDate (string (date)): Order date at EGIS.
    • orderNumber (string): EGIS order number (leading zeros kept); invoices naming it find the order.
    • paymentMethod (string): Payment method of the order at EGIS.
    • sentAt (string (date-time)): When the order was sent to EGIS.
    • smallQuantitiesMarkup (number): Small-quantity markup charged.
    • statusCode (integer): -1 error, 0 stored in EGIS, 10 sent to the distributor, 20 rejected, 30 confirmed, 40 delivered, 50 invoiced. Orders in -1, 20 and 50 are no longer followed. (one of -1, 0, 10, 20, 30, 40, 50)
    • statusText (string): Status text of EGIS.
  • goodsReceipts (array of object): Goods receipts of the purchase order.
    • grNumber (string): Number of the goods receipt.
    • id (string (uuid)): Id of the goods receipt.
    • receivedAt (string (date-time)): When the goods were received.
    • status (string): Status of the goods receipt.
  • id (string (uuid)): Id of the purchase order.
  • lines (array of POLine): Empty in lists.
    • articleNumber (string): Article number in masterdata.
    • description (string): Description of the line.
    • ean (string): EAN (GTIN) of the article.
    • id (string (uuid)): Id of the purchase order line.
    • invoicedQty (number): Always 0.
    • mpn (string): Manufacturer part number.
    • orderedQty (number): Quantity ordered.
    • pcsNumber (string): EGIS PCS number of the article (purchase cart orders).
    • position (integer): Position number of the line.
    • productId (string (uuid)): Masterdata article (product) id.
    • receivedQty (number): Quantity received.
    • sourceLineId (string (uuid)): The sales order line the line was bought for (set by the purchase cart; never by a client).
    • supplierArticleNumber (string): The distributor's article number of the offer the purchase cart chose.
    • taxRate (number): Tax rate in percent.
    • unit (string): Unit of measure.
    • unitPrice (number): Net unit price.
  • netTotal (number): Net total of the purchase order.
  • orderDate (string (date)): Order date.
  • poNumber (string): Number of the purchase order.
  • sourceOrders (array of object): The sales orders the lines were bought for.
    • id (string (uuid)): Id of the sales order.
    • number (string): Number of the sales order.
  • sourcing (object): How a purchase cart chose the order (generated orders only). The sending channel prefers its source.
    • cartId (string (uuid)): Purchase cart the order was made from.
    • distributorId (string): Distributor the cart optimizer chose.
    • goodsCents (integer): Goods value of the shipment in cents.
    • offerKey (string): Key of the distributor offer.
    • offerKeys (array of string): Every offer key of the order when several share the supplier.
    • optimizedAt (string (date-time)): When the proposal was computed.
    • priceCents (integer): Landed cost (goods and shipment costs) in euro cents.
    • proposalId (string (uuid)): Proposal of the cart the order was made from.
    • shippingCents (integer): Shipping cost of the shipment in cents.
    • source (string): Offer source: egis, ingram, infinigate or masterdata.
  • status (PurchaseOrderStatus): (one of draft, open, partially_received, received, closed, cancelled)
  • supplierAddressId (string (uuid)): Masterdata address of the supplier.
  • supplierOrder (SupplierOrder): The order as its supplier knows it, when it was sent through another channel than EGIS.
    • attemptedAt (string (date-time)): When the last API send started.
    • awaitingDocuments (boolean): A shipped order is still followed: a shipment's delivery note, an announced invoice or a re-check of the inbound invoices is missing.
    • channel (string): How the order went out; manual: ordered by other means and recorded. (one of ingram, infinigate, mail, manual)
    • comment (string): Remark of the last send; a mail sent again without one repeats it.
    • error (string): Why the last send or refresh failed.
    • expectedDeliveryDate (string (date)): Latest delivery date the supplier expects for its open lines (Ingram: estimated, else promised delivery date, else backorder ETA).
    • followError (string): What the follow-up could not resolve and a person has to (German), e.g. shipped lines without shipment data or a shipment that could not be taken over.
    • invoices (array of object): Invoices the supplier reported.
      • date (string (date)): Invoice date.
      • grossTotal (number): Gross total.
      • netTotal (number): Net total.
      • number (string): Invoice number of the supplier.
    • lastFollowedAt (string (date-time)): When the supplier's answer last changed the order (automatic follow-up or refresh).
    • lineMap (object): Supplier line number → purchase order line id.
    • orderNumber (string): The supplier's order number (also stored as the external number of the order when empty).
    • recipient (string (email)): Where the mail went (mail).
    • rejectedLines (array of object): Lines the supplier did not take while taking the rest of the order (Ingram 207).
      • lineId (string (uuid)): Id of the purchase order line.
      • reason (string): The supplier's reason.
      • supplierLineNumber (string): The line number the supplier got (key of lineMap).
    • related (array of string): Further order numbers when the supplier split the order.
    • rematchPending (boolean): The re-check of the inbound invoices after new invoice data failed; the next run retries it.
    • requestedDeliveryDate (string (date)): Requested delivery date of the last send; a mail sent again without one repeats it.
    • revision (integer): Counts the sends of changed content (mail sent again); part of the mail's idempotency key.
    • sentAt (string (date-time)): When the order was sent.
    • sentLines (object): What an API send asked for, by supplier line number (key of lineMap); a lost answer is compared with it.
    • shipments (array of object): Shipments the supplier reported.
      • carrier (string): Carrier of the shipment.
      • deliveryNoteId (string (uuid)): The inbound delivery note made from it.
      • handledManually (boolean): A shipment given up on that a person recorded by hand (acknowledgeSupplierFollowError).
      • id (string): Unique within the order: the supplier's delivery number, else sub order and ship date (Ingram; a shipment without delivery number is taken once its ship date is named; reports of one sub order and day without delivery number are one shipment, a delivery number named later attaches to it, and every later report with that number resolves to the same shipment).
      • invoiceNumber (string): The supplier's invoice of the shipment.
      • lines (array of object): Lines of the shipment.
        • lineId (string (uuid)): Id of the purchase order line.
        • quantity (number): Quantity shipped.
        • serialNumbers (array of string): Serial numbers.
      • number (string): The supplier's delivery note number.
      • shippedAt (string (date-time)): When it was shipped.
      • subOrder (string): The supplier's sub order of the shipment (Ingram).
      • takeoverAttempts (integer): Failed hand-overs as delivery note; after 5 the follow-up stops trying (see followError).
      • takeoverError (string): Why the last hand-over failed.
      • trackingNumber (string): Tracking number of the carrier.
      • trackingUrl (string): Tracking link of the carrier.
    • shipmentsMissingSince (string (date-time)): Since when the supplier calls lines shipped that its shipments do not cover; after 14 days the order counts as shipped with a followError.
    • state (string): State at the supplier (sending, sent, confirmed, partially_shipped, shipped, cancelled, failed). (one of sending, sent, confirmed, partially_shipped, shipped, cancelled, failed)
    • statusText (string): The supplier's status text.
  • updatedAt (string (date-time)): When the purchase order was last changed.

Example 200 answer:

{
  "createdAt": "2026-11-17T10:05:00Z",
  "currency": "EUR",
  "egis": {
    "confirmations": [],
    "deliveryNotes": [],
    "distributorId": "70044",
    "distributorName": "Nordlicht IT-Distribution GmbH",
    "freightCharge": 0,
    "invoices": [],
    "link": "https://egis.example/bestellungen/0000733548",
    "orderDate": "2026-11-17",
    "orderNumber": "0000733548",
    "paymentMethod": "Rechnung",
    "sentAt": "2026-11-17T10:12:00Z",
    "statusCode": 10,
    "statusText": "An Distributor übermittelt"
  },
  "goodsReceipts": [],
  "id": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d71",
  "lines": [
    {
      "articleNumber": "HW-1004",
      "description": "USB-C Dockingstation 100 W",
      "ean": "4061234500045",
      "id": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e11",
      "invoicedQty": 0,
      "orderedQty": 10,
      "pcsNumber": "PCS400935",
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d04",
      "receivedQty": 0,
      "supplierArticleNumber": "NL-DOCKC100",
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 139
    },
    {
      "articleNumber": "HW-1007",
      "description": "Headset USB Stereo mit Geräuschunterdrückung",
      "ean": "4061234500076",
      "id": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e12",
      "invoicedQty": 0,
      "orderedQty": 10,
      "pcsNumber": "PCS400942",
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d07",
      "receivedQty": 0,
      "supplierArticleNumber": "NL-HS-USB-ANC",
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 79
    }
  ],
  "netTotal": 2180,
  "orderDate": "2026-11-17",
  "poNumber": "BE-2026-00071",
  "status": "open",
  "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
  "updatedAt": "2026-11-17T10:12:00Z"
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/trade/v1/purchase-orders/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/egis' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"comment":"Lieferung bitte an Lager 2","completeShipment":false,"lines":[{"customerEmail":"it@kunde.example","lineId":"3f2b8e8a-1c4d-4f7e-9a0b-2c3d4e5f6a7b"}]}'

View as Markdown · Interactive reference · OpenAPI