NFO UPS API Service
home
NFO UPS API Service Documentation
Overview and Purpose of the API
The NFO UPS API Service is designed to facilitate seamless integration between UPS and MxTMS to create next flight out shipments. It provides endpoints to create orders and retrieve rates for orders.
The API is secured using OAuth 2.0, ensuring secure and authorized access to its endpoints. It is built to handle requests and responses in JSON format, making it easy to integrate with modern applications.
Authentication Requirements and Security Details
The NFO UPS API Service uses OAuth 2.0 for authentication and authorization. Below are the details of the security implementation:
- Authorization Header: All requests to the API must include an
Authorizationheader with a valid Bearer token. - Token Endpoints:
- Authorization URI:
https://login.microsoftonline.com/d0bc7ed9-9964-48b5-a845-c5f4a2073269/oauth2/v2.0/token
- Authorization URI:
- Grant Type:
client_credentials - Client ID:
client_id - Client Secret:
client_secret - Error Responses:
401 Unauthorized: Indicates a bad or expired token.403 Forbidden: Indicates a bad OAuth request.
Base URL and Environments
The API is hosted on the following base URL:
https://<base-url>/apiReplace <base-url> with the appropriate environment-specific domain.
In the staging environment, the URL is
https://staging-nfo-ups-api.us-e2.cloudhub.io/Detailed Endpoint Documentation
1. Create an Order in MxTMS From UPS Request
Endpoint: POST /api/order
Description: This endpoint is used to create an order in MxTMS using the FF (Next Flight Out) Service
Request
- Headers:
Authorization: Bearer token (required)
- Body:
- Content-Type:
application/json - Example:
- Content-Type:
{
"shipmentRequest": {
"clientInfo": {
"dataSource": "AY"
},
"shipmentDetails": {
"serviceType": "FF",
"dimUOM": "IN",
"dimWeight": 5.5,
"grossWeight": 5.5,
"weightUOM": "LBS",
"averagePkgWeightType": "0",
"numOfPiecesInShipment": 2,
"paymentDetails": {
"shipmentCharge": [
{
"shipmentChargeType": "02",
"billType": "01",
"accountNumber": "3927",
"billInformation": {
"creditCard": {
"paymentCardType": "",
"paymentCardNumber": "",
"expirationDate": "",
"securityCode": ""
},
"alternativePaymentMethod": "",
"certifiedElectronicMail": "",
"interchangeSystemCode": "",
"preAuthorizedPaymentInformation": {
"paymentMediaType": "",
"paymentGuid": ""
}
},
"address": {
"streetAddress": {
"addressLine1": "340 MacArthur Blvd",
"addressLine2": "abc",
"addressLine3": "xyz"
},
"city": "Mahwah",
"stateOrProvinceCode": "NJ",
"postalCode": "07430",
"countryCode": "US"
}
}
]
},
"shipper": {
"accountNumber": "3927",
"contactInformation": {
"name": "ABB Inc.",
"nickName": "Return Manger",
"phone": {
"number": 1231231231,
"extension": 1234
}
},
"address": {
"streetAddress": {
"addressLine1": "340 MacArthur Blvd",
"addressLine2": "abc",
"addressLine3": "xyz"
},
"city": "Mahwah",
"stateOrProvinceCode": "NJ",
"postalCode": "07430",
"countryCode": "US"
}
},
"shipFrom": {
"contactInformation": {
"name": "ABB Inc.",
"nickName": "Return Manger",
"phone": {
"number": 1231231231,
"extension": 1234
}
},
"address": {
"streetAddress": {
"addressLine1": "340 MacArthur Blvd",
"addressLine2": "abc",
"addressLine3": "xyz"
},
"city": "Mahwah",
"stateOrProvinceCode": "NJ",
"postalCode": "07430",
"countryCode": "US"
}
},
"shipTo": {
"contactInformation": {
"name": "ABB Inc.",
"nickName": "Return Manger",
"phone": {
"number": 1231231231,
"extension": 1234
}
},
"address": {
"streetAddress": {
"addressLine1": "8101 World Center Dr",
"addressLine2": "",
"addressLine3": ""
},
"city": "Orlando",
"stateOrProvinceCode": "FL",
"postalCode": "32821",
"countryCode": "US"
}
},
"package": [
{
"description": "mechanical pencils",
"packagingType": "02",
"dimensions": {
"unitOfMeasurement": "IN",
"length": 7,
"width": 8,
"height": 9
},
"packageWeight": {
"unitOfMeasurement": "LBS",
"weight": 4
},
"dimWeight": {
"unitOfMeasurement": "LBS",
"weight": 4
},
"referenceNumber": [
{
"barCodeIndicator": true,
"code": "",
"value": ""
}
]
}
],
"shipmentServiceOptions": {
"deliveryOption": {
"saturdayDeliveryIndicator": true,
"sundayDeliveryIndicator": true,
"weekendDeliveryType": "NSA"
},
"pickupOption": {
"holdForPickupIndicator": true
},
"deliveryConfirmation": {
"dcisType": "1"
}
},
"pickupDate": {
"pickupDate": "20241111",
"readyTime": "2015"
}
},
"referenceNumber": [
{
"barCodeIndicator": true,
"code": "",
"value": ""
}
]
}
}Response
- 200 OK:
- Content-Type:
application/json - Example:
- Content-Type:
{
"shipmentResponse": {
"shipmentResults": {
"shipmentCharges": {
"rateChart": 1,
"itemizedCharges": [
{
"chargeType": "554",
"currencyCode": "USD",
"monetaryValue": 0,
"subType": "NSU"
},
{
"chargeType": "300",
"currencyCode": "USD",
"monetaryValue": 0,
"subType": "NSA"
},
{
"chargeType": "121",
"currencyCode": "USD",
"monetaryValue": 0,
"subType": "1"
},
{
"chargeType": "220",
"currencyCode": "USD",
"monetaryValue": 0,
"subType": "HFP"
}
]
},
"billingWeight": {
"unitOfMeasurement": "LBS",
"weight": 14
},
"shipmentIdentificationNumber": "1Z2T88FR0300011213",
"packageResult": [
{
"trackingNumber": "1Z2T88FR0300011213",
"baseServiceCharge": {
"currencyCode": "USD",
"monetaryValue": 14.02
},
"serviceOptionsCharges": {
"currencyCode": "USD",
"monetaryValue": 0
},
"shippingLabel": {
"imageFormatType": "GIF",
"graphicImage": "base64EncodedImage"
}
}
],
"estimatedArrival": {
"arrival": {
"date": "20241119",
"time": "104215"
}
}
},
"warningDetails": [
{
"code": 10,
"message": "test"
}
]
}
}- 400 Bad Request:
- Content-Type:
application/json - Example:
- Content-Type:
{
"response": {
"errors": [
{
"code": "250002",
"message": "Error creating order"
}
]
}
}2. Get a Rate for an Order
Endpoint: POST /api/rate
Description: This endpoint is used to retrieve a rate for an order from the MxTMS system.
Request
- Headers:
Authorization: Bearer token (required)
- Body:
- Content-Type:
application/json - Example:
- Content-Type:
{
"rateRequest": {
"shipmentDetails": {
"serviceType": "FF",
"dimUOM": "IN",
"dimWeight": 5.5,
"grossWeight": 5.5,
"weightUOM": "LBS",
"averagePkgWeightType": "0",
"numOfPiecesInShipment": 2,
"shipper": {
"accountNumber": "2271",
"contactInformation": {
"name": "ABB Inc.",
"nickName": "Return Manger",
"phone": {
"number": 1231231231,
"extension": 1234
}
},
"address": {
"streetAddress": {
"addressLine1": null,
"addressLine2": "abc",
"addressLine3": "xyz"
},
"city": null,
"stateOrProvinceCode": "NJ",
"postalCode": "07430",
"countryCode": null
}
},
"shipFrom": {
"contactInformation": {
"name": "ABB Inc.",
"nickName": "Return Manger",
"phone": {
"number": 1231231231,
"extension": 1234
}
},
"address": {
"streetAddress": {
"addressLine1": "340 MacArthur Blvd",
"addressLine2": "abc",
"addressLine3": "xyz"
},
"city": "Mahwah",
"stateOrProvinceCode": "NJ",
"postalCode": "07430",
"countryCode": "US"
}
},
"shipTo": {
"contactInformation": {
"name": "ABB Inc.",
"nickName": "Return Manger",
"phone": {
"number": 1231231231,
"extension": 1234
}
},
"address": {
"streetAddress": {
"addressLine1": "8101 World Center Dr",
"addressLine2": "",
"addressLine3": ""
},
"city": "Orlando",
"stateOrProvinceCode": "FL",
"postalCode": "32821",
"countryCode": "US"
}
},
"package": [
{
"commodity": {
"freightClass": "",
"nmfcCommodity": {
"primeCode": "",
"subCode": ""
}
},
"description": "mechanical pencils",
"packagingType": "02",
"dimensions": {
"unitOfMeasurement": "IN",
"length": 7,
"width": 8,
"height": 9
},
"packageWeight": {
"unitOfMeasurement": "LBS",
"weight": 4
},
"packageServiceOptions": {
"deliveryConfirmation": {
"dcisType": "3"
}
}
}
],
"shipmentServiceOptions": {
"pickupOption": {
"holdForPickupIndicator": true
},
"deliveryConfirmation": {
"dcisType": "1"
}
}
}
}
}Response
- 200 OK:
- Content-Type:
application/json - Example:
- Content-Type:
{
"rateResponse": {
"ratedShipment": [
{
"serviceType": "0C9",
"itemizedCharges": [
{
"chargeType": "554",
"currencyCode": "USD",
"monetaryValue": 0,
"subType": "NSU"
},
{
"chargeType": "300",
"currencyCode": "USD",
"monetaryValue": 0,
"subType": "SAT"
},
{
"chargeType": "121",
"currencyCode": "USD",
"monetaryValue": 0,
"subType": "ASS"
},
{
"chargeType": "220",
"currencyCode": "USD",
"monetaryValue": 0,
"subType": "HFP"
}
],
"baseServiceCharges": {
"currencyCode": "USD",
"monetaryValue": 0
},
"billingWeight": {
"unitOfMeasurement": "LB",
"weight": 7
},
"ratedPackage": [
{
"baseServiceCharge": {
"currencyCode": "USD",
"monetaryValue": 14.46
},
"billingWeight": {
"unitOfMeasurement": "LB",
"weight": 7
},
"itemizedCharges": [
{
"chargeType": "434",
"currencyCode": "USD",
"monetaryValue": 0,
"subType": "NONE"
},
{
"chargeType": "430",
"currencyCode": "USD",
"monetaryValue": 0,
"subType": "NONE"
},
{
"chargeType": "120",
"currencyCode": "USD",
"monetaryValue": 0,
"subType": "DCS"
}
],
"serviceOptionsCharges": {
"currencyCode": "USD",
"monetaryValue": 0
},
"totalCharges": {
"currencyCode": "USD",
"monetaryValue": 15.54
},
"transportationCharges": {
"currencyCode": "USD",
"monetaryValue": 18.54
},
"weight": 7
}
]
}
],
"warningDetails": [
{
"code": 10,
"message": "test"
}
]
}
}- 400 Bad Request:
- Content-Type:
application/json - Example:
- Content-Type:
{
"response": {
"errors": [
{
"code": "250002",
"message": "Error creating order"
}
]
}
}Error Handling and Status Codes
The API uses standard HTTP status codes to indicate the success or failure of a request. Below is a summary of the status codes and their meanings:
| Status Code | Description |
|---|---|
| 200 | Request was successful. |
| 400 | Bad request. The request could not be understood or was missing parameters. |
| 401 | Unauthorized. The token is invalid or expired. |
| 403 | Forbidden. The OAuth request is invalid. |
Best Practices for Implementation
To ensure smooth integration with the NFO UPS API Service, follow these best practices:
Authentication:
- Always include a valid Bearer token in the
Authorizationheader. - Use the
client_credentialsgrant type to obtain the token.
- Always include a valid Bearer token in the
Error Handling:
- Implement proper error handling for
401and403responses to handle token expiration or invalid requests. - Validate the request body before sending it to the API to avoid
400 Bad Requesterrors.
- Implement proper error handling for
Request and Response Formats:
- Ensure that all requests and responses are in JSON format.
- Use the provided examples as a reference for constructing requests and parsing responses.
Rate Limiting:
- Be mindful of any rate limits imposed by the API. Avoid sending excessive requests in a short period.
This concludes the documentation for the NFO UPS API Service. For further assistance, please refer to the API support team.