openapi: 3.0.0 info: title: Workorder Portal API description: API for managing workorder portal operations version: 1.0.0 servers: - url: https://api.repzo.me/v1 description: Production server security: - ApiKeyAuth: [] tags: - name: Workorder Portal description: Workorder portal management operations paths: /workorder-portal: get: tags: - Workorder Portal summary: Get workorder portal entries description: Retrieve workorder portal entries with optional filtering and pagination parameters: - name: page in: query description: Page number for pagination required: false schema: type: integer minimum: 1 default: 1 - name: per_page in: query description: Number of items per page required: false schema: type: integer minimum: 1 maximum: 100 default: 25 - name: sort in: query description: Sort field required: false schema: type: string - name: company_namespace in: query description: Company namespace for filtering required: false schema: type: array items: type: string - name: status in: query description: Filter by status required: false schema: type: string enum: ["pending", "in_progress", "completed", "cancelled"] - name: workorder in: query description: Filter by workorder ID required: false schema: type: string - name: client in: query description: Filter by client ID required: false schema: type: string - name: _id in: query description: Filter by ID required: false schema: type: array items: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean example: true data: type: array items: $ref: "#/components/schemas/WorkorderPortal" paging: $ref: "#/components/schemas/PagingInfo" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalServerError" post: tags: - Workorder Portal summary: Create a new workorder portal entry description: Create a new workorder portal entry requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateWorkorderPortalRequest" responses: "201": description: Workorder portal entry created successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: $ref: "#/components/schemas/WorkorderPortal" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "422": $ref: "#/components/responses/ValidationError" "500": $ref: "#/components/responses/InternalServerError" /workorder-portal/{id}: get: tags: - Workorder Portal summary: Get workorder portal entry by ID description: Retrieve a specific workorder portal entry by its ID parameters: - name: id in: path required: true description: Workorder portal entry ID schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean example: true data: $ref: "#/components/schemas/WorkorderPortal" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalServerError" patch: tags: - Workorder Portal summary: Update workorder portal entry description: Update an existing workorder portal entry parameters: - name: id in: path required: true description: Workorder portal entry ID schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateWorkorderPortalRequest" responses: "200": description: Workorder portal entry updated successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: $ref: "#/components/schemas/WorkorderPortal" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/ValidationError" "500": $ref: "#/components/responses/InternalServerError" delete: tags: - Workorder Portal summary: Delete workorder portal entry description: Delete a workorder portal entry by ID parameters: - name: id in: path required: true description: Workorder portal entry ID schema: type: string responses: "200": description: Workorder portal entry deleted successfully content: application/json: schema: type: object properties: success: type: boolean example: true "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalServerError" /workorder-portal/{id}/status: patch: tags: - Workorder Portal summary: Update workorder portal status description: Update the status of a workorder portal entry parameters: - name: id in: path required: true description: Workorder portal entry ID schema: type: string requestBody: required: true content: application/json: schema: type: object properties: status: type: string enum: ["pending", "in_progress", "completed", "cancelled"] description: New status notes: type: string description: Status update notes required: - status responses: "200": description: Status updated successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: $ref: "#/components/schemas/WorkorderPortal" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalServerError" components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: "Use format: Bearer {api_key}" schemas: WorkorderPortal: type: object properties: _id: type: string description: Unique identifier example: "507f1f77bcf86cd799439011" workorder: type: string description: Workorder ID reference example: "507f1f77bcf86cd799439012" client: type: string description: Client ID reference example: "507f1f77bcf86cd799439013" portal_access_code: type: string description: Unique access code for portal example: "WOP-2024-001" status: type: string description: Current status enum: ["pending", "in_progress", "completed", "cancelled"] example: "pending" access_level: type: string description: Level of access granted enum: ["view_only", "comment", "full_access"] example: "comment" allowed_actions: type: array items: type: string enum: ["view", "comment", "upload_files", "approve", "reject"] description: Actions allowed for this portal access expiry_date: type: string format: date-time description: When portal access expires last_accessed: type: string format: date-time description: Last time portal was accessed access_count: type: integer description: Number of times portal was accessed example: 5 notifications: type: object properties: email_enabled: type: boolean description: Whether email notifications are enabled sms_enabled: type: boolean description: Whether SMS notifications are enabled notification_events: type: array items: type: string enum: ["status_change", "new_comment", "deadline_approaching"] portal_settings: type: object properties: show_progress: type: boolean description: Whether to show progress information allow_comments: type: boolean description: Whether commenting is allowed require_authentication: type: boolean description: Whether authentication is required custom_branding: type: object properties: logo_url: type: string description: URL to custom logo brand_color: type: string description: Brand color hex code example: "#FF5733" company_name: type: string description: Company name to display company_namespace: type: array items: type: string description: Company namespace disabled: type: boolean description: Whether portal access is disabled example: false createdAt: type: string format: date-time description: Creation timestamp modifiedAt: type: string format: date-time description: Last modification timestamp SVClient: type: integer description: Client version __v: type: integer description: Document version required: - workorder - client - portal_access_code - status CreateWorkorderPortalRequest: type: object properties: workorder: type: string description: Workorder ID reference example: "507f1f77bcf86cd799439012" client: type: string description: Client ID reference example: "507f1f77bcf86cd799439013" access_level: type: string description: Level of access granted enum: ["view_only", "comment", "full_access"] default: "view_only" allowed_actions: type: array items: type: string enum: ["view", "comment", "upload_files", "approve", "reject"] description: Actions allowed for this portal access default: ["view"] expiry_date: type: string format: date-time description: When portal access expires notifications: type: object properties: email_enabled: type: boolean default: true sms_enabled: type: boolean default: false notification_events: type: array items: type: string enum: ["status_change", "new_comment", "deadline_approaching"] portal_settings: type: object properties: show_progress: type: boolean default: true allow_comments: type: boolean default: true require_authentication: type: boolean default: false custom_branding: type: object properties: logo_url: type: string brand_color: type: string company_name: type: string company_namespace: type: array items: type: string description: Company namespace disabled: type: boolean description: Whether portal access is disabled default: false required: - workorder - client UpdateWorkorderPortalRequest: type: object properties: status: type: string description: Current status enum: ["pending", "in_progress", "completed", "cancelled"] access_level: type: string description: Level of access granted enum: ["view_only", "comment", "full_access"] allowed_actions: type: array items: type: string enum: ["view", "comment", "upload_files", "approve", "reject"] expiry_date: type: string format: date-time description: When portal access expires notifications: type: object properties: email_enabled: type: boolean sms_enabled: type: boolean notification_events: type: array items: type: string enum: ["status_change", "new_comment", "deadline_approaching"] portal_settings: type: object properties: show_progress: type: boolean allow_comments: type: boolean require_authentication: type: boolean custom_branding: type: object properties: logo_url: type: string brand_color: type: string company_name: type: string company_namespace: type: array items: type: string description: Company namespace disabled: type: boolean description: Whether portal access is disabled PagingInfo: type: object properties: total: type: integer description: Total number of items page: type: integer description: Current page number per_page: type: integer description: Items per page pages: type: integer description: Total number of pages responses: BadRequest: description: Bad request content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: "Invalid request parameters" Unauthorized: description: Unauthorized content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: "Authentication required" Forbidden: description: Forbidden content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: "Insufficient permissions" NotFound: description: Resource not found content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: "Resource not found" ValidationError: description: Validation error content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: "Validation failed" InternalServerError: description: Internal server error content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: "Internal server error"