feat: Ni category updates

feat: Ni category updates

Author: sangeet-joy-tw

xero-payroll-uk.yaml

@@ -260,7 +260,7 @@ paths:
                                 "county":null,
                                 "countryName":null,
                                 "postCode": "MK9 1EB"
-                              }
+                              },
                               "payrollCalendarID":null,
                               "updatedDateUTC":"2020-03-25T03:12:10",
                               "createdDateUTC":"2020-03-25T03:12:10",
@@ -352,6 +352,20 @@ paths:
                               "payrollCalendarID": null,
                               "updatedDateUTC": "2017-05-12T10:00:24",
                               "createdDateUTC": "2017-05-12T10:00:24",
+                              "niCategories": [
+                                {
+                                  "startDate": "2020-05-01T00:00:00",
+                                  "niCategory": "A"
+                                },
+                                {
+                                  "startDate": null,
+                                  "niCategory": "F",
+                                  "niCategoryID": 1,
+                                  "dateFirstEmployedAsCivilian": null,
+                                  "workplacePostcode": "SW1A 1AA"
+                                }
+                              ],
+                              "employeeNumber": "2",
                               "endDate": null
                           }
                         }'
@@ -570,7 +584,14 @@ paths:
           python: start_date
           ruby: start_date
           object: employment
-          is_last: true 
+          is_last: true
+        - niCategories:
+          key: niCategories
+          keyPascal: NICategories
+          keySnake: ni_categories
+          is_object: true
+          object: employment
+          default: A
       summary: Creates employment detail for a specific employee using a unique employee ID
       parameters:
         - $ref: '#/components/parameters/idempotencyKey'
@@ -600,7 +621,15 @@ paths:
                           "employment": {
                             "payrollCalendarID": "216d80e6-af55-47b1-b718-9457c3f5d2fe",
                             "startDate": "2020-04-01T00:00:00",
-                            "niCategory": "A",
+                            "niCategories": [
+                              {
+                                "niCategory": "A",
+                                "startDate": "2020-05-01",
+                                "niCategoryID": 594,
+                                "dateFirstEmployedAsCivilian": null,
+                                "workplacePostcode": null
+                              }
+                            ],
                             "employeeNumber": "123ABC"
                           }
                         }'
@@ -619,8 +648,13 @@ paths:
             example: '{
                         "PayrollCalendarID": "216d80e6-af55-47b1-b718-9457c3f5d2fe",
                         "StartDate": "2020-04-01",
-                        "EmployeeNumber": "123ABC",
-                        "NICategory": "A"
+                        "NICategories": [
+                          {
+                            "NICategory": "A",
+                            "StartDate": "2020-05-01"
+                          }
+                        ],
+                        "EmployeeNumber": "123ABC"
                       }'
   /Employees/{EmployeeID}/Tax:
     parameters:
@@ -5997,6 +6031,14 @@ components:
           type: string
           format: date-time
           x-is-datetime: true
+        niCategory:
+          $ref: '#/components/schemas/NICategoryLetter'
+          deprecated: true
+        niCategories:
+          description: The employee's NI categories
+          type: array
+          items:
+            $ref: '#/components/schemas/NICategory'
         nationalInsuranceNumber:
           description: National insurance number of the employee
           type: string
@@ -6019,7 +6061,7 @@ components:
         - PayrollCalendarID
         - StartDate
         - EmployeeNumber
-        - NICategory
+        - NICategories
       properties:
         payrollCalendarID:
           description: Xero unique identifier for the payroll calendar of the employee
@@ -6035,23 +6077,14 @@ components:
           type: string
           example: 007
         niCategory:
-          description: The NI Category of the employee
-          type: string
-          enum:
-          - A
-          - B
-          - C
-          - F
-          - H
-          - I
-          - J
-          - L
-          - M
-          - S
-          - V
-          - X
-          - Z
-          example: A
+          $ref: '#/components/schemas/NICategoryLetter'
+          deprecated: true
+        niCategories:
+          description: The employee's NI categories
+          type: array
+          items:
+            $ref: '#/components/schemas/NICategory'
+
     EmployeeTaxObject:
       type: object
       properties:
@@ -7866,3 +7899,73 @@ components:
           description: The Xero identifier for Timesheet tracking category.
           type: string
           format: uuid
+    NICategoryLetter:
+      description: The employee's NI Category letter.
+      type: string
+      example: I
+      enum:
+      - A
+      - B
+      - C
+      - D
+      - E
+      - F
+      - H
+      - I
+      - J
+      - K
+      - L
+      - M
+      - N
+      - S
+      - V
+      - X
+      - Z
+    NICategory:
+      type: object
+      required:
+        - niCategory
+        - workplacePostcode
+      properties:
+        startDate:
+          description: The start date of the NI category (YYYY-MM-DD)
+          type: string
+          format: date
+          example: 2024-12-02  
+          x-is-date: true 
+        niCategory:
+          $ref: '#/components/schemas/NICategoryLetter'
+        niCategoryID:
+          description: Xero unique identifier for the NI category
+          type: number
+          example: 15
+        dateFirstEmployedAsCivilian:
+          description: The date in which the employee was first employed as a civilian (YYYY-MM-DD)
+          type: string
+          format: date
+          example: 2024-12-02
+          x-is-date: true 
+        workplacePostcode:
+          description: The workplace postcode
+          type: string
+          example: SW1A 1AA
+      oneOf:
+        - required:
+          - workplacePostcode
+          properties:
+            niCategory:
+              enum: 
+                - F
+                - I
+                - L
+                - S
+                - N
+                - E
+                - D
+                - K
+        - required:
+          - dateFirstEmployedAsCivilian
+          properties:
+            niCategory:
+              enum:
+                - V