Get Started

3 Get Started

Quick Start

Complete these tasks to set up your environment and use Collect and Receive.

Task 1: Obtain Account Information

From your account administrator, obtain the applicable account credentials to enable you to access Collect and Receive functions and resources.

Specifically, you will need one of the following:

User name and password
Client ID and secret

Task 2: Obtain Access Token

After you set up your REST client, follow steps in Authenticate section to obtain an access token in response.

Task 3: Send a Request

You can send a request to ensure that your connection works, for example, retrieving a count of orders.

curl -i -X GET -H "Authorization:Bearer <access-token>" https://<HOSTNAME>:<PORT>/<service>/api/delivery/v2/delivery/count

If the request is successful, you should receive a 200 response with a body such as the following:

Congratulations!

Authenticate

Collect and Receive uses OAuth 2.0 protocol for authentication, enabling clients to connect securely to the server using Client Credential authorization grant.

Note:

Ensure that you have the appropriate authentication credentials.

You access the Collect and Receive REST resources over HTTPS and you must provide the following information for authentication:

User name and password for your Collect and Receive or an appropriate application client_id and secret.
The client’s scope.
The authorization grant type, which is client_credentials.

For example, to authenticate using cURL:

Construct a POST request using the -X POST cURL option.
Prepare the request body encoded in application/x-www-form-urlencoded content type using -d cURL option.
Pass the required credential, scope, and grant type.

The following provides an example cURL command:

       curl -i -X POST -u <client id>:<client secret> -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials&scope=<scope>" https://<host>:<PORT>/oauth2/v2/token

Send Requests

Use these guidelines when sending requests using the Collect and Receive REST API.

URL Structure

Here's the URL structure for the requests:

https://<HOSTNAME>:<PORT>/<service>/<resource-path>

Where:

<HOSTNAME>:<PORT>: Host and port where Collect and Receive is running.
<service>: The service identifier.<resource-path>: Relative path that defines the resource.

Supported Methods

You can perform basic CRUD operations (create, read, update, and delete) on a resource by using standard HTTP method requests, as summarized in the following table.

Table 3-1 HTTP Method Requests

HTTP Method	Description
`GET`	Retrieve information about the resource.
`POST`	Create the resource.
`PUT`	Update the resource.
`DELETE`	Delete the resource.

Media Types

The following media types are supported by the Collect and Receive REST API:

application/json

Supported Headers

The Collect and Receive REST API supports the following headers that may be passed in the header section of the HTTP request or response.

Table 3-2 Headers

Header	Description	Example
`Authorization`	Supply the bearer token to access OAuth 2.0 protected resources.	`Authorization: Bearer <access-token>`
`Accept`	Indicate the content type the client is able to understand.	`Accept: application/json`
`Content-Type`	Media type of the body of the request/response.	`Content-Type: application/json`

Search Conventions

This section describes the Search Conventions.

Where

The where parameter is used to filter results within list and count requests. It is a JSON object containing query parameters for filtering results. Fields to be filtered on may be provided in the form of a dot-notated path named for the fields known to this resource. For example, a delimited field named child.id would filter by the entity field of this resource named child and that entity has a field named id.

Querying is supported in three ways:

If a single value is provided, it is treated as a baseline. If the single value is a character type, then the value is used as the basis for a "like" or "startsWith" comparison. For example, `{"child.name":"Jo"}` would match Joe, John, and so on. For all other types, it serves as the lower bound of a >= comparison, {"minAmount":100.00}.
If an array is provided, the values within it are treated as "equals" or "in" values depending upon the element count, for example {"id":[1, 2, 3]}.
If an object is provided, a variety of options are supported:
- Fields named "from" and "to" within the object, will serve as lower and/or upper bounds for a range-based query, for example {"id":{"from":0,"to":100}}
- A field named singleValue can be used to follow the single value pattern discussed above.
- A field named in can be used to follow the array pattern discussed above.
- A field named fieldPath can be used to specify the path of a related field.
- A field named caseInsensitive can be used to enable case-insensitive querying of character-based fields.
- A field named invert can be used to invert a predicate (that is as a NOT).

Combining criteria in "and" and "or" blocks is supported by providing specially named properties with names beginning with @and and @or with JSON object values. These can be used directly within the body for criteria grouping purposes, and also nested within each other. When using multiple @and / @or groupings within a given object, take care to suffix them with additional characters (that is @and1 , @and2 , and so on) to ensure that they are uniquely named since any duplicates will be eliminated.

Some examples, which may be helpful when using this functionality, can be found at Query Examples.

OrderBy

A comma-delimited list of fields used to determine result ordering or a JSON array of complex sorting criteria.

When supplied as strings, names are provided in the same format as the where argument - optionally followed by `asc` (default) or `desc` to control order direction.
When supplied as a JSON array, a String fieldName field must be included in the object. Optional String order (asc or desc) and boolean caseInsensitive fields may also be provided.

Expands

A comma-delimited list of relationship paths, in dot-notated path form (that is, child.line would return the relationship named child, and its child relationship named line), on the resulting model which should be included in the response or all if all associated relationships should be included. By default, all *:1 relationships are always present in service responses. Any *:Many relationships are always excluded by default, and the expands mechanism is the means by which callers may request for these relationships to be returned in service responses.

Simple Field Comparison

In this example we look for records which have an id >= 1.

{
  "id": 1
}

Case Insensitive Comparison

In this example we look for records which have a reference id like AAA%, but ignore case.

{
    "deliveryId": {
        "singleValue": "aaa",
        "caseInsensitive": true
    }
}

Field Range Comparison

In this example, we look for records with a referenceId between AAA and ZZZZZZZZZZZZZZ.

{
    "deliveryId": {
        "from": "AAA",
        "to": "ZZZZZZZZZZZZZZ"
    }
}

Compound Field Comparison

In this example, we look for records with a crossReference with a key of TEST_TRANSACTION_ID and value of 12345.

{
    "crossReferences.key": {
        "in": ["TEST_TRANSACTION_ID"]
    },
    "crossReferences.value": {
        "in": ["12345"]
    }
}

Nested Compound Field Comparison

In this example, we look for fields with a reference Id >= AAA1111 and a crossReference with a key of TEST_TRANSACTION_ID and value of 12345.

{
    "deliveryId": "AAA1111",
    "@and1": {
        "crossReferences.key": {
            "in": ["TEST_TRANSACTION_ID"]
        },
        "crossReferences.value": {
            "in": ["12345"]
        }
    }
}

Field to Field Comparison

In this example we look for records where deliveryId is not equal to the currency, ignoring the case of the two.

{
    "deliveryId": {
        "fieldPath": "currency",
        "caseInsensitive": true,
        "invert": true
    }
}

Use Cases

Use cases demonstrate how to make use of REST APIs, including how to create and update records, and more. Use them to understand quickly how REST APIs can meet your business needs.

To get the most benefit from use cases, you should be familiar with basic REST concepts discussed in the Quick Start.

Quote

This section explains how to make use of Quote-related functions. Quotes are a mechanism by which eligibility for same-day delivery and estimated costs can be determined.

Build

To submit a request to obtain one or more quotes, the build resource method is provided. This method accepts a delivery request, and returns 0 or more quotes from eligible providers.

POST

https://<HOSTNAME>:<PORT>/<service>/api/delivery/v2/quote/build

Example Request

The following is an example of the request body in JSON format.

{
   "deliveryId": "0000001",
   "totalValue": 100.00,
   "pickupContact": {
   "companyName": "<COMPANYNAME>",
   "firstName": "<FIRSTNAME>",
   "lastName": "<LASTNAME>",
   "phoneNumber": "<PHONENUMBER>"
},
  "pickupAddress": {
   "address1": "<ADDRESS>",
   "city": "<CITY>",
   "state": "<STATE>",
   "postalCode": "<POSTALCODE>",
   "country": "<COUNTRY>"
},
   "dropoffContact": {
   "firstName": ""<FIRSTNAME>",
   "lastName": ""<LASTNAME>",
   "phoneNumber": "<PHONENUMBER>"
},
   "dropoffAddress": {
   "address1": "<ADDRESS>",
   "city": "<CITY>",
   "state": "<STATE>",
   "postalCode": "<POSTALCODE>",
   "country": "<COUNTRY>"
},
"manifest": [
  {
    "description": "Package 1",
    "identifier": "<ID>",
    "items": [
    {
      "description": "widget",
      "identifier": "<ID>",
      "quantity": 2
    }
   ],
    "length": 5,
    "height": 5,
    "width": 5,
    "weight": 10
  }
]
}

Example Response

The following is an example of a successful response body in JSON format.

{
    "quotes": [
        {
            "created": "2023-06-02T13:54:39.346Z",
            "createdBy": "<UID>",
            "id": 1,
            "crossReferences": [],
            "currency": "USD",
            "deliveryId": "0000001",
            "dropoffDeadline": "2023-06-02T15:24:14.000Z",
            "dropoffEta": "2023-06-02T14:53:48.000Z",
            "expires": "2023-06-02T14:09:39.241Z",
            "fee": 13.6,
            "provider": "<PROVIDER>",
            "providerCreated": "2023-06-02T13:54:39.241Z",
            "providerInstance": "<PROVIDERINSTANCE>",
            "providerlId": "<PROVIDERID>"
        }
    ]
}

Other Responses

In the event of the request not succeeding, a number of other responses may be returned.

Table 3-3 Other Responses — Request Not Successful

HTTP Code	Explanation	Body
204	No providers were eligible to service this request.	NA
400	The provided request input was not valid.	An array of MapperErrorData objects describing issues with the request.
404	A provided identifier or provider could not be found.	NA
424	One or more eligible providers were identified, but none were able to service the request.	An array of ProviderError objects explaining the issue(s).
500	The request failed for an unknown reason.	NA

Get

To retrieve a previously generated quote, the get method is provided. This method retrieves a single quote using its (id) identifier.

GET

https://<HOSTNAME>:<PORT>/<service>/api/delivery/v2/quote/{id}

Example Response

The following is an example of a successful response body in JSON format.


"created": "2023-06-02T13:54:39.346Z",
"createdBy": "<UID>",
"id": <ID>,
"crossReferences": [],
"currency": "USD",
"deliveryId": "0000001",
"dropoffDeadline": "2023-06-02T15:24:14.000Z",
"dropoffEta": "2023-06-02T14:53:48.000Z",
"expires": "2023-06-02T14:09:39.241Z",
"fee": 13.6,
"provider": "<PROVIDER>",
"providerCreated": "2023-06-02T13:54:39.241Z",
"providerInstance": "<PROVIDERINSTANCE>",
"providerlId": "<PROVIDERID>"
}

Other Responses

In the event of the request not succeeding, a number of other responses may be returned.

Table 3-4 Other Responses — Request Not Successful

HTTP Code	Explanation
404	The requested quote could not be found.
500	The request failed for an unknown reason.

List

To obtain a list of quotes, the list method is provided. This method returns an array of quotes matching the provided criteria. See Quick Start for more information on this endpoint’s available options.

GET

https://<HOSTNAME>:<PORT>/<service>/api/delivery/v2/quote?where={“deliveryId”:[“0000001”]}

Example Response

The following is an example of a successful response body in JSON format.

[
      {
          "created": "2023-06-02T13:54:39.346Z",
          "createdBy": "<UID>",
          "id": 1,
          "crossReferences": [],
          "currency": "USD",
          "deliveryId": "0000001",
          "dropoffDeadline": "2023-06-02T15:24:14.000Z",
          "dropoffEta": "2023-06-02T14:53:48.000Z",
          "expires": "2023-06-02T14:09:39.241Z",
          "fee": 13.6,
          "provider": "<PROVIDER>",
          "providerCreated": "2023-06-02T13:54:39.241Z",
          "providerInstance": "<PROVIDERINSTANCE>",
          "providerlId": "<PROVIDERID>"
      }
]

Other Responses

In the event of the request not succeeding, a number of other responses may be returned.

Table 3-5 Responses — Request Not Successful

HTTP Code	Explanation
500	The request failed for an unknown reason.

Delivery Services

This section explains how to make use of Delivery-related functions. Deliveries represent successfully arranged same-day delivery orders.

Build

To submit a request to obtain a delivery, the build resource method is provided. This method accepts a delivery request, and returns a single delivery from an eligible provider.

POST

https://<HOSTNAME>:<PORT>/<service>/api/delivery/v2/delivery/build

Example Request

The following is an example of the request body in JSON format.

{
	"deliveryId": "0000001",
	"totalValue": 100.00,
	"pickupContact": {
		"companyName": "<COMPANYNAME>",
		"firstName": "<FIRSTNAME>",
		"lastName": "<LASTNAME>",
		"phoneNumber": "<PHONENUMBER>"
	},
	"pickupAddress": {
		"address1": "<ADDRESS>",
		"city": "<CITY>",
		"state": "<STATE>",
		"postalCode": "<POSTALCODE>",
		"country": "<COUNTRY>"
	},
	"dropoffContact": {
		"firstName": "<FIRSTNAME>",
		"lastName": "<LASTNAME>",
		"phoneNumber": "<PHONENUMBER>"
	},
	"dropoffAddress": {
		"address1": "<ADDRESS>",
		"city": "<CITY>",
		"state": "<STATE>",
		"postalCode": "<POSTALCODE>",
		"country": "<COUNTRY>"
	},
	"manifest": [
		{
			"description": "Package 1",
			"identifier": "0000001 -01-01",
			"items": [
				{
					"description": "widget",
					"identifier": "<ID>",
					"quantity": 2
				}
			],
			"length": 5,
			"height": 5,
			"width": 5,
			"weight": 10
	}
]
}

Example Response

The following is an example of a successful response body in JSON format.

{
	"delivery": {
		"created": "2023-06-02T15:58:14.260Z",
		"createdBy": "UID",
		"id": 1,
		"barcodes": [
			{
				"created": "2023-06-02T15:58:14.298Z",
				"createdBy": "<UID>",
				"id": 1,
				"identifier": "<ID>",
				"parentId": <PARENTID>,
				"type": "QR",
				"value": "0000001 -01-01"
			}
		],
		"crossReferences": [],
		"currency": "USD",
		"deliveryId": "<DELIVERYID>",
		"dropoffDeadline": "2023-06-02T17:33:50.000Z",
		"dropoffEta": "2023-06-02T17:00:07.000Z",
		"fee": 13.6,
		"manifestSize": 1,
		"pickupEta": "2023-06-02T16:18:14.000Z",
		"provider": "<PROVIDER>",
		"providerCreated": "2023-06-02T15:58:13.965Z",
		"providerInstance": "<PROVIDERINSTANCE>",
		"providerlId": "<PROVIDERVID>",
		"status": "PENDING",
		"statusHistory": [],
		"trackingURL": "https://<PROVIDER>.com/path/to/tracking/url”
	}
}

Other Responses

In the event of the request not succeeding, a number of other responses may be returned.

Table 3-6 Other Responses — Request Not Successful

HTTP Code	Explanation	Body
204	No providers were eligible to service this request.	NA
400	The provided request input was not valid.	An array of MapperErrorData objects describing issues with the request.
404	A provided identifier or provider could not be found.	NA
409	The provided deliveryId already exists.	NA
424	One or more eligible providers were identified, but none were able to service the request.	An array of ProviderError objects explaining the issue(s).
500	The request failed for an unknown reason.	NA

Status

To retrieve a previously arranged delivery, reflecting its current to-the-minute status, the status endpoint is provided. This method retrieves a single delivery using either its {id} or {deliveryId}.

GET

https://<HOSTNAME>:<PORT>/<service>/api/delivery/v2/delivery/status?id={id}

https://<HOSTNAME>:<PORT>/<service>/api/delivery/v2/delivery/status?deliveryId={deliveryId}

Example Response

The following is an example of a successful response body in JSON format.

{
	"created": "2023-06-02T15:58:14.260Z",
	"createdBy": "<UID>",
	"id": 1,
	"barcodes": [
		{
			"created": "2023-06-02T15:58:14.298Z",
			"createdBy": "<UID>",
			"id": 1,
			"identifier": "<ID>",
			"parentId": <PARENTID>,
			"type": "QR",
			"value": "0000001 -01-01"
		}
	],
	"crossReferences": [],
	"currency": "USD",
	"deliveryId": "<DELIVERYID>",
	"dropoffDeadline": "2023-06-02T17:33:50.000Z",
	"dropoffEta": "2023-06-02T17:00:07.000Z",
	"fee": 13.6,
	"manifestSize": 1,
	"pickupEta": "2023-06-02T16:18:14.000Z",
	"provider": "<PROVIDER>",
	"providerCreated": "2023-06-02T15:58:13.965Z",
	"providerInstance": "<PROVIDERINSTANCE>",
	"providerlId": "<PROVIDERID>",
	"status": "PENDING",
	"statusHistory": [],
	"trackingURL": "https://<PROVIDER>.com/path/to/tracking/url"
}

Other Responses

In the event of the request not succeeding, a number of other responses may be returned.

Table 3-7 Other Responses — Request Not Successful

HTTP Code	Explanation	Body
400	The provided request input was not valid.	An array of MapperErrorData objects describing issues with the request.
404	A provided identifier or provider could not be found.	NA
424	One or more eligible providers were identified, but none were able to service the request.	An array of ProviderError objects explaining the issue(s).
500	The request failed for an unknown reason.	NA

Cancel

To cancel a delivery which has not yet reached a terminal state, the cancel endpoint is provided. This method cancels a single delivery using either its {id} or {deliveryId}.

POST

https://<HOSTNAME>:<PORT>/<service>/api/delivery/v2/delivery/cancel?id={id}

https://<HOSTNAME>:<PORT>/<service>/api/delivery/v2/delivery/cancel?deliveryId={deliveryId}

Example Response

The following is an example of a successful response body in JSON format.


	"created": "2023-06-02T15:58:14.260Z",
	"createdBy": "<UID>",
	"id": 1,
	"barcodes": [
		{
			"created": "2023-06-02T15:58:14.298Z",
			"createdBy": "<UID>",
			"id": 1,
			"identifier": "<ID>",
			"parentId": <PARENTID>,
			"type": "QR",
			"value": "0000001 -01-01"
		}
	],
	"crossReferences": [],
	"currency": "USD",
	"deliveryId": "<DELIVERYID>",
	"dropoffDeadline": "2023-06-02T17:33:50.000Z",
	"dropoffEta": "2023-06-02T17:00:07.000Z",
	"fee": 13.6,
	"manifestSize": 1,
	"pickupEta": "2023-06-02T16:18:14.000Z",
	"provider": "<PROVIDER>",
	"providerCreated": "2023-06-02T15:58:13.965Z",
	"providerInstance": "<PROVIDERINSTANCE>",
	"providerlId": "<PROVIDERID>",
	"status": "CANCELED",
	"statusHistory": [],
	"trackingURL": "https://<PROVIDER>.com/path/to/tracking/url"
}

Other Responses

In the event of the request not succeeding, a number of other responses may be returned.

Table 3-8 Other Responses — Request Not Successful

HTTP Code	Explanation	Body
400	The provider input is invalid	NA
404	A provided identifier or provider could not be found.	NA
409	Delivery is not in a status eligible for cancellation.	NA
424	One or more eligible providers were identified, but none were able to service the request.	An array of ProviderError objects explaining the issue(s).
500	The request failed for an unknown reason.	NA

Get

To retrieve a previously generated delivery, the get method is provided. This method retrieves a single delivery using its (id) identifier.

GET

https://<HOSTNAME>:<PORT>/<service>/api/delivery/v2/delivery/{id}

Example Response

The following is an example of a successful response body in JSON format.

{
	"created": "2023-06-02T15:58:14.260Z",
	"createdBy": "<UID>",
	"id": 1,
	"barcodes": [
		{
			"created": "2023-06-02T15:58:14.298Z",
			"createdBy": "<UID>",
			"id": 1,
			"identifier": "<ID>",
			"parentId": <PARENTID>,
			"type": "QR",
			"value": "0000001 -01-01"
		}
	],
	"crossReferences": [],
	"currency": "USD",
	"deliveryId": "<DELIVERYID>",
	"dropoffDeadline": "2023-06-02T17:33:50.000Z",
	"dropoffEta": "2023-06-02T17:00:07.000Z",
	"fee": 13.6,
	"manifestSize": 1,
	"pickupEta": "2023-06-02T16:18:14.000Z",
	"provider": "<PROVIDER>",
	"providerCreated": "2023-06-02T15:58:13.965Z",
	"providerInstance": "<PROVIDERINSTANCE>",
	"providerlId": "<PROVIDERID>",
	"status": "PENDING",
	"statusHistory": [],
	"trackingURL": "https://<PROVIDER>.com/path/to/tracking/url"
	}

Other Responses

In the event of the request not succeeding, a number of other responses may be returned.

Table 3-9 Other Responses — Request Not Successful

HTTP Code	Explanation
404	The requested delivery could not be found.
500	The request failed for an unknown reason.

List

To obtain a list of deliveries, the list method is provided. This method returns an array of deliveries matching the provided criteria. See Send Requests for more information on this endpoint’s available options.

GET

https://<HOSTNAME>:<PORT>/<service>/api/delivery/v2/delivery?where={“deliveryId”:[“0000001”]}

Example Response

The following is an example of a successful response body in JSON format.

[
{
	"created": "2023-06-02T15:58:14.260Z",
	"createdBy": "<UID>",
	"id": 1,
	"barcodes": [
		{
			"created": "2023-06-02T15:58:14.298Z",
			"createdBy": "<UID>",
			"id": 1,
			"identifier": "<ID>",
			"parentId": <PARENTID>,
			"type": "QR",
			"value": "0000001 -01-01"
		}
	],
	"crossReferences": [],
	"currency": "USD",
	"deliveryId": "<DELIVERYID>",
	"dropoffDeadline": "2023-06-02T17:33:50.000Z",
	"dropoffEta": "2023-06-02T17:00:07.000Z",
	"fee": 13.6,
	"manifestSize": 1,
	"pickupEta": "2023-06-02T16:18:14.000Z",
	"provider": "<PROVIDER>",
	"providerCreated": "2023-06-02T15:58:13.965Z",
	"providerInstance": "<PROVIDERINSTANCE>",
	"providerlId": "<PROVIDERID>",
	"status": "PENDING",
	"statusHistory": [],
	"trackingURL": "https://<PROVIDER>.com/path/to/tracking/url"
	}
]

Other Responses

In the event of the request not succeeding, a number of other responses may be returned.

Table 3-10 Other Responses — Request Not Successful

HTTP Code	Explanation
500	The request failed for an unknown reason.