The Paperless Document API allows applications to upload electronic documents to UPS documents repository for faster and more efficient customs processing.

The Paperless Document API web service allows your application to upload your own customized trade documents for customs clearance to the UPS documents repository called "Forms History".

Linking the document image to the shipment identification number generated by your manifesting system via the Paperless Document API upload process allows UPS operations and customs to process your international shipments more quickly and efficiently.

The Paperless Document API web service consists of three operations:

• Upload documents to Forms History
• Delete uploaded documents and
• Push uploaded documents to Image Repository.

In order to utilize all these facilities, a user must have a valid 6 digit UPS shipper number.

• You will need to have Maven and the Java Development Kit installed.

• You can either download a local copy or clone the repository:

git clone <https://github.com/UPS-API/java-api-examples>

• Update your OAuth Client information in /src/main/resources/application.properties file. These values can be found in the UPS Developer Portal under Apps and your specific application's information.

• Update your client information in any tags marked with "< >" within the /src/main/resources/ json files. For this API there are the following fields:

• Build the project using Maven

cd <project home>
mvn clean package

• Run the project that is generated in the /target directory.

java -jar paperlessDocuments-x.x.x.jar    

• check console output for application result

There are 2 notable class in this tutorial, namely com.ups.api.app.AppConfig and com.ups.api.app.PaperlessDocuments. The AppConfig class is a configuration class leveraging Spring injection to incorporate the property value from src/main/resources/application.properties file. The PaperlessDocuments class is to illustrat how to use the uploadDocuments, pushImageToRepository and DeleteDocuments api.

 String accessToken = Util.getAccessToken(appConfig, restTemplate);

Get an access token via OAuth client_credentials grant type.

	// Create Paperless Documents Upload Request from a pre-determined json file
	PAPERLESSDOCUMENTUploadRequestWrapper paperlessUploadRequestWrapper = Util.createRequestFromJsonFile(
						entry.getValue().get(AppConfig.SCENARIO_PROPERTIES_JSON_FILE_NAME),
						PAPERLESSDOCUMENTUploadRequestWrapper.class,this.appConfig,null);			

It reconstructs a Paperless Upload Request Wrapper object from a json file. In a typical application, a PaperlessUploadRequestWrapper object would be created via a default constructor and calling setter to populate the attribute instead.

	// Get Upload documents status
	PAPERLESSDOCUMENTUploadResponseWrapper paperlessUploadResponseWrapper = (PAPERLESSDOCUMENTUploadResponseWrapper)this.sendRequest(paperlessUploadRequestWrapper);			

The sendRequest function creates a UploadDocuments api object and set the access token expiry tolerance if it haven't created one yet as well as populating with a valid access token. A Wrapper with Upload response will be returned from backend server providing the status of the upload with respective document ids.

• Request Schema PAPERLESSDOCUMENTUploadRequestWrapper
• Response Schema PAPERLESSDOCUMENTUploadResponseWrapper

{
  "UploadRequest": {
      "Request": {
          "RequestOption": "1",
          "TransactionReference": {
              "CustomerContext": "Verify 2 Files get succesfully uploaded"
          }
      },
      "UserCreatedForm": [
          {
              "UserCreatedFormFileName": "Test 1",
              "UserCreatedFormFile": "QmFzZSA2NCBlbmNvZGVkIGRhdGE=",
              "UserCreatedFormFileFormat": "txt",
              "UserCreatedFormDocumentType": "001"
          },
          {
            "UserCreatedFormFileName": "Test 2",
            "UserCreatedFormFile": "QmFzZSA2NCBlbmNvZGVkIGRhdGE=",
            "UserCreatedFormFileFormat": "txt",
            "UserCreatedFormDocumentType": "001"
        }
      ]
  }
}

{
    "UploadResponse": {
        "Response": {
            "ResponseStatus": {
                "Code": "1",
                "Description": "Success"
            },
            "TransactionReference": {
                "CustomerContext": "testing",
                "TransactionIdentifier": "trhel8vm2dmbbMlFddycP6"
            }
        },
        "FormsHistoryDocumentID": {
            "DocumentID": [
                "2022-12-19-20.43.52.123456",
                "2022-12-19-20.43.53.789101"
            ]
        }
    }
}

	// Create Paperless Documents Request from a pre-determined json file
	PAPERLESSDOCUMENTRequestWrapper paperlessRequestWrapper = Util.createRequestFromJsonFile(
						entry.getValue().get(AppConfig.SCENARIO_PROPERTIES_JSON_FILE_NAME),
						PAPERLESSDOCUMENTRequestWrapper.class,this.appConfig,new CreateRequestEnricher() {});  			               

It reconstructs a Paperless Request Wrapper object from a json file. In a typical application, a PAPERLESSDOCUMENTRequestWrapper object would be created via a default constructor and calling setter to populate the attribute instead.

	// Get Upload Image status
	PAPERLESSDOCUMENTResponseWrapper paperlessResponseWrapper = (PAPERLESSDOCUMENTResponseWrapper)this.sendRequest(paperlessRequestWrapper);			

The sendRequest function creates a UploadImage api object and set the access token expiry tolerance if it haven't created one yet as well as populating with a valid access token. A Wrapper with PushToImageRepository response will be returned from backend server providing the Transaction identifier and status of the push.

• Request Schema PAPERLESSDOCUMENTRequestWrapper
• Response Schema PAPERLESSDOCUMENTResponseWrapper

{
    "PushToImageRepositoryRequest": {
        "Request": {
            "TransactionReference": {
                "CustomerContext": "Verify Paperless Document request returns Success Response for PushToImageRepositoryRequest with DocumentID"
            }
        },
        "FormsHistoryDocumentID": {
            "DocumentID": "<Document ID>"
        },
        "ShipmentIdentifier": "<Shipment Identifier>",//holds the trackingNumber of the shipment
        "ShipmentType": "1",
        "TrackingNumber": "<Tracking Number>",
        "ShipmentDateAndTime":"2022-12-20-10.00.00"
    }
    }
}

{
    "PushToImageRepositoryResponse": {
        "Response": {
            "ResponseStatus": {
                "Code": "1",
                "Description": "Success"
            },
            "TransactionReference": {
                "CustomerContext": "testing",
                "TransactionIdentifier": "trhel8vm2dmbgsWjS4T1QG"
            }
        },
        "FormsGroupID": "<Forms Group ID>"
    }
}

	// Prepare Delete Document api access.
	DeleteDocumentsApi deleteApi = deleteDocumentsApi.get();
	if(null == deleteApi) {
					deleteApi = new DeleteDocumentsApi(new ApiClient(this.restTemplate));
					deleteApi.getApiClient().setBasePath(this.appConfig.getPaperlessDocumentsBaseUrl());
					deleteDocumentsApi.set(deleteApi);
				}
	deleteApi.getApiClient().addDefaultHeader(HttpHeaders.AUTHORIZATION, BEARER + accessToken);				 									               

Create a delete documents api object and set the access token expiry tolerance if it haven't created one yet as well as populating with a valid access token.

	// Delete document status
	PAPERLESSDOCUMENTDeleteResponseWrapper paperlessDeleteResponseWrapper = deleteApi.delete(this.appConfig.getPaperlessDocumentsVersion(), this.appConfig.getShipperNumber(),this.appConfig.getDocumentId(),transId,this.appConfig.getTransactionSrc());	
										

A Wrapper with delete response will be returned from backend server providing the Transaction identifier and status of the deletion.

• DELETE request
• Response Schema PAPERLESSDOCUMENTDeleteResponseWrapper

• DELETE Request {{url}}/api/paperlessdocuments/v1/DocumentId/ShipperNumber
• HEADERS: Content-Type:application/json ShipperNumber: transId:test123 transactionSrc:testing DocumentId:

{
    "DeleteResponse": {
        "Response": {
            "ResponseStatus": {
                "Code": "1",
                "Description": "Success"
            },
            "TransactionReference": {
                "CustomerContext": "testing",
                "TransactionIdentifier": "trhel8vm1dm8634TLv7mXv"
            }
        }
    }
}

It's recommended to create an instance of ApiClient per thread in a multithreaded environment to avoid any potential issues.