Parts Orders API

Parts Orders
 1.0.0 
OAS3

Introduction

Place a parts order with a dealer, and retrieve the order details.

Definitions

A selection of fields that require more verbose explanations.

  • orderType is used to communicate the urgency of the order. The following abbreviations are availabe in the API, although dealers may not make use of them all:
    • EMG - Emergency
    • VOR - Vehicle Off Road
    • STK - Stock Order
    • DPO - Daily Parts Order
    • COL - Collection
  • orderReference is usually an external reference used by the customer to identify the order. Some dealers may require this to be added.

Parts Orders Status Fields

Each line on a parts order, and the order itself, have status fields. Note that not all dealers support all statuses.

  • partsOrderLineStatus shows the progress of each parts line on the order.

    • OPEN - A temporary or draft line has been created on the order in the DMS.
    • RESERVED - The part is marked as Reserved in the DMS, or is in the process of being picked up from the relevant parts bin.
    • ISSUED - The part has been picked up and is ready to be packed.
    • BACKORDER - The part was not in stock and is on order
    • PACKED - The part has been packed and is ready for delivery
    • INTRANSIT - The part is en route to the customer
    • DELIVERED - The part has been delivered
    • CANCELLED - The part line has been cancelled
    • INVOICED - The customer has been invoiced for the part

  • orderStatus shows the progress of the order, and is based on the statuses of the parts lines.

    • CREATED - The order has been created, but none of the parts have yet been reserved, issued or ordered.
    • CONFIRMED - One or more of the parts on the order have been reserved or issued.
    • INPROGRESS - The order is being processed, and picking or back orders of at least one of the parts on the order have started.
    • SHIPPED - At least one of of the parts on the order is being or has been shipped to the customer. Parts orders may be shipped in multiple batches, depending on availability.
    • CLOSED - The order is closed. All the parts have been either invoiced or cancelled.

Change History

[1.0.0]

  • brandCode data changed to a short code for the brand
Servers
Computed URL:https://api.eu-stage.keyloop.io/sample/sample/v1

Server variables

enterpriseIdstoreId
enterpriseId
storeId

Parts Orders

Create and get parts orders

POST​/parts-orders
Create Parts Order

Create a new parts order in the DMS. Note that orders can only be created for existing customers.

If mandatoryVehicleReferences fields were provided in the /price-availability response, then these are mandatory when placing an order.

If alternateDeliveryAddress is left blank, the order will be delivered to the customer's invoice address.

Parameters

No parameters

Request body

Payload for creating new parts order

{
  "customerId": "123e4569-e89b-12e3-a452-426655440001",
  "companyId": "345e7890-f23y-12d3-a456-537766551112",
  "orderContact": {
    "name": "Cate ContactPerson",
    "phone": "123-4567890",
    "email": "cate.contactperson@company.com",
    "companyName": "Company Ltd."
  },
  "alternateDeliveryAddress": {
    "streetName": "Narrow street",
    "postalCode": 123456,
    "city": "Smalltown",
    "countryCode": "GB"
  },
  "orderType": "VOR",
  "orderReference": "Parts for Golf XN06 TTY",
  "parts": [
    {
      "part": {
        "partId": "S7654321",
        "brandCode": "S",
        "partCode": 7654321
      },
      "quantity": 10,
      "mandatoryVehicleReferences": [
        {
          "type": "KEYNUMBER",
          "value": "AO339223X/2926"
        }
      ]
    }
  ]
}

Responses

CodeDescriptionLinks
201

Success

Media type
Controls Accept header.
{
  "partsOrderId": 123445677,
  "partsOrderDateTime": "2019-07-21T17:32:28.000Z",
  "orderStatus": "CONFIRMED",
  "customer": {
    "customerId": "00000000-0000-0000-0000-000000000000",
    "familyName": "OrderPerson",
    "givenName": "Ollie",
    "titleCommon": "Mr."
  },
  "company": {
    "companyId": "00000000-0000-0000-0000-000000000000",
    "name": "Company Ltd."
  },
  "orderContact": {
    "name": "Cate ContactPerson",
    "phone": "123-4567890",
    "email": "cate.contactperson@company.com",
    "companyName": "Company Ltd."
  },
  "deliveryAddress": {
    "streetName": "Narrow street",
    "postalCode": 123456,
    "city": "Smalltown",
    "countryCode": "GB"
  },
  "orderType": "VOR",
  "orderReference": "Parts for Golf XN06 TTY",
  "parts": {
    "orderLineId": "00000000-0000-0000-0000-000000000000",
    "partId": "S7654321",
    "quantity": 10,
    "unitOfMeasure": {
      "unit": "PIECE",
      "value": 1
    },
    "unitOfSale": 1,
    "partsOrderLineStatus": "RESERVED",
    "mandatoryVehicleReference": {
      "type": "KEYNUMBER",
      "value": "AO339223X/2926"
    },
    "listPrice": {
      "netValue": 100,
      "grossValue": 120,
      "taxValue": 20,
      "taxRate": 20,
      "currencyCode": "EUR"
    },
    "orderPrice": {
      "netValue": 100,
      "grossValue": 120,
      "taxValue": 20,
      "taxRate": 20,
      "currencyCode": "EUR"
    }
  }
}
No links
202

Success

Media type
{
  "partsOrderId": 123445677
}
No links
400

Bad Request

Media type
{
  "correlationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "message": "Invalid request",
  "details": [
    {
      "field": "Status",
      "value": "string",
      "issue": "The value 'XYZ' is not valid."
    }
  ],
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href": "string",
      "title": "string"
    }
  ]
}
No links
GET​/parts-orders​/{partsOrderId}
Get Parts Order

Get the details of a specific parts order, including an up-to-date list of parts, their prices, quantities and statuses.
Note, that parts orders are not retained indefinitely, and dealers can choose how long they remain in the system after the order has been fulfilled.

Parameters

NameDescription
partsOrderId *
string
(path)

The unique ID of the parts order.

Responses

CodeDescriptionLinks
200

Success

Media type
Controls Accept header.
{
  "partsOrderId": 123445677,
  "partsOrderDateTime": "2019-07-21T17:32:28.000Z",
  "orderStatus": "CONFIRMED",
  "customer": {
    "customerId": "00000000-0000-0000-0000-000000000000",
    "familyName": "OrderPerson",
    "givenName": "Ollie",
    "titleCommon": "Mr."
  },
  "company": {
    "companyId": "00000000-0000-0000-0000-000000000000",
    "name": "Company Ltd."
  },
  "orderContact": {
    "name": "Cate ContactPerson",
    "phone": "123-4567890",
    "email": "cate.contactperson@company.com",
    "companyName": "Company Ltd."
  },
  "deliveryAddress": {
    "streetName": "Narrow street",
    "postalCode": 123456,
    "city": "Smalltown",
    "countryCode": "GB"
  },
  "orderType": "VOR",
  "orderReference": "Parts for Golf XN06 TTY",
  "parts": {
    "orderLineId": "00000000-0000-0000-0000-000000000000",
    "partId": "S7654321",
    "quantity": 10,
    "unitOfMeasure": {
      "unit": "PIECE",
      "value": 1
    },
    "unitOfSale": 1,
    "partsOrderLineStatus": "RESERVED",
    "mandatoryVehicleReference": {
      "type": "KEYNUMBER",
      "value": "AO339223X/2926"
    },
    "listPrice": {
      "netValue": 100,
      "grossValue": 120,
      "taxValue": 20,
      "taxRate": 20,
      "currencyCode": "EUR"
    },
    "orderPrice": {
      "netValue": 100,
      "grossValue": 120,
      "taxValue": 20,
      "taxRate": 20,
      "currencyCode": "EUR"
    }
  }
}
No links
404

Not Found

Media type
{
  "correlationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "message": "Invalid request",
  "details": [
    {
      "field": "Status",
      "value": "string",
      "issue": "The value 'XYZ' is not valid."
    }
  ],
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href": "string",
      "title": "string"
    }
  ]
}
No links

Schemas

MandatoryVehicleReferences
PartsOrder
PartsOrder202Response
PartsOrderCreateRequest
PartsOrderLine
PartsOrderLineSimple
Parts Order Line Status
Parts Order Status
Parts Order Type
ValidationError