This service offers a general interface for custom declarations, where those declarations are represented using the WCO declarations schema. In addition to submitting declarations, the Customs Declarations service allows you to amend and cancel them. It also provides the ability to upload supporting documents and make arrival notifications.
The objective of the Customs Declarations Service API is:
- Receive a request from a declarant wishing to make a declaration
- Validate the request payload conforms to the schema DMS WCO 3.6 schema
- Pass the request onto CDS backend
- Respond to the declarant indicating the success of steps 2 / 3.
As the notification process is asynchronous the only response to the declarant from this API is to indicate the success (or otherwise) of the validation and submission to the CDS backend.
- This microservice requires mongoDB 4.+
- Run locally:
sbt runwhich runs on port9820by default - Run with test endpoints:
sbt 'run -Dapplication.router=testOnlyDoNotUseInAppConf.Routes'
The Customs Declarations service can be run locally from Service Manager, using the following profiles:
| Profile Details | Command | Description |
|---|---|---|
| CUSTOMS_DECLARATION_ALL | sm2 --start CUSTOMS_DECLARATION_ALL | To run all CDS applications. |
| CUSTOMS_INVENTORY_LINKING_EXPORTS_ALL | sm2 --start CUSTOMS_INVENTORY_LINKING_EXPORTS_ALL | To run all CDS Inventory Linking Exports related applications. |
| CUSTOMS_INVENTORY_LINKING_IMPORTS_ALL | sm2 --start CUSTOMS_INVENTORY_LINKING_IMPORTS_ALL | To run all CDS Inventory Linking Imports related applications. |
- Run Unit Tests:
sbt test - Run Integration Tests:
sbt IntegrationTest/test - Run Unit and Integration Tests:
sbt test IntegrationTest/test - Run Unit and Integration Tests with coverage report:
./run_all_tests.sh
which runsclean scalastyle coverage test it:test coverageReport dependencyUpdates"
To run the CDS acceptance tests, see here.
To run performance tests, see here.
For Customs Declarations API documentation, see here.
Path - internal routes prefixed by /customs-declarations |
Supported Methods | Description |
|---|---|---|
/customs-declarations/ |
POST | Endpoint to submit a declaration. |
/customs-declarations/cancellation-requests |
POST | Endpoint to cancel a declaration. |
/customs-declarations/amend |
POST | Endpoint to amend a declaration. |
/customs-declarations/file-upload |
POST | Endpoint to submit a file upload. |
/customs-declarations/uploaded-file-upscan-notifications/clientSubscriptionId/:clientSubscriptionId |
POST | Endpoint to manage file upload upscan notifications. |
/customs-declarations/file-transmission-notify/clientSubscriptionId/:clientSubscriptionId |
POST | Endpoint to submit file upload notifications to customs notification. |
/customs-declarations/arrival-notification |
POST | Endpoint to submit an arrival notification declaration. |
| Path | Supported Methods | Description |
|---|---|---|
/file-upload/test-only/all |
DELETE | Endpoint to delete all file upload metadata. |
A request to the /file-upload endpoint can contain successRedirect and errorRedirect URLs. These are non-mandatory. If both a success and error redirect are included then upscan v2 will be called, otherwise v1.
There is an SBT task zipWcoXsds that generates a ZIP file containing schemas and example messages for each version under /public/api/conf
during the packaging phase (so are not generated during normal development). These ZIP files are referenced by the YAML.
These references are rendered as HTML links to generated ZIP in the deployed service.
To generate the zip file locally run the following command in command line from project root directory:
sbt package
The X-Client-ID header, together with the application context and version are used
to call the api-subscription-fields service to get the unique fieldsId UUID to pass on to the backend request.
Note the service to get the fieldsId is not currently stubbed.
Make sure the api-subscription-fields service is running on port 9650. Then run the below curl command.
Please note that version 2.0 is used as an example in the commands given, and you should insert the customs declarations api version number which you will call subsequently.
Please note that value d65f2252-9fcf-4f04-9445-5971021226bb is used as an example in the commands given, and you should insert the UUID value which suits your needs.
curl -v -X PUT "http://localhost:9650/field/application/d65f2252-9fcf-4f04-9445-5971021226bb/context/customs%2Fdeclarations/version/2.0" -H "Cache-Control: no-cache" -H "Content-Type: application/json" -d '{ "fields" : { "callbackUrl" : "https://postman-echo.com/post", "securityToken" : "securityToken", "authenticatedEori": "ABC123" } }'
We then have to manually reset the fieldId field to match the id expected by the downstream services. In a mongo command
window paste the following, one after the other.
use api-subscription-fields
db.subscriptionFields.update(
{ "clientId" : "d65f2252-9fcf-4f04-9445-5971021226bb", "apiContext" : "customs/declarations", "apiVersion" : "2.0" },
{ $set:
{"fieldsId" : "d65f2252-9fcf-4f04-9445-5971021226bb"}
}
)
When you then send a request to customs-declarations make sure you have the HTTP header X-Client-ID with the value d65f2252-9fcf-4f04-9445-5971021226bb
Three versions of this service are available on the Developer Hub.
Each have separate configuration sections for the MDG wco-declaration endpoint so the versions may be pointed to different backend services.
Supplying the required ACCEPT header in the request distinguishes which service configuration to use:
| Accept Header | Version |
|---|---|
| application/vnd.hmrc.1.0+xml | v1 |
| application/vnd.hmrc.2.0+xml | v2 |
| application/vnd.hmrc.3.0+xml | v3 |
Please note that requests with any other value of Accept header are rejected with 406 Not Acceptable response status.
Dynamic switching of service endpoints has been implemented for wco declaration connector. To configure dynamic switching of the endpoint there must be a corresponding section in the application config file (see example below). This should contain the endpoint config details.
The service customs-declarations has a default configuration and a stub configuration. Note
that default configuration is declared directly inside the customs-declarations section.
Prod {
...
services {
...
wco-declaration {
host = some.host
port = 80
bearer-token = "some_token"
context = /services/declarationmanagement/1.0.0
stub {
host = localhost
port = 9479
bearer-token = "some_stub_token"
context = "/registrations/registerwithid/1.0.0"
}
}
v2 {
wco-declaration {
host = some.host
port = 80
bearer-token = "some_token"
context = /services/declarationmanagement/1.0.0
stub {
host = localhost
port = 9479
bearer-token = "some_stub_token"
context = "/registrations/registerwithid/1.0.0"
}
}
}
}
}
default version (application/vnd.hmrc.1.0+xml):
curl -X "POST" http://customs-declarations-host/test-only/service/wco-declaration/configuration -H 'content-type: application/json' -d '{ "environment": "stub" }'
version 2 (application/vnd.hmrc.2.0+xml):
curl -X "POST" http://customs-declarations-host/test-only/service/v2.wco-declaration/configuration -H 'content-type: application/json' -d '{ "environment": "stub" }'
The service customs-declarations is now configured to use the stub environment
curl -X "POST" http://customs-declarations-host/test-only/service/wco-declaration/configuration -H 'content-type: application/json' -d '{ "environment": "default" }'
The service customs-declarations is now configured to use the default environment
curl -X "GET" http://customs-declarations-host/test-only/service/wco-declaration/configuration
{
"service": "wco-declaration",
"environment": "stub",
"url": "http://currenturl/customs-declarations"
"bearerToken": "current token"
}
This code is open source software licensed under the Apache 2.0 License.