[APT-1257] documentation for hourly absence creation new endpoint

personio-personnel-data-api-oa3.yaml

@@ -1740,7 +1740,7 @@ paths:
  application/x-www-form-urlencoded:
  schema:
  $ref: "#/components/schemas/CreateTimeOffPeriodRequest"
- description: Absense data
+ description: Absence data
  required: true
  x-readme:
  code-samples:
@@ -1749,7 +1749,7 @@ paths:
  - language: "php"
  code: "Auto-generated code snippets for this language may not be supported"
  responses:
- "201":
+ "200":
  description: The absence period is successfully created
  content:
  application/json:
@@ -1831,7 +1831,7 @@ paths:
  success: false
  error:
  code: 0
- message: 'Something went wrong'
+ message: 'Time-off type not found.'
 
  "422":
  description: Validation error
@@ -2107,6 +2107,7 @@ paths:
  type: AbsenceType
  attributes:
  id: "9bba303f-0fbc-4514-9958-0befa21923fb"
+ name: "Absence Type Name"
  certificate:
  status: not-required
  start: "2022-05-31T22:00:00.0Z"
@@ -2139,6 +2140,146 @@ paths:
  problem+json:
  schema:
  $ref: "#/components/schemas/ErrorResponse"
+ post:
+ security:
+ - BearerAuth: [ ]
+ tags:
+ - Absences
+ description: Adds absence data for absence types **tracked in hours**.
+ requestBody:
+ content:
+ application/x-www-form-urlencoded:
+ schema:
+ $ref: "#/components/schemas/CreateAbsencePeriodRequest"
+ description: Absence data
+ required: true
+ x-readme:
+ code-samples:
+ - language: "powershell"
+ code: "Auto-generated code snippets for this language may not be supported"
+ - language: "php"
+ code: "Auto-generated code snippets for this language may not be supported"
+ responses:
+ "201":
+ description: The absence period is successfully created
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ data:
+ $ref: "#/components/schemas/HourlyAbsencePeriodResponse"
+ examples:
+ response:
+ value:
+ success: true
+ data:
+ - type: AbsencePeriod
+ attributes:
+ id: 9bba303f-0fbc-4514-9958-0befa21923fb
+ measurement_unit: "hour"
+ effective_duration: 960
+ employee:
+ type: Employee
+ attributes:
+ id:
+ label: id
+ value: 2367
+ type: integer
+ universal_id: id
+ first_name:
+ label: First name
+ value: Michael
+ type: standard
+ universal_id: first_name
+ last_name:
+ label: Last name
+ value: Miller
+ type: standard
+ universal_id: last_name
+ email:
+ label: Email
+ value: michael.miller@demo.com
+ type: standard
+ universal_id: email
+ absence_type:
+ type: AbsenceType
+ attributes:
+ id: "9bba303f-0fbc-4514-9958-0befa21923fb"
+ name: "Absence Type Name"
+ certificate:
+ status: not-required
+ start: "2022-05-31T22:00:00.0Z"
+ end: "2022-06-02T22:00:00.0Z"
+ half_day_start: true
+ half_day_end: false
+ comment: "this is a comment"
+ origin: "web"
+ status: "approved"
+ created_by: 1
+ created_at: "2022-06-20T14:29:56.510Z"
+ updated_at: "2022-06-20T14:29:56.510Z"
+ approved_at: "2022-06-20T14:29:56.510Z"
+ breakdowns:
+ - date: "2022-06-01"
+ effective_duration: 480
+ - date: "2022-06-02"
+ effective_duration: 480
+ "400":
+ description: Invalid request
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/ErrorInsertingAbsenceResponse"
+ examples:
+ response:
+ value:
+ success: false
+ error:
+ code: 400
+ message: 'Error when trying to insert absence period'
+
+ "404":
+ description: Employee or Absence type not found
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/ErrorResponse"
+ examples:
+ response:
+ value:
+ success: false
+ error:
+ code: 0
+ message: 'Absence type not found.'
+
+ "422":
+ description: Validation error
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/ErrorCreateAbsenceResponse"
+ examples:
+ response:
+ value:
+ success: false
+ error:
+ code: 0
+ message: 'The given data failed to pass validation.'
+ error_data: '{...}'
+ "500":
+ description: Internal server error
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/ErrorResponse"
+ examples:
+ response:
+ value:
+ success: false
+ error:
+ code: 0
+ message: 'Something went wrong'
 
  "/company/document-categories":
  parameters:
@@ -2721,7 +2862,7 @@ components:
  example: The absence period was not found.
 
  ErrorInsertingAbsenceResponse:
- title: 400 absense error
+ title: 400 absence error
  type: object
  properties:
  success:
@@ -3808,11 +3949,11 @@ components:
  half_day_start:
  type: boolean
  example: false
- description: Weather the start date is a half-day off.
+ description: Whether the start date is a half-day off.
  half_day_end:
  type: boolean
  example: false
- description: Weather the end date is a half-day off.
+ description: Whether the end date is a half-day off.
  comment:
  type: string
  example: Some Comment
@@ -3828,6 +3969,62 @@ components:
  - end_date
  - half_day_start
  - half_day_end
+ CreateAbsencePeriodRequest:
+ title: Create Absence periods **tracked in hours**
+ type: object
+ properties:
+ employee_id:
+ type: integer
+ description: Employee identifier
+ absence_type_id:
+ type: string
+ format: uuid
+ description: Absence type identifier
+ start_date:
+ type: string
+ format: date
+ description: "Absence start date. Format: yyyy-mm-dd"
+ example: '2020-01-31'
+ end_date:
+ type: string
+ format: date
+ description: "Absence end date. Format: yyyy-mm-dd"
+ example: '2020-01-31'
+ full_day:
+ type: boolean
+ example: false
+ description: Whether it's a full day absence or not, only required if the start_date and end_date are the same (one day absence at most)
+ start_time:
+ type: string
+ format: date
+ description: "Absence start time. Format: HH:ii and only required if the start_date and end_date are the same, and full_day is false (partial-day absence)"
+ example: '03:00'
+ end_time:
+ type: string
+ format: date
+ description: "Absence end time. Format: HH:ii and only required if the start_date and end_date are the same, and full_day is false (partial-day absence)"
+ example: '15:00'
+ half_day_start:
+ type: boolean
+ example: false
+ description: Whether the start date is a half-day off, only required if the start_date and end_date are not the same (more than one day absence)
+ half_day_end:
+ type: boolean
+ example: false
+ description: Whether the end date is a half-day off, only required if the start_date and end_date are not the same (more than one day absence)
+ comment:
+ type: string
+ example: Some Comment
+ description: Optional comment
+ skip_approval:
+ type: boolean
+ example: false
+ description: Optional, default value is true. If set to false, the approval status of the absence request will be "pending" if an approval rule is set for the absence type in Personio. The respective approval flow will be triggered.
+ required:
+ - employee_id
+ - absence_type_id
+ - start_date
+ - end_date
  AbsencePeriodsResponse:
  title: List All Absence Periods response
  type: object
@@ -4004,6 +4201,24 @@ components:
  attributes:
  $ref: "#/components/schemas/Absence"
 
+ HourlyAbsencePeriodResponse:
+ title: Absence Periods response
+ type: object
+ allOf:
+ - $ref: "#/components/schemas/Response"
+ - type: object
+ properties:
+ data:
+ type: object
+ required:
+ - type
+ - attributes
+ properties:
+ type:
+ example: AbsencePeriod
+ attributes:
+ $ref: "#/components/schemas/HourlyAbsence"
+
  Absence:
  type: object
  properties:
@@ -4127,6 +4342,9 @@ components:
  type: string
  format: uuid
  example: 61fe126b-a7b3-449a-b5ee-3865a6fcc546
+ name:
+ type: string
+ example: Absence Type Name
  AbsencePeriodBreakdown:
  type: object
  required: