Merge branch 'feature/H-1976' into 'master'

feature/H-1976

See merge request hrbox-public/api!18

v2/swagger.yaml

@@ -487,10 +487,102 @@ paths:
     get:
       tags:
         - org-employment
-      summary: Get list of requested org employment files
+      summary: Org employment files
+      parameters:
+        - name: id
+          in: query
+          description: Unique identifier of the document (UUID)
+          required: false
+          schema:
+            type: string
+            format: uuid
+        - name: created_at
+          in: query
+          description: Creation date (ISO 8601 format)
+          required: false
+          schema:
+            type: string
+            format: date-time
+        - name: updated_at
+          in: query
+          description: Last update date (ISO 8601 format)
+          required: false
+          schema:
+            type: string
+            format: date-time
+        - name: ready_at
+          in: query
+          description: Ready date (ISO 8601 format)
+          required: false
+          schema:
+            type: string
+            format: date-time
+        - name: custom_id
+          in: query
+          description: Custom identifier (string, up to 64 characters)
+          required: false
+          schema:
+            type: string
+            maxLength: 64
+        - name: organization_id
+          in: query
+          description: Organization identifier (string, up to 64 characters)
+          required: false
+          schema:
+            type: string
+            maxLength: 64
+        - name: org_employment_id
+          in: query
+          description: Employment record number (string, up to 64 characters)
+          required: false
+          schema:
+            type: string
+            maxLength: 64
+        - name: user_id
+          in: query
+          description: User identifier (UUID)
+          required: false
+          schema:
+            type: string
+            format: uuid
+        - name: file_id
+          in: query
+          description: File identifier (UUID)
+          required: false
+          schema:
+            type: string
+            format: uuid
+        - name: org_employment_file_type_id
+          in: query
+          description:
+            Document type (enum: see documentation)
+          required: false
+          schema:
+            $ref: '#/components/schemas/orgEmploymentFileType'
+        - name: org_employment_file_status_id
+          in: query
+          description:
+            Document status (enum: see documentation)
+          required: false
+          schema:
+            $ref: '#/components/schemas/orgEmploymentFileStatus'
+        - name: date_from
+          in: query
+          description: Start date of the range (ISO 8601 format)
+          required: false
+          schema:
+            type: string
+            format: date
+        - name: date_to
+          in: query
+          description: End date of the range (ISO 8601 format)
+          required: false
+          schema:
+            type: string
+            format: date
       responses:
         200:
-          description: Org employment files
+          description: Get list of requested org employment files
           content:
             application/json:
               schema:
@@ -512,17 +604,45 @@ paths:
           description: Server Error
 
   /org-employment-file/request:
-    get:
+    post:
       tags:
         - org-employment
-      summary: Get org employment file
+      summary: Request Org employment file
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                org_employment_id:
+                  type: string
+                  format: uuid
+                  description: User`s org employment ID
+                org_employment_file_type_id:
+                  $ref: '#/components/schemas/orgEmploymentFileType'
+                date_from:
+                  description: Дата с (например для расчетной ведомости, за период с)
+                  type: string
+                  format: 'date'
+                  example: 2025-04-23
+                date_to:
+                  description: Дата по (например для расчетной ведомости, за период по)
+                  type: string
+                  format: 'date'
+                  example: 2025-04-27
       responses:
         200:
-          description: Get org employment file
+          description: Create request for Org employment file
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/orgEmploymentFile'
+                allOf:
+                  - $ref: '#/components/schemas/httpJsonResponse'
+                  - type: object
+                    properties:
+                      data:
+                        $ref: '#/components/schemas/orgEmploymentFile'
         401:
           description: Unauthorized request
         403:
@@ -4732,6 +4852,27 @@ components:
       name: X-Hrbox-Client-Id
       description: "Авторизация с использованием API-ключа. Требуемые заголовки: Content-Type, X-Hrbox-Client-Id, X-Hrbox-Client-Secret."
   schemas:
+    httpJsonResponse:
+      type: object
+      properties:
+        success:
+          description: Result status.
+          type: boolean
+          example: true
+        data:
+          type: object
+          description: Response data
+        errors:
+          type: array
+          items:
+            type: string
+          description: Array of validation errors
+        message:
+          description: Message displayed to user (localized).
+          type: array
+          nullable: true
+          example: ''
+
     _meta:
       type: object
       properties:
@@ -8466,31 +8607,9 @@ components:
           format: uuid
           example: 195e1707-3f5d-4780-8dc1-b1023e1f974f
         org_employment_file_status_id:
-          type: integer
+          $ref: '#/components/schemas/orgEmploymentFileStatus'
-          description: Cостояние документа
-          oneOf:
-            - title: REQUESTED
-              const: 1
-              description: "Запрошен"
-            - title: PENDING
-              const: 2
-              description: "В обработке"
-            - title: READY
-              const: 3
-              description: "Готов"
         org_employment_file_type_id:
-          type: integer
+          $ref: '#/components/schemas/orgEmploymentFileType'
-          description: Тип документа
-          oneOf:
-            - title: PAYSLIP
-              const: payslip
-              description: "Расчетный лист"
-            - title: NDFL2
-              const: ndfl2
-              description: "2НДФЛ"
-            - title: CUSTOM
-              const: custom
-              description: "Кастомный тип"
         custom_id:
           description: ID кастомной обработки
           type: string
@@ -8530,6 +8649,30 @@ components:
           format: uuid
           example: 195e1707-3f5d-4780-8dc1-b1023e1f974f
 
+    orgEmploymentFileType:
+      type: string
+      description: >
+         Тип документа:
+           * `payslip` - Расчетный лист (PAYSLIP).
+           * `ndfl2` - 2НДФЛ (NDFL2).
+           * `custom` - Кастомный тип (CUSTOM).
+      enum:
+        - payslip
+        - ndfl2
+        - custom
+
+    orgEmploymentFileStatus:
+      type: integer
+      description: >
+        Состояние документа:
+          * `1` - Запрошен (REQUESTED).
+          * `2` - В обработке (PENDING).
+          * `3` - Готов (READY).
+      enum:
+        - 1
+        - 2
+        - 3
+
   parameters:
     boardDateTypeParam:
       in: query