FAQ of ACE OCEAN NG API integration

FAQ of ACE OCEAN NG API integration

1. General

      1.1. What is ACE OCEAN?

      ACE OCEAN(AMS) is the ocean manifest system of US, which require carrier / NVOCC to file the manifest(BL) 24 hours before loading in the foreign port.
      Though this API of ACE OCEAN, customer can file the AMS through API and get the CBP response directly. 

      1.2. Where is the spec?

      The spec can be found here Regulatory Filing =>USA=>ACE OCEAN: https://developer.globaletrade.services/
      

      1.3 How can I use the online spec in my local?

  1. Install the postman in you laptop?
  2. Access online spec URL https://developer.globaletrade.services/
  3. Click the "Run in Postman" to import the spec into your local env, then follow the prompt from Postman. 
  4. As result, you can import the online spec into your local as below
  5. After the collection is imported into local, you can configure the UAT credentials and try to do the submission   

     1.4. What is the typical process for the integration?

      Please follow below steps to submit the request and retrieve the response. For more details, please refer to the Request and Response section. 
  1. [POST / Submission/BL Submission] : To submit the ACE Ocean request to GeTS and get the ack response.
  2. [GET / Response/[Endpoint]Retrieve Response] : To pull new response responses for all transactions. We can use this API for the system integration. 
  3. [GET / Response/[Endpoint]Retrieve Response per Transaction] : To get the response for one submission when failed to retrieve response in point b.


2. Account

      2.1. What UAT information shall I get from GeTS?

      We will provide you with information:
  1. UAT URL: https://tcompliance.globaletrade.services
  2. API key
  3. Route
  4. SCAC code(test)
  5. Organization Name

      2.2. How to use the provided UAT information in the local testing?

  1. UAT URL: Open  "variables" tab of postman collection by Clicking "CALISTA Developer Platform" => "Variables", copy https://tcompliance.globaletrade.services   into "crf-us-base-url"
  2. API key: follow the step a, copy the provided API key into "crf-us-api-key"
  3. Route: copy the provided route id into the request API at "Regulatory Filing" => "USA" => "ACE OCEAN" => "Submission" => "BL Submission"
  4. SCAC code(test): please copy the provided SCAC code at below location in the request JSON

      2.3. How to handle "Access is not authenticated" error message?

  1. Please check whether the route id is correct
  2. if the route id is correct, contact the point of contact from GeTS to investigate.

3. Request

3.1. Where is the request spec of ACE OCEAN BL?

  1. For the request of the submission endpoint, please find "USA" => "Endpoints" => "Submission"
  2. For the ACE OCEAN JSON spec within base64 string, please find "USA" => "ACE OCEAN" => "BL Submission"

3.2. Where can I find the sample JSON of ACE OCEAN BL?

      Access the "USA" => "ACE OCEAN" => "BL Submission", scroll down and find the "Sample JSON"
      

3.3. How can I submit the JSON request to GeTS?

  1. After importing the collection into your local (1.3 How can I use the online spec in my local?) and configure the UAT credential ( 2.2. How to use the provided UAT information in the local testing?)
  2. Access "USA" => "ACE OCEAN" => "BL Submission"
  3. Follow the spec and prepare the ACE OCEAN JSON, refer to "3.1. Where is the request spec of ACE OCEAN BL? and 3.2. Where can I find the sample JSON of ACE OCEAN BL?"
  4. Convert the ACE OCEAN JSON to base64 byte array, copy the byte array to base64 field
  5. Click the submit

3.4. What is the meaning of acknowledgement response after we submit the "submission" API?

      The ack response indicate that GeTS receive the request with a transaction id; Later the system will process the request.  Regarding the response from GeTS and CBP, please call response API.

4.1 Response

4.1 How can I get the response from GeTS?

There are 2 response API:
  • [GET / Response/[Endpoint]Retrieve Response] : To get new response responses for all transactions.
  • [GET / Response/[Endpoint]Retrieve Response per Transaction] : To get the response for one submission if there is any concerns.

4.2 How many response types for ACE OCEAN? Where are the specs of these response and where are the samples of these response types?

  • /ACE OCEAN/Response/GeTS Validation Response: The validation response is generated by Crimsonlogic GeTS, generated when the request could not pass Crimsonlogic validation
  • /ACE OCEAN/Response/CBP Direct Response: The accepted and rejected response from CBP
  • /ACE OCEAN/Response/CBP Status Notification: The status notification response from CBP. 

Other