Endpoints꞉ Consignments - Fastway-Couriers-South-Africa/myFastway.ApiClient GitHub Wiki
Contents
Endpoints
| Endpoint | Verb | Paging | Description |
|---|---|---|---|
| /api/consignments | GET | Y | returns all consignments |
| /api/consignments/{id} | GET | returns consignment for a given Id | |
| /api/consignments?from={from}&to={to} | GET | Y | returns consignments for a given date range |
| /api/consignments/{id}/labels | GET | returns all labels for a given consignment | |
| /api/consignments/{id}/labels/{label} | GET | returns a label for a given consignment | |
| /api/consignments/pending | GET | returns pending consignments | |
| /api/consignments/quote | POST | returns quote | |
| /api/consignments | POST | create new consignments | |
| /api/consignments/deleted-reasons | GET | gets the deleted reason id's | |
| /api/consignments/{id}/files/document-types | POST | uploads a document of a given type to a consignment | |
| /api/consignments/{id}/pickup-details | POST | updates the collection details for a given id | |
| /api/consignments/{id}/reason/{deleteReasonId} | DELETE | deletes a consignment with a given reason | |
| /api/consignments/{id}/undelete | PUT | restores a deleted consignment |
Quick Start
Minimum Information Required to Consign
The following is the minimum amount of information required to create a consignment. All fields below are mandatory. The supplied address must conform to the Address Validation process
Consigning a parcel
{
"To": {
"ContactName": "",
"PhoneNumber": "",
"Email": "",
"Address": {
"StreetAddress": "",
"Locality": "",
"StateOrProvince": "",
"PostalCode": "",
"Country": ""
}
},
"Items": [
{
"Quantity": 0,
"PackageType": "P",
"WeightDead": 0,
"WeightCubic": 0,
"Length": 0,
"Width": 0,
"Height": 0
}
]
}
Consigning a satchel
{
"To": {
"ContactName": "",
"PhoneNumber": "",
"Email": "",
"Address": {
"StreetAddress": "",
"Locality": "",
"StateOrProvince": "",
"PostalCode": "",
"Country": ""
}
},
"Items": [
{
"Quantity": 0,
"PackageType": "S",
"SatchelSize": "A4"
}
]
}
Consigning both a parcel and satchel
{
"To": {
"ContactName": "",
"PhoneNumber": "",
"Email": "",
"Address": {
"StreetAddress": "",
"Locality": "",
"StateOrProvince": "",
"PostalCode": "",
"Country": ""
}
},
"Items": [
{
"Quantity": 0,
"Reference": "",
"PackageType": "P",
"WeightDead": 0,
"WeightCubic": 0,
"Length": 0,
"Width": 0,
"Height": 0
},
{
"Quantity": 0,
"PackageType": "S",
"SatchelSize": "A4"
}
]
}
Request Objects
Create Consignment with New Contact (receiver) Request
This request will create a consignment using the Contact information provided. This contact will be saved to your address book if "Automatically save new contacts to address book" has been selected under Options | Consignments (website)
{
"To": {
"ContactCode": "",
"BusinessName": "",
"ContactName": "",
"PhoneNumber": "",
"Email": "",
"Address": {
"StreetAddress": "",
"AdditionalDetails": "",
"Locality": "",
"StateOrProvince": "",
"PostalCode": "",
"Country": ""
}
},
"Items": [
{
"Quantity": 0,
"Reference": "",
"PackageType": "P",
"WeightDead": 0,
"WeightCubic": 0,
"Length": 0,
"Width": 0,
"Height": 0
},
{
"Quantity": 0,
"PackageType": "S",
"SatchelSize": "A4"
}
],
"Services": [
{
"ServiceCode": "",
"ServiceItemCode": ""
}
],
"InstructionsPublic": "",
"InstructionsPrivate": "",
"ExternalRef1": "",
"ExternalRef2": ""
}
Create Consignment with known Contact (receiver) Request
This request will use a previously saved contact using the ContactId provided
{
"To": {
"ContactId": 0
},
"Items": [
{
"Quantity": 0,
"Reference": "",
"PackageType": "P",
"WeightDead": 0,
"Length": 0,
"Width": 0,
"Height": 0
},
{
"Quantity": 0,
"Reference": "",
"PackageType": "S",
"SatchelSize": "A4"
}
],
"Services": [
{
"ServiceCode": "",
"ServiceItemCode": ""
}
],
"InstructionsPublic": "",
"InstructionsPrivate": "",
"ExternalRef1": "",
"ExternalRef2": ""
}
Create Consignment with known My-Item Request
A previously saved 'My Item' maybe been used by providing a myItemId
{
"To": {
"ContactId": 0
},
"Items": [
{
"myItemId": 0,
"Quantity": 0,
"Reference": ""
}
],
"Services": [
{
"ServiceCode": "",
"ServiceItemCode": ""
}
],
"InstructionsPublic": "",
"InstructionsPrivate": "",
"ExternalRef1": "",
"ExternalRef2": ""
}
Create Consignment with Optional Services
Opt-In Services can be added to a Consignment Request object via the Services property (Array). Each Service is added to the array as object containing the Service Code and the Service Item code.
{
"Services": [
{
"ServiceCode": "",
"ServiceItemCode": ""
}
]
}
Example: To add a 'Leave at door' Service to a consignment the object would be
{
"Services": [
{
"ServiceCode": "DELOPT",
"ServiceItemCode": "ATL"
}
]
}
Please see Services to see the available options (note: these may have to be set up by your Regional Franchise in advance)
Response Object
The following is the repsonse object returned from /api/consignments/{id}
{
"data": {
"conId": 0,
"from": {
"contactId": 0,
"code": "",
"businessName": "",
"contactName": "",
"phoneNumber": "",
"email": "",
"instructions": "",
"address": {
"addressId": 0,
"streetAddress": "",
"additionalDetails": "",
"locality": "",
"stateOrProvince": "",
"postalCode": "",
"country": "",
"lat": 0.0,
"lng": 0.0,
"userCreated": false,
"hash": ""
}
},
"to": {
"contactId": 0,
"code": "",
"businessName": "",
"contactName": "",
"phoneNumber": "",
"email": "",
"instructions": "",
"address": {
"addressId": 0,
"streetAddress": "",
"additionalDetails": "",
"locality": "",
"stateOrProvince": "",
"postalCode": "",
"country": "",
"lat": 0.0,
"lng": 0.0,
"userCreated": false,
"hash": ""
}
},
"items": [
{
"conItemId": 0,
"reference": "Parcel",
"packageType": "P",
"myItemId": null,
"satchelSize": "",
"weightDead": 0.0,
"length": 0.0,
"width": 0.0,
"height": 0.0,
"weightCubic": 0.0,
"label": "",
"price": 0.0,
"tax": 0.0,
"total": 0.0,
"services": []
}
],
"price": 0.0,
"tax": 0.0,
"total": 0.0,
"itemCount": 1,
"instructionsPublic": "",
"instructionsPrivate": "",
"externalRef1": "",
"externalRef2": "",
"services": [
{
"serviceItemId": 0,
"serviceDescription": "",
"price": 0.0,
"tax": 0.0,
"total": 0.0
}
]
}
}
items.packageType (length: 1) These Package Types are available
items.satchelSize (length: 2) These Satchel Sizes are available
items.weightCubic - (read only) The calculated cubic weight of the package from the length, width and height dimensions
items.length - The length of the parcel (cm)
items.width - The width of the parcel (cm)
items.height - The height of the parcel (cm)
instructionsPublic (length: 500) Special Instructions, which a printed on the label. Note: Only the first 150 characters will be printed on the label
instructionsPrivate (length: 500) Private (internal) instructions, not visible to the receiver
externalRef1 (length: 100) reference field which can be used to link consignments to external systems
externalRef2 (length: 100) reference field which can be used to link consignments to external systems
Get By Date Range
/api/consignments?from={from}&to={to}
The format for the from and to query params is YYYYMMDD, e.g. for consignments between the 1st and 3rd of August 2018, the query string would be /api/consignments?from=20180801&to=20180603
Response Object
{
"data": [
{
"conId": 0,
"toBusinessName": "",
"toContactName": "",
"toStreetAddress": "",
"toAdditionalDetails": "",
"toLocality": "",
"toStateOrProvince": "",
"toPostalCode": "",
"price": 0.0,
"tax": 0.0,
"total": 0.0,
"totalInvoiced": 0.0,
"itemCount": 0,
"externalRef1": "",
"externalRef2": "",
"createdOn": "2018-08-17T10:12:15.5733"
}
]
}
Labels
/api/consignments/{id}/labels?pageSize={pageSize}
/api/consignments/{id}/labels/{label}?pageSize={pageSize}
Request parameters
- pageSize=A4 (default) - page size will be A4 with 4 labels per page
- pageSize=4x6 - page size will be 4x6 inch, with one label per page
Response Object
Getting labels returns a byte array of a pdf file containing the labels
Note: By default, only labels without scanning events will be available for download i.e. once a courier has interacted with a parcel, the label is no longer available for download.
Pending
/api/consignments/pending
Returns newly created consignments that are yet to have any scanning events (courier interaction) associated with them
Response Object
{
"data": [
{
"conTotal": 0.0,
"conTotalInvoiced": 0.0,
"conTotalPending": 0.0,
"toAddress": "",
"conId": 0,
"toBusinessName": "",
"toContactName": "",
"createdOn": "2018-08-23T14:17:55.0867"
},
{
"conTotal": 0.0,
"conTotalInvoiced": 0.0,
"conTotalPending": 0.0,
"toAddress": "",
"conId": 0,
"toBusinessName": "",
"toContactName": "",
"createdOn": "2018-08-23T14:16:05.5367"
}
]
}
Quote
/api/consignments/quote
Request Object
The quote end point accepts a consignment object in one of the shapes provided above.
Response Object
{
"data": {
"price": 0.0,
"tax": 0.0,
"total": 0.0,
"items": [
{
"productType": "Labels",
"description": "A4 satchel",
"quantity": 1,
"price": 0.0,
"tax": 0.0,
"total": 0.0
},
{
"productType": "Labels",
"description": "Parcel of 5.00kg dead, 0.63kg cubic (25cm x 10cm x 10cm)",
"quantity": 1,
"price": 0.0,
"tax": 0.0,
"total": 0.0
}
]
}
}
items.productType The type of product being quoted on. This is either labels (which includes labels and satchels) or service which is a mandatory service associated with item e.g. an on-forward / rural service
Quote (Version 2)
/api/consignments/quote?api-version=2
locationDetailsKey The cache key returned from the Location endpoint
Request Object
{
"LocationDetailsKey": "{{locationDetailsKey}}",
"Items": [
{
"Quantity": 1,
"Reference": "",
"PackageType": "P",
"WeightDead": 1,
"Length": 1,
"Width": 1,
"Height": 1
},
{
"Quantity": 1,
"Reference": "",
"PackageType": "",
"SatchelSize": "A4"
}
],
"Services": []
}
Response Object
An array of quote objects are returned, 1 for each SLA Service available, e.g. if both Economy and Priority services are available, 2 quotes will be returned in the array
{
"data": [
{
"sla": {
"sLACode": "",
"sLAName": "",
"sLADays": 0,
"sLADescription": ""
},
"price": 0.0,
"tax": 0.0,
"total": 0.0,
"items": [
{
"productType": "Labels",
"description": "Parcel of 1kg dead, 0.10kg cubic (1cm x 1cm x 1cm)",
"quantity": 1,
"itemPrice": 0.0,
"price": 0.0,
"tax": 0.0,
"total": 0.0
},
{
"productType": "Labels",
"description": "A4 satchel",
"quantity": 1,
"itemPrice": 0.0,
"price": 0.0,
"tax": 0.0,
"total": 0.0
}
]
}
]
}
sla (Nullable) The service (Economy, Priority) available
Consign
Request Object
The consign end point accepts a Request Object
Response Object
{
"data": {
"consignmentId": 0
}
}
Delete
/api/consignments/{id}/reason/{deleteReasonId}
Deletes a consignment for the given reason (see below)
Deleted Reasons
Response Object
{
"data": [
{
"id": 3,
"description": "Created in Error"
},
{
"id": 4,
"description": "Duplicate"
}
]
}
Undelete
/api/consignments/{id}/undelete
Restores a deleted consignment
File Upload
/api/consignments/{id}/files/document-types/{documentTypeId}
Uploads a document of a given Document Type to an exsting consigment. The post should be of a multipart/form-data type, adding to the files collection (see below)
Pickup Details
/api/consignments/{id}/pickup-details
Request Object
{
"preferredPickupDate": "yyyy-MM-ddTHH:mm:ss",
"preferredPickupCycleId": 1,
"fromInstructionsPublic": "pickup instructions"
}
Reponse
Returns Status Code 200 (OK)
Please see Collections for further information