API-RAMP-Manifesting

An API that exposes multiple end-points to perform postage calculation and recalculation processes. The API will internally call the rules engine for the given mailitem and save the record in “manifesting results” if successful or “manifesting exception” upon failure.

Non Functional Requirements

1. SLA should be less than 50 ms for dim weight calculation, rate indicator and extra service code and extra service fee calculation
2. SLA should be less than 100 ms for recalculations requests
3. Performance test required to map out the matrixpo

Technical Design

1. Use of opportunistic caching (invalidate after 30 mins)
2. All time limits and numbers should be configurable
3. Circuit breaker retries 3 times
4. Time to wait between retries 30 seconds
5. Timeout on caller should be set to 5 mins
6. On continuous mailitem recalculation failures (default 80)
   1. Open the circuit breaker
   2. Retry after 5 mins

 

EVS File Generation end-points
Exposes the business logic that is required for calculating elements that will populate in the USPS eVS manifest file. Successfully calculated data will be saved in manifestingresults table.

Calculate Rate Indicator
Based on mail class and volume, it will return the rate indicator needed for USPS eVS file

End point:
curl -X GET "https://api-ramp-manifesting-noc.ecs-am-ramp-dit.apps.usqasocp001.dhl.com:443/api/v1/dim/rateIndicator?cuboidal=true&dspProductId=83&entryRateCode=2&height=10&length=25&mailClass=PS&uom=IN&width=10&zipCodeSetTypeId=4" -H "accept: */*"

Input Elements:

Node	Req	Description	Data Type	Length	Example Values
cuboidal	yes	Cuboidal or Not	Boolean		true, false
dspproduct_id	yes	USPS Product	Integer	(1,3)	36,83
entryratecode	yes	Type of USPS facility where mail is tendered	Integer	1	1,2
length	yes	Length of parcel (longest dimension)	Number	30 CHAR	22
width	yes	Width of parcel	Number	30 CHAR	10
height	yes	Height of parcel	Number	30 CHAR	10
mailclass	yes	USPS class of mail	String	2 CHAR	PS,PM
uom	yes	The unit of measurement	String	2 CHAR	CM,IN
zipcodesetype_id	yes	Zipcode set type	Integer	2 CHAR	4,11

 

Example Request URL: https://api-ramp-manifesting-noc.ecs-am-ramp-dit.apps.usqasocp001.dhl.com:443/api/v1/dim/rateIndicator?cuboidal=true&dspProductId=83&entryRateCode=2&height=10&length=25&mailClass=PS&uom=IN&width=10&zipCodeSetTypeId=4

Example Response:

 

 

 

Json =  {

  "dimension": {

    "length": 25,

    "height": 10,

    "width": 10,

    "uom": "IN"

  },

  "rateIndicator": "3R",

  "entryRateCode": 2,

  "cuboidal": true,

  "dspProductId": 83,

  "mailClass": "PS",

  "zipCodeSetTypeId": 4

}

Logic:

• volume = Length x Height x Width
• if (is non cuboidal or not PM or not PS) then
• volume = volume above x cuboidal factor (0.785) 
• if volume > 1 cubic feet and exist in uspsrateindicator table
• rate indicator lookup in uspsareteindicator based on cuboidal, entryreatecode, mailclass
  • else
• rate indicator lookup in  zipcodesetype_dspproduct table based on the dspproduct and zipcodeset type
• Cuboidal factor will be hardcoded
• manifesting.cuboidalproductexception = list of values (PM, PS)

 

Calculate extra service fees and code
Based on DSP product, dimensions, entry rate, and cuboidal flag, it will return the extra service fees and codes needed for USPS eVS file

End point: 
curl -X GET "https://api-ramp-manifesting-noc.ecs-am-ramp-dit.apps.usqasocp001.dhl.com:443/api/v1/dim/extraServiceCodeFees?confirmationType=DELCON&cuboidal=true&dspProductId=36&entryRateCode=1&height=10&length=27&mailContentCategory=5&uom=IN&width=10" -H "accept: */*"

Input Elements:

Node	Req	Description	Data Type	Length	Values
confirmationtype	no	USPS delivery confirmation	String	30 CHAR	DELCON,SIGCON
cuboidal	yes	Cuboidal or Not	Boolean		true,false
dspproduct_id	yes	USPS Product	Number	(1,3)	36,83
entryratecode	no	Type of USPS facility where mail is tendered	Number	1	1,4
height	yes	Height of parcel	Integer	30 CHAR	10
width	yes	Width of parcel	Integer	30 CHAR	10
length	yes	Length of parcel (longest dimension)	Integer	30 CHAR	22
mailContentCategory	yes	Dangerous Goods code	Number	50 CHAR	5
unitOfMeasure	yes	The unit of measurement	String	2 CHAR	IN,CM

 

Example Request URL: https://api-ramp-manifesting-noc.ecs-am-ramp-dit.apps.usqasocp001.dhl.com:443/api/v1/dim/extraServiceCodeFees?confirmationType=sigcon&cuboidal=true&dspProductId=36&entryRateCode=1&height=10&length=27&mailContentCategory=5&uom=IN&width=10

Example Response:

Json =  {

  "entryRateCode": 1,

  "dimension": {

    "length": 27,

    "height": 10,

    "width": 10,

    "uom": "IN"

  },

  "extraServices": {

    "extraservicefee5": "0.0",

    "extraservicefee1": "2.00",

    "extraservicecode5": "857",

    "extraservicecode1": "881"

  },

  "cuboidal": true,

  "dspProductId": 36,

  "confirmationType": "sigcon"

}

Logic:

Lookup mailcontentcategory.uspsevscode map to extraservicecode5 = uspsevscode
Lookup evsextraservicefee(volume>x, entryratecode) = name (map to servicecode) and fee (map to extraservicefee)
Lookup evsextraservicefee (length>x, entryratecode) = name (map to servicecode) and fee (map to extraservicefee)

DELCON/SIGCON 

When CONFIRMATIONTYPE == USPS_DELIVERY_CONFIRMATION

Lookup DSPSERVICETYPEMAPPING with DSPPRODUCT ID and DSPSERVICE_ID as 1 = name (map to EXTRASRVCCODE) and fee (map to EXTRASRVCFEE)

When CONFIRMATIONTYPE == USPS_SIGNATURE_CONFIRMATION

Lookup DSPSERVICETYPEMAPPING with DSPPRODUCT ID and DSPSERVICE_ID as 2 = name (map to EXTRASRVCCODE) and fee (map to EXTRASRVCFEE).

EXAMPLE

Lookup delcon = code = 785. fee=0.25

Lookup sigcon =

Lookup extersevice for volume = code = 883 and fee=1.50

Lookup extraservice for length 

Lookup dangerous good = code 227

 

 extraService= {
                   "extraservicecode5":"227",
                   "extraservicecode1":"785",
                   "extraservicefee1":"0.25".

                    "extraservicecode2":"883 ",
                   "extraservicefee2":"1.50"
                }

 

Calculate dim weight
Based on parcel dimensions, cuboidal flag, and ordered product, it will return the dim weight needed for USPS eVS file

End point: 
curl -X GET "https://api-ramp-manifesting-noc.ecs-am-ramp-dit.apps.usqasocp001.dhl.com:443/api/v1/dim/dimweight?cuboidal=true&dimUom=IN&height=10&length=12&orderedProduct=36&width=10" -H "accept: */*"

Input Elements:

Node	Req	Description	Data Type	Length	Example Values
cuboidal	yes	Cuboidal or Not	Boolean		true,false
dimUom	yes	The unit of measurement	String	2 Char	CM,IN
length	yes	Length of parcel (longest dimension)	VARCHAR2	30 Char	10
width	yes	Width of parcel	VARCHAR2	30 Char	10
height	yes	Height of parcel	VARCHAR2	30 Char	10
orderedProduct	yes	DHL Ordered Product	Number	4 Char	36,631

 

Example Request URL: https://api-ramp-manifesting-noc.ecs-am-ramp-dit.apps.usqasocp001.dhl.com:443/api/v1/dim/dimweight?cuboidal=true&dimUom=IN&height=10&length=12&orderedProduct=36&width=10

 

Example Response:

Json =  {

  "dimension": {

    "cuboidal": true,

    "dimensionHeight": 10,

    "dimensionLength": 12,

    "dimensionSource": "string",

    "dimensionWidth": 10,

    "unitOfMeasure": "IN"

  },

  "weight": {

    "unitOfMeasure": "G",

    "value": 19664.47

  }

}

Logic:

• Property manifesting.dimOrderedProducts= contain the list of all orderedProducts to calculate dims
• manifesting.dim_cuboidal_factor= contain the list of all orderedProducts to calculate dims
• manifesting.dim_non_cuboidal_factor= contain the list of all orderedProducts to calculate dims 
• dimWeight = (Length x Width x Height) / Factor

 

 

Postage Recalculation end-points
Provides the ability to schedule manifest recalculation by facility, along with view and update the schedule. It will normally be used for a future date to automatically trigger a massive manifesting recalculation for all mailitems still pending to be completed for manifesting, ie. sortcode or rate updates

Create a new recalculation job
Will create a new job to be scheduled for manifest recalculations and create a record in manifestRecalculationJobs

End point: 
curl -X POST "https://api-ramp-manifesting-ecs-am-ramp-dit.ocp-apps-am-ramp-test.dhlecs.com:443/api/v1/manifestRecalculationJobs" -H "accept: */*" -H "Content-Type: application/json" -d "[{\"description\":\"testing\",\"facilityCode\":\"USMCO1\",\"filterParam\":\"string\",\"scheduledDateTime\":\"2022-12-30 22:45 America/Los_Angeles\",\"version\":\"2022-12-13-1\"}]"

Input Elements:

Node	Req	Description	Data Type	Length	Example Values
facilityCode	yes	Facility with manifested shipments	VARCHAR2	6 Char	USMCO1
scheduledDateTime	yes	Date/Time the recalculation will run	String	YYYY-MM-DD HH:MM TimeZoneID	2022-12-30 22:45 America/Los_Angeles
filterParam	no	To further limit the call	Condition		where zipcode is 30041
version	yes	Unique value to assign to recalculation	String	5Char	Sort1
description	no	User can enter free text	String	200 Char	Free text

 

Expected Response:

Json =  {

[

  {

    "facilityCode": "USMCO1",

    "scheduledDateTime": "2025-01-01 22:45 America/Los_Angeles",

    "version": "sort2",

    "description": "testing the API with Archana and having a great time",

    "filterParam": "string"

  }

]

Logic:

• All dates must be in the future
• Time must be in 15 minutes interval i.e. 11/17/2022 3:07 PM is invalid
• Version and FacilityCode must be unique

Update a recalculation job
Will update manifest recalculation jobs that are still pending to be processed. Looks up a record based on the version and facility code to update.

End point: curl -X PUT "https://api-ramp-manifesting-ecs-am-ramp-dit.ocp-apps-am-ramp-test.dhlecs.com:443/api/v1/manifestRecalculationJobs" -H "accept: */*" -H "Content-Type: application/json" -d "[{\"description\":\"testing the Put\",\"facilityCode\":\"USMCO1\",\"filterParam\":\"string\",\"scheduledDateTime\":\"2022-12-30 22:45 America/Los_Angeles\",\"version\":\"Sort1\"}]"

Input Elements:

Node	Req	Description	Data Type	Length	Example Values
facilityCode	yes	Facility with manifested shipments	VARCHAR2	6 Char	USMCO1
scheduledDateTime	yes	Date/Time the recalculation will run	String	YYYY-MM-DD HH:MM TimeZoneID	2022-12-30 22:45 America/Los_Angeles
filterParam	no	To further limit the call	Condition		where zipcode is 30041
version	yes	Unique value to assign to recalculation	String	5Char	Sort1
description	no	User can enter free text	String	200 Char	Free text

Expected Response:

JSON[

  {

    "facilityCode": "USEWR1",

    "scheduledDateTime": "2022-12-15 22:45 America/Los_Angeles",

    "version": "123",

    "description": "test",

    "filterParam": "string"

  }

]

Logic:

• Cannot update records that existed in the past

Delete a recalculation job
Will delete the given job based on the facility and version number

End point: 
curl -X DELETE "https://api-ramp-manifesting-ecs-am-ramp-dit.ocp-apps-am-ramp-test.dhlecs.com:443/api/v1/manifestRecalculationJobs?facilityCode=USEWR1&version=SORT1" -H "accept: */*"

Input Elements:

Node	Req	Description	Data Type	Length	Example Values
facilityCode	yes	Facility with manifested shipments	VARCHAR2	6 Char	USEWR1
version	yes	Unique value to assign to recalculation	String	5 Char	SORT1

Expected Response:

 

JSON {

  "facilityCode": "USMCO1",

  "scheduledDateTime": "2022-12-30 22:45 America/Los_Angeles",

  "version": "123",

  "description": "test",

  "filterParam": "string"

}

 

Retrieve list of scheduled jobs
Will return the list of manifestRecalculationJobs

End point: 
curl -X GET "https://api-ramp-manifesting-ecs-am-ramp-dit.ocp-apps-am-ramp-test.dhlecs.com:443/api/v1/manifestRecalculationJobs?page=2&pageSize=100" -H "accept: */*"

Input Elements:

Node	Req	Description	Data Type	Length	Example Values
facilityCode	yes	Facility with manifested shipments	VARCHAR2	6 Char	USMCO1
pendingOnly	no	Only view pending items or All	Boolean		true, false
page	no	Which page do you want to see	String	5Char	1,2
pageSize	no	How many records per page	String		100

Expected Response:

JSON {

  "description": "string",

  "facilityCode": "string",

  "filterParam": "string",

  "scheduledDateTime": "2022-12-30 22:45 America/Los_Angeles",

  "version": "string"

}Logic:

• Add pagination to the request and the response
• Add filter by upcoming request to get only pending jobs
• Add filter by facility 

 

Delete Manifesting Results for given mailitem
Will delete manifestingResults for a given mailitem and return a 202 if deletion is successful

End point: 
curl -X DELETE "https://api-ramp-manifesting-ecs-am-ramp-dit.ocp-apps-am-ramp-test.dhlecs.com:443/api/v1/manifesting/manifestingResult/9374810914200018787441" -H "accept: */*"

Input Elements:

Node	Req	Description	Data Type	Length	Example Values
rampmailidentifer	yes	Facility with manifested shipments	VARCHAR2	34 Char	9374810914200018787441

 

Expected Response:

TBD

 

 

User Guide

Get Access

You must request credentials for any applications you develop

To register your app and get your API subscription keys:

1. Click My Apps on the portal website.
2. Click the + Add App button.
   The “Add App” form appears.
3. Complete the Add App form. 
   You can select the APIs you want to access.
4. When you have completed the form, click the Add App button.

 

Authentication

Every call to the API requires a subscription key. This key needs to be either passed through a query string parameter or specified in the request header (DHL-API-Key).

To view your API subscription keys:

1. From the My Apps screen, click on the name of your app.
   The Details screen appears. 
2. If you have access to more than one API, click the name of the relevant API. 
   Note: The APIs are listed under the “Credentials” section. 
3. Click the Show link below the asterisks that is hiding the Consumer Key. 
   The Consumer Key appears.    

 

Environments

The addressable API base URL/URI environments are:  

Environment	Description
https://api-ramp-manifesting-noc.ecs-am-ramp-dit.apps.usqasocp001.dhl.com	Internal environment

 

Rate limits

Rate limits protect the DHL infrastructure from suspicious requests that exceed defined thresholds.

The table below details the main request limits:

Service Level	Maximum calls per second	Maximum calls per day
Starter	1	250
Standard	2	1000

Please contact api@dpdhl.com if you need a different service level. 

When the limit is reached, you will receive an HTTP Status code: 

429: Too many requests.