customs-data-store

This repository contains the code for a persistent cache that holds customs-related data.

This microservice is a common backend service, which is used by other services. For example, it is used by CDS Exports, CDS Financials and CDS Reimbursements.

Pre-requisites

There are a number of dependencies required to run the service.

The easiest way to get started with these is via the Service Manager command line interface. You can find the installation instructions in the MDTP HandBook.

Command	Description
sm2 --start CUSTOMS_FINANCIALS_ALL	Runs all dependencies
sm2 -s	Shows running services
sm2 --stop CUSTOMS_DATA_STORE	Stop the micro service
sbt run or sbt "run 9893"	(from root dir) to compile the current service with your changes

Testing

The minimum requirement for test coverage is 90%. Builds will fail when the project drops below this threshold.

Unit tests

Command	Description
sbt test	Runs unit tests locally
sbt "test/testOnly *TEST_FILE_NAME*"	runs tests for a single file

Coverage

Command	Description
sbt clean coverage test coverageReport	Generates a unit test coverage report that you can find here target/scala-3.3.5/scoverage-report/index.html

Available routes

Path	Description	Comments
GET /customs-data-store/eori/verified-email	Retrieves a verified email address for the logged-in EORI either from cache or SUB09
GET /customs-data-store/eori/company-information	Retrieves the business full name and address for the logged-in EORI either from cache or SUB09
GET /customs-data-store/eori/eori-history	Retrieves a list of all historic EORI's associated with the logged-in EORI either from cache or SUB09
GET /customs-data-store/eori/xieori-information	Retrieves XI EORI information for the logged-in EORI either from cache or SUB09
POST /customs-data-store/eori/verified-email-third-party	Retrieves the verified email address for the EORI specified in request body either from cache or SUB09
POST /customs-data-store/eori/company-information-third-party	Retrieves the business full name for the EORI specified in request body either from cache or SUB09
POST /customs-data-store/eori/eori-history-third-party	Retrieves the historic EORIs for the EORI specified in request body from cache or SUB21
POST /customs-data-store/update-email	Populates a new verified email address in the cache and removes undeliverable information
POST /customs-data-store/update-eori-history	Updates the eori history for a given EORI in the cache
POST /customs-data-store/update-undeliverable-email	Updates undeliverable information for a given enrolmentValue
GET /customs-data-store/subscriptions/subscriptionsdisplay	Internal Use Only
GET /customs-data-store/subscriptions/unverified-email-display	Internal Use Only
GET /customs-data-store/subscriptions/email-display	Internal Use Only

Feature switches

Not applicable

GET /eori/verified-email

An endpoint to retrieve a verified email address for logged-in EORI.

Response body

{
  "address": "test@email.com",
  "timestamp": "2020-03-20T01:02:03Z"
}

Response codes

Status	Description
200	A verified email has been found for the specified eori
404	No verified email has been found for the specified eori
500	An unexpected failure happened in the service

GET /eori/company-information

An endpoint to retrieve the business full name and address for logged-in EORI.

Response body

{
  "name": "ABC ltd",
  "consent": "1",
  "address": {
    "streetAndNumber": "12 Example Street",
    "city": "Example",
    "postalCode": "AA00 0AA",
    "countryCode": "GB"
  }
}

Fields

Field	Required	Description
name	Mandatory	Company name
consent	Optional	consentToDisclosureOfPersonalData
address	Mandatory	The address Information for the company
address.streetAndNumber	Mandatory	The street and number where the company resides
address.city	Mandatory	The city where the company resides
address.postalCode	Optional	Mandatory for the country code "GB"
address.countryCode	Mandatory	The country code where the company resides

Response codes

Status	Description
200	Company information found and returned
404	Company information not found or elements of the payload not found

GET /eori/eori-history

An endpoint that retrieves a list of all historic EORI's associated with logged-in EORI.

Response body

{
  "eoriHistory": [
    {
      "eori": "historicEori1",
      "validFrom": "2001-01-20T00:00:00Z",
      "validTo": "2001-01-20T00:00:00Z"
    },
    {
      "eori": "historicEori2",
      "validFrom": "2001-01-20T00:00:00Z",
      "validTo": "2001-01-20T00:00:00Z"
    }
  ]
}

Response codes

Status	Description
200	A sequence of historic eori's returned
500	An unexpected failure happened in the service

GET /eori/xieori-information

An endpoint that retrieves XI EORI information for the requested EORI.

Response body

{
  "xiEori": "XI744638982004",
  "consent": "S",
  "address": {
    "pbeAddressLine1": "address line 1",
    "pbeAddressLine2": "address line 2",
    "pbeAddressLine3": "city 1",
    "pbePostCode": "AA1 1AA"
  }
}

Response codes

Status	Description
200	XI EORI information is returned
404	XI EORI information is retrieved neither from cache nor SUB09

POST /eori/verified-email-third-party

An endpoint to retrieve a verified email address for EORI specified in request body.

Example request

{
  "eori": "testEori"
}

Fields

Field	Required	Description
eori	Mandatory	The eori used to provide a verified email address to

Response body

{
  "address": "test@email.com",
  "timestamp": "2020-03-20T01:02:03Z"
}

Response codes

Status	Description
200	A verified email has been found for the specified eori
400	Malformed request
404	No verified email has been found for the specified eori
500	An unexpected failure happened in the service

POST /eori/company-information-third-party

An endpoint to retrieve the business full name and address for EORI specified in request body.

Example request

{
  "eori": "testEori"
}

Fields

Field	Required	Description
eori	Mandatory	The eori used to provide a verified email address to

Response body

{
  "name": "ABC ltd",
  "consent": "1",
  "address": {
    "streetAndNumber": "12 Example Street",
    "city": "Example",
    "postalCode": "AA00 0AA",
    "countryCode": "GB"
  }
}

Fields

Field	Required	Description
name	Mandatory	Company name
consent	Optional	consentToDisclosureOfPersonalData
address	Mandatory	The address Information for the company
address.streetAndNumber	Mandatory	The street and number where the company resides
address.city	Mandatory	The city where the company resides
address.postalCode	Optional	Mandatory for the country code "GB"
address.countryCode	Mandatory	The country code where the company resides

Response codes

Status	Description
200	A verified email has been found for the specified eori
400	Malformed request
404	No verified email has been found for the specified eori
500	An unexpected failure happened in the service

POST /eori/eori-history-third-party

An endpoint to retrieve the historic EORIs of a given third party EORI (not the logged-in user's EORI).

Example request

{
  "eori": "testEori"
}

Fields

Field	Required	Description
eori	Mandatory	The eori for which historically associated EORIs are to be retrieved

Response body

{
  "eoriHistory": [
    {
      "eori": "historicEori1",
      "validFrom": "2001-01-20T00:00:00Z",
      "validTo": "2001-01-20T00:00:00Z"
    },
    {
      "eori": "historicEori2",
      "validFrom": "2001-01-20T00:00:00Z",
      "validTo": "2001-01-20T00:00:00Z"
    }
  ]
}

Response codes

Status	Description
200	A sequence of historic eori's returned
500	An unexpected failure happened in the service

POST /update-email

An endpoint to update the verified email address for a given EORI and removes undeliverable information.

Example request

{
  "eori": "someEori",
  "address": "test@email.com",
  "timestamp": "2020-03-20T01:02:03Z"
}

Fields

Field	Required	Description
eori	Mandatory	The eori used to provide a verified email address to
address	Mandatory	The verified email address for the specified eori
timestamp	Mandatory	The timestamp when the email was verified

POST /update-eori-history

An endpoint to populate the historic EORI's for a given EORI.

Example request

{
  "eori": "testEori"
}

Response codes

Status	Description
204	Successfully updated the historic EORI's in the cache
500	An unexpected failure happened in the service

POST /update-undeliverable-email

An endpoint to update undeliverable information for an enrolmentValue.

Request parameters

Param	Type	Optional/Mandatory
subject	String	Mandatory
eventId	String	Mandatory
groupId	String	Mandatory
timestamp	DateTime	Mandatory
event.id	String	Mandatory
event.enrolment	String	Mandatory
event.emailAddress	String	Mandatory
event.event	String	Mandatory
event.detected	DateTime	Mandatory
event.code	Int	Optional
event.reason	String	Optional

Example request

{
  "subject": "subject-example",
  "eventId": "example-id",
  "groupId": "example-group-id",
  "timestamp": "2021-05-14T10:59:45.811+01:00",
  "event": {
    "id": "example-id",
    "event": "someEvent",
    "emailAddress": "email@email.com",
    "detected": "2021-05-14T10:59:45.811+01:00",
    "code": 12,
    "reason": "Inbox full",
    "enrolment": "HMRC-CUS-ORG~EORINumber~testEori"
  }
}

Response codes

Status	Description
204	Successfully updated undeliverable information for enrolmentValue
404	No update was performed on a record either due to it not existing or already having the same undeliverable information present
400	If enrolmentKey is not equal to 'HMRC-CUS-ORG' OR If enrolmentIdentifier is not equal to 'EORINumber'
500	An unexpected failure happened in the service

Helpful commands

Command	Description
sbt runAllChecks	Runs all standard code checks
sbt clean	Cleans code
sbt compile	Better to say 'Compiles the code'
sbt coverage	Prints code coverage
sbt test	Runs unit tests
sbt it/test	Runs integration tests
sbt scalafmtCheckAll	Runs code formatting checks based on .scalafmt.conf
sbt scalastyle	Runs code style checks based on /scalastyle-config.xml
sbt Test/scalastyle	Runs code style checks for unit test code /test-scalastyle-config.xml
sbt coverageReport	Produces a code coverage report
sbt "test/testOnly *TEST_FILE_NAME*"	runs tests for a single file
sbt clean coverage test coverageReport	Generates a unit test coverage report that you can find here target/scala-3.3.5/scoverage-report/index.html
sbt "run -Dfeatures.some-feature-name=true"	enables a feature locally without risking exposure