Skip to content

Commit fa530a2

Browse files
Thepworth95Thepworth95
authored
[MTDSA-30246] - Retrieve Periods Of Account OAS (#186)
1 parent d56a8aa commit fa530a2

File tree

7 files changed

+197
-0
lines changed

7 files changed

+197
-0
lines changed

‎resources/public/api/conf/2.0/application.yaml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,5 +63,7 @@ paths:
6363
$ref: "./quarterly_period_type_create_amend.yaml"
6464
/individuals/business/details/{nino}/{businessId}/{taxYear}/accounting-type:
6565
$ref: "./accounting_type.yaml"
66+
/individuals/business/details/{nino}/{businessId}/{taxYear}/periods-of-account:
67+
$ref: "./periods_of_account.yaml"
6668

6769

‎resources/public/api/conf/2.0/common/pathParameters.yaml

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,17 @@ components:
3535
description: |
3636
The tax year the data applies to. The start year and end year must not span two tax years.
3737
The minimum tax year is 2025-26. No gaps are allowed, for example, 2025-27 is not valid. (The minimum tax year in Sandbox is 2024-25.)
38+
schema:
39+
type: string
40+
pattern: ^2[0-9]{3}-[0-9]{2}$
41+
example: "2024-25"
42+
required: true
43+
periodsOfAccountTypeTaxYear:
44+
name: taxYear
45+
in: path
46+
description: |
47+
The tax year the data applies to. The start year and end year must not span two tax years.
48+
The minimum tax year is 2025-26. No gaps are allowed, for example, 2025-27 is not valid.
3849
schema:
3950
type: string
4051
pattern: ^2[0-9]{3}-[0-9]{2}$

‎resources/public/api/conf/2.0/examples/retrievePeriodsOfAccount/response.json

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{
2+
"periodsOfAccount": true,
3+
"periodsOfAccountDates": [
4+
{
5+
"startDate": "2025-04-06",
6+
"endDate": "2025-07-05"
7+
},
8+
{
9+
"startDate": "2025-07-06",
10+
"endDate": "2025-10-05"
11+
},
12+
{
13+
"startDate": "2025-10-06",
14+
"endDate": "2026-01-05"
15+
},
16+
{
17+
"startDate": "2026-01-06",
18+
"endDate": "2026-04-05"
19+
}
20+
]
21+
}

‎resources/public/api/conf/2.0/examples/retrievePeriodsOfAccount/response2.json

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"periodsOfAccount": false
3+
}

‎resources/public/api/conf/2.0/periods_of_account.yaml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
get:
2+
$ref: "./retrieve_periods_of_account.yaml"
3+
summary: Retrieve Periods Of Account
4+
security:
5+
- User-Restricted:
6+
- read:self-assessment

‎resources/public/api/conf/2.0/retrieve_periods_of_account.yaml

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
summary: Retrieve Periods Of Account
2+
description: |
3+
This API is used to retrieve a customers Periods of Account and can submit the Periods of Account dates.
4+
5+
### Test data
6+
Scenario simulations using <code>Gov-Test-Scenario</code> headers is only available in the sandbox environment.
7+
| Header Value (Gov-Test-Scenario) | Scenario |
8+
| -------------------------------- | ---------------------------------------------------------------- |
9+
| N/A - DEFAULT | Simulate a successful response |
10+
| NO_PERIODS_OF_ACCOUNT | Simulate a successful response with no periods of account |
11+
| NOT_FOUND | Simulate a scenario where no data is found. |
12+
| STATEFUL | Performs a stateful submission of the request that is submitted. |
13+
14+
15+
16+
parameters:
17+
- $ref: './common/pathParameters.yaml#/components/parameters/nino'
18+
- $ref: './common/pathParameters.yaml#/components/parameters/businessId'
19+
- $ref: './common/pathParameters.yaml#/components/parameters/periodsOfAccountTypeTaxYear'
20+
- $ref: './common/headers.yaml#/components/parameters/acceptJson'
21+
- $ref: './common/headers.yaml#/components/parameters/authorization'
22+
- $ref: './common/headers.yaml#/components/parameters/testScenarioHeader'
23+
24+
tags:
25+
- Periods Of Account
26+
27+
security:
28+
- User-Restricted:
29+
- read:self-assessment
30+
31+
responses:
32+
"200":
33+
description: Success
34+
headers:
35+
X-CorrelationId:
36+
$ref: './common/headers.yaml#/components/parameters/correlationId'
37+
Deprecation:
38+
$ref: './common/headers.yaml#/components/parameters/deprecationHeader'
39+
Sunset:
40+
$ref: './common/headers.yaml#/components/parameters/sunsetHeader'
41+
Link:
42+
$ref: './common/headers.yaml#/components/parameters/linkHeader'
43+
content:
44+
application/json:
45+
schema:
46+
$ref: './schemas/retrievePeriodsOfAccount/response.json'
47+
examples:
48+
PERIODS_OF_ACCOUNT_TRUE:
49+
description: Example Response when the periodsOfAccount field is true
50+
value:
51+
$ref: './examples/retrievePeriodsOfAccount/response.json'
52+
PERIODS_OF_ACCOUNT_FALSE:
53+
description: Example Response when the periodsOfAccount field is false
54+
value:
55+
$ref: './examples/retrievePeriodsOfAccount/response2.json'
56+
"400":
57+
description: Bad request
58+
headers:
59+
X-CorrelationId:
60+
$ref: './common/headers.yaml#/components/parameters/correlationId'
61+
Deprecation:
62+
$ref: './common/headers.yaml#/components/parameters/deprecationHeader'
63+
Sunset:
64+
$ref: './common/headers.yaml#/components/parameters/sunsetHeader'
65+
Link:
66+
$ref: './common/headers.yaml#/components/parameters/linkHeader'
67+
content:
68+
application/json:
69+
schema:
70+
$ref: './schemas/error-response.yaml'
71+
examples:
72+
FORMAT_NINO:
73+
$ref: './common/errors.yaml#/components/examples/formatNino'
74+
FORMAT_TAX_YEAR:
75+
$ref: './common/errors.yaml#/components/examples/formatTaxYear'
76+
FORMAT_BUSINESS_ID:
77+
$ref: './common/errors.yaml#/components/examples/formatBusinessId'
78+
RULE_TAX_YEAR_RANGE_INVALID:
79+
$ref: './common/errors.yaml#/components/examples/ruleTaxYearRangeInvalid'
80+
RULE_TAX_YEAR_NOT_SUPPORTED:
81+
$ref: './common/errors.yaml#/components/examples/ruleTaxYearNotSupported'
82+
RULE_INCORRECT_GOV_TEST_SCENARIO:
83+
$ref: './common/errors.yaml#/components/examples/ruleIncorrectGovTestScenario'
84+
85+
"403":
86+
description: Forbidden
87+
headers:
88+
X-CorrelationId:
89+
$ref: './common/headers.yaml#/components/parameters/correlationId'
90+
Deprecation:
91+
$ref: './common/headers.yaml#/components/parameters/deprecationHeader'
92+
Sunset:
93+
$ref: './common/headers.yaml#/components/parameters/sunsetHeader'
94+
Link:
95+
$ref: './common/headers.yaml#/components/parameters/linkHeader'
96+
content:
97+
application/json:
98+
schema:
99+
$ref: './schemas/error-response.yaml'
100+
examples:
101+
CLIENT_OR_AGENT_NOT_AUTHORISED:
102+
$ref: './common/errors.yaml#/components/examples/clientOrAgentNotAuthorised'
103+
104+
"404":
105+
description: Not Found
106+
headers:
107+
X-CorrelationId:
108+
$ref: './common/headers.yaml#/components/parameters/correlationId'
109+
Deprecation:
110+
$ref: './common/headers.yaml#/components/parameters/deprecationHeader'
111+
Sunset:
112+
$ref: './common/headers.yaml#/components/parameters/sunsetHeader'
113+
Link:
114+
$ref: './common/headers.yaml#/components/parameters/linkHeader'
115+
content:
116+
application/json:
117+
schema:
118+
$ref: './schemas/error-response.yaml'
119+
examples:
120+
MATCHING_RESOURCE_NOT_FOUND:
121+
$ref: './common/errors.yaml#/components/examples/notFound'

‎resources/public/api/conf/2.0/schemas/retrievePeriodsOfAccount/response.json

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
{
2+
"$schema": "http://json-schema.org/draft-04/schema#",
3+
"description": "Retrieve accounting type response",
4+
"type": "object",
5+
"properties": {
6+
"periodsOfAccount": {
7+
"type": "boolean",
8+
"description": "Indicates whether the customer has periods of account.\n\nIf this value is true then periodsOfAccountDates must be submitted.",
9+
"example": true
10+
},
11+
"periodsOfAccountDates": {
12+
"type": "array",
13+
"description": "List of periods of account. These will be returned if a customer has submitted periods of account.\n\nIf periodsOfAccount is set to false, then this value will not be returned.",
14+
"items": {
15+
"type": "object",
16+
"properties": {
17+
"startDate": {
18+
"type": "string",
19+
"description": "The start date of the period of account.",
20+
"example": "2024-01-01"
21+
},
22+
"endDate": {
23+
"type": "string",
24+
"description": "The end date of the period of account.",
25+
"example": "2024-03-31"
26+
}
27+
},
28+
"required": ["startDate", "endDate"]
29+
}
30+
}
31+
},
32+
"required": ["periodsOfAccount"]
33+
}

0 commit comments

Comments
 (0)