Shipping API

Shipping
 0.0.6 
OAS3

Introduction

Draft APIs to provide a parts proof of delivery APIs that might extend to additional endpoints to handle shipping of any kind.

Definitions

The following definitions are pertinent to the usage of this API.

  • Route is the route that a van will take when delivering or picking up parts. It comprises a unique ID, A name and a list of trips.
  • A Trip is a collection of stops, and the date & time the trip is scheduled to start. A trip will use a route.
  • A Stop is a location where a delivery or a pickup has to be made, and the shipments associated with that stop.
  • A Shipment is the thing that has to be delivered or picked up. It is a box of parts or some other package with a unique ID/barcode.
  • A Receipt is the formal acceptance of the shipment by the customer, the customer's delegate or, in the case of a pickup, the van driver.

Change Log

  • [0.0.1] First draft
  • [0.0.2] Package modifed to be a Shipment, and experimenting with Routes
  • [0.0.3]
    • receiptType changed to shipmentType and moved to shipments.
    • Fields to show the total shipments by type have been added to Stop.
    • A status field has been added to trips
    • In GET Trip Details, tripId has been changed to a path parameter.
    • GET Routes now calls the trips as an array, and the q search parameter has been renamed query
    • In Receipt the signatureImage field name has changed to signatureImageURL
    • Tweaks have been made to the defintions.
  • [0.0.4]
    • Changed Receipt summary to reference Create not Post
    • Removed components requestBodies and ReceiptCreate
    • Changed URL from localhost
    • Removed references to repair-orders and replace with shipping
    • Changed Trip definition in Route to use component
    • Changed initial values of RouteId, TripId, StopId and ShipmentId
    • Changed StopsList to StopList
    • Changed description of RoutesSearchResponse description
  • [0.0.5]
    • [MIDWARE-2412] Added PartsInShipment to the Shipment SCHEMA
    • Updated contacts
  • [0.0.6]
    • Removed StopList and declare Stops like all other arrays
Servers
Computed URL:https://api.eu-stage.keyloop.io/sample/sample/v1

Server variables

enterpriseIdstoreId
enterpriseId
storeId

Routes

Shipping routes

GET​/shipping​/routes
Find a shipping route and its trips

Use this endpoint to return a list of routes and trips. The response returns trips with start times up to 12 hours in the past, and 24 hours in the future.

Parameters

NameDescription
query
string
(query)

The search string with which the end user wishes to search for the route. Omitting the query parameter will return all routes.

Responses

CodeDescriptionLinks
200

The search results

Media type
Controls Accept header.
[
  {
    "routeId": "DEL",
    "name": "Huddersfield-Wakefield",
    "trips": [
      {
        "tripId": "DEL-2019-08-28T12:00:00",
        "scheduledStart": "2019-07-21T17:32:28.000Z",
        "status": "INPROGRESS",
        "routeName": "Huddersfield Wakefield",
        "routeId": "DEL",
        "stops": [
          {
            "stopId": "C0001",
            "stopName": "Joe's Garage",
            "stopAddress": {
              "streetName": "Mill Lane",
              "houseNumber": 7,
              "postalCode": "SE4 1UU",
              "city": "London",
              "countryCode": "GB"
            },
            "totalDeliveries": 7,
            "totalPickups": 0,
            "shipments": [
              {
                "shipmentId": "BOX00012",
                "shipmentType": {
                  "Type": "DELIVERY"
                },
                "barCode": "00012-30510-10001-01011-20951",
                "shipmentAddress": {
                  "streetName": "Mill Lane",
                  "houseNumber": 7,
                  "postalCode": "SE4 1UU",
                  "city": "London",
                  "countryCode": "GB"
                },
                "customer": {
                  "name": "Joe",
                  "companyName": "Joe's Garage"
                },
                "contact": {
                  "name": "Frank",
                  "phone": "07000 000000",
                  "email": "frank@joesgarage.com",
                  "companyName": "Joe's Garage"
                },
                "partsInShipment": [
                  {
                    "partId": "S7654321",
                    "brandCode": "S",
                    "partCode": "7654321",
                    "description": "Oil filter",
                    "quantity": 10
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
]
No links

Trips

Shipping trips

GET​/shipping​/trips​/{tripId}
Get the details of a trip

Use this endpoint to retrieve the details of a specific trip.

Parameters

NameDescription
tripId *
string
(path)

The unique ID of the trip.

Responses

CodeDescriptionLinks
200

The details of the requested trip

Media type
Controls Accept header.
{
  "tripId": "DEL-2019-08-28T12:00:00",
  "scheduledStart": "2019-07-21T17:32:28.000Z",
  "status": "INPROGRESS",
  "routeName": "Huddersfield Wakefield",
  "routeId": "DEL",
  "stops": [
    {
      "stopId": "C0001",
      "stopName": "Joe's Garage",
      "stopAddress": {
        "streetName": "Mill Lane",
        "houseNumber": 7,
        "postalCode": "SE4 1UU",
        "city": "London",
        "countryCode": "GB"
      },
      "totalDeliveries": 7,
      "totalPickups": 0,
      "shipments": [
        {
          "shipmentId": "BOX00012",
          "shipmentType": {
            "Type": "DELIVERY"
          },
          "barCode": "00012-30510-10001-01011-20951",
          "shipmentAddress": {
            "streetName": "Mill Lane",
            "houseNumber": 7,
            "postalCode": "SE4 1UU",
            "city": "London",
            "countryCode": "GB"
          },
          "customer": {
            "name": "Joe",
            "companyName": "Joe's Garage"
          },
          "contact": {
            "name": "Frank",
            "phone": "07000 000000",
            "email": "frank@joesgarage.com",
            "companyName": "Joe's Garage"
          },
          "partsInShipment": [
            {
              "partId": "S7654321",
              "brandCode": "S",
              "partCode": "7654321",
              "description": "Oil filter",
              "quantity": 10
            }
          ]
        }
      ]
    }
  ]
}
No links
404

Validation Error

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

Receipts

Shipping receipts

POST​/shipping​/receipts
Create a receipt

Post the receipt from a delivery/pickup to the DMS.

Parameters

No parameters

Request body

Information required to create a new Receipt

{
  "receiptReference": "DEL",
  "shipmentType": {
    "Type": "DELIVERY"
  },
  "tripId": "DEL-2019-08-28T12:00:00",
  "stopId": "C0001",
  "shipmentId": "BOX00012",
  "driver": {
    "name": "Joe Smith",
    "driverId": "1234567"
  },
  "signature": {
    "signedForBy": "Jo Smith",
    "company": "Acme Corp",
    "signedForAlternateAddress": {
      "streetName": "Mill Lane",
      "houseNumber": 7,
      "postalCode": "SE4 1UU",
      "city": "London",
      "countryCode": "GB"
    },
    "signedForLocation": {
      "latitude": "51.419857",
      "longditude": "-1.514089"
    },
    "signatureImageURL": "https://domain.name/path/12341251123412.jpg"
  }
}

Responses

CodeDescriptionLinks
201

Success

No links
400

Validation Error

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

RoutesSearchResponse
Route
Receipt
Trip
Stop
Shipment
ContactSimple
Contact
ValidationError
Address.Physical
PartInShipment
Response.Error
Response.Error.Details
Link method
Receipt_shipmentType
Receipt_driver
Receipt_signature_signedForLocation
Receipt_signature
Shipment_shipmentType