Updates the user answers cache for a specific appaId and period key if the user has the lock.
Calls to this API must be made by an authenticated and authorised user with an ADR enrolment in order for the data to be returned.
URL: /alcohol-duty-returns/cache/set
Method: PUT
Request Body
The data section contains the actual user answers and other stored data. The content will depend on the specific questions answered and will not be documented in detail here
Field Name | Description | Data Type | Mandatory/Optional | Notes |
---|---|---|---|---|
_id | The identification | ReturnId | Mandatory | |
_id.appaId | The appaId | String | Mandatory | |
_id.periodKey | The period of the return | String | Mandatory | YYAM (year, 'A,' month A-L) |
groupId | The user's groupId | String | Mandatory | |
internalId | The user's id | String | Mandatory | |
regimes | The regimes the user is subscribed | Set(Enum) | Mandatory | Beer, Cider, Wine, Spirits, OtherFermentedProduct |
data | The user answers data | Object | Mandatory | 'Free form'; also contains obligations |
data.obligationData | The obligation data | ObligationData | Mandatory | |
data.obligationData.status | The current obligation status | Enum | Mandatory | Open |
data.obligationData.fromDate | The date from which the period applies | Date | Mandatory | YYYY-MM-DD |
data.obligationData.toDate | The date to which the period applies | Date | Mandatory | YYYY-MM-DD |
data.obligationData.dueDate | The date the return is due to be filed and paid by | Date | Mandatory | |
data.obligationData.periodKey | The period key of the obligation | String | Mandatory | YYAM (year, A, month A-L) |
data.lastUpdated | The timestamp of the last update | Timestamp | Mandatory | value inside $date.$numberLong |
data.validUntil | The timestamp of the validity expiry | Timestamp | Mandatory | value inside $date.$numberLong |
Required Request Headers:
Header Name | Header Value | Description |
---|---|---|
Authorization | Bearer {TOKEN} | A valid bearer token from the auth service |
Code: 200 OK
Response Body
The response body returns the user answers cache entry if set up which relates to details for a return for a specific appaId and period.
The data section contains the actual user answers and other stored data. The content will depend on the specific questions answered and will not be documented in detail here
Field Name | Description | Data Type | Mandatory/Optional | Notes |
---|---|---|---|---|
_id | The identification | ReturnId | Mandatory | |
_id.appaId | The appaId | String | Mandatory | |
_id.periodKey | The period of the return | String | Mandatory | YYAM (year, 'A,' month A-L) |
groupId | The user's groupId | String | Mandatory | |
internalId | The user's id | String | Mandatory | |
regimes | The regimes the user is subscribed | Set(Enum) | Mandatory | Beer, Cider, Wine, Spirits, OtherFermentedProduct |
data | The user answers data | Object | Mandatory | 'Free form'; also contains obligations |
data.obligationData | The obligation data | ObligationData | Mandatory | |
data.obligationData.status | The current obligation status | Enum | Mandatory | Open |
data.obligationData.fromDate | The date from which the period applies | Date | Mandatory | YYYY-MM-DD |
data.obligationData.toDate | The date to which the period applies | Date | Mandatory | YYYY-MM-DD |
data.obligationData.dueDate | The date the return is due to be filed and paid by | Date | Mandatory | |
data.obligationData.periodKey | The period key of the obligation | String | Mandatory | YYAM (year, A, month A-L) |
data.lastUpdated | The timestamp of the last update | Timestamp | Mandatory | value inside $date.$numberLong |
data.validUntil | The timestamp of the validity expiry | Timestamp | Mandatory | value inside $date.$numberLong |
Request/Response Body Examples
An example entry with the rest of the data portion removed:
{
"_id": {
"appaId": "AP0000000001",
"periodKey": "24AF"
},
"groupId": "testGroupId-01234567-89ab-cdef-fdec-ba9876543210",
"internalId": "Int-01234567-89ab-cdef-fdec-ba9876543210",
"regimes": [
"Spirits",
"Wine",
"Cider",
"OtherFermentedProduct",
"Beer"
],
"data": {
"obligationData": {
"status": "Open",
"fromDate": "2024-06-01",
"toDate": "2024-06-30",
"dueDate": "2024-08-07",
"periodKey": "24AF"
}
},
"lastUpdated": {
"$date": {
"$numberLong": "1726578927221"
}
},
"validUntil": {
"$date": {
"$numberLong": "1729170927221"
}
}
}
Code: 401 UNAUTHORIZED
This response can occur when a call is made by any consumer without an authorized session that has an ADR enrolment.
Code: 404 NOT_FOUND
No cache entry to update was found for the appaId,periodKey pair
Code: 423 LOCKED
The return is locked
Code: 500 INTERNAL_SERVER_ERROR
This response can occur if the query to the database fails