openapi: 3.1.0
info:
  title: COR Attachments Resource Allocation API
  description: The COR API lets you integrate with projectcor.com applications using simple HTTP methods, in either XML or JSON formats, making this an ideal API for developing integrations with other softwares, external clients or mobile applications
  version: 1.0.0
servers:
- url: https://api.projectcor.com/v1
  description: Production server
security:
- bearerAuth: []
tags:
- name: Resource Allocation
paths:
  /allocation/saveAllocation:
    post:
      tags:
      - Resource Allocation
      summary: Save Allocation
      description: "Creates a new resource allocation for a user on a project.\n\n**Request Body Requirements:**\nAll values in the object are required.\n\n**Known Errors:**\n- `InvalidAllocationError` — The allocation is invalid:\n  - Empty `allocatedHours` field\n  - The `from` date is greater than or equal to the `to` date\n  - The date range exceeds 12 months\n- `AllocationAlreadyExistInDatesRangeError` — An allocation already exists within the specified date range\n- `UserNotFoundError` — The specified user cannot be found\n- `UserNotHaveWorkDaysError` — The user does not have any work days configured\n- `ProjectNotFoundError` — The specified project cannot be found"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AllocationInput'
            example:
              userId: 1111
              companyId: 1111
              email: email@email.com
              resource:
                typeId: Project
                entityId: 1111
              from: '2024-06-01'
              to: '2024-10-31'
              assignedByUserId: 11111
              allocatedHours: 20
      responses:
        '200':
          description: Allocation saved successfully
        '400':
          description: Invalid allocation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllocationError'
              examples:
                invalid_allocation:
                  summary: Invalid allocation data
                  value:
                    error: InvalidAllocationError
                    message: Empty allocated hours field
                user_not_found:
                  summary: User not found
                  value:
                    error: UserNotFoundError
                    message: The specified user cannot be found
                allocation_exists:
                  summary: Allocation already exists
                  value:
                    error: AllocationAlreadyExistInDatesRangeError
                    message: An allocation already exists within the specified date range
  /allocation/updateAllocation:
    put:
      tags:
      - Resource Allocation
      summary: Update Allocation
      description: "Updates an existing resource allocation. Requires both the old allocation data and the new allocation data.\n\n**Known Errors:**\n- `InvalidAllocationError` — The new allocation is invalid:\n  - Empty `allocatedHours` field\n  - The `from` date is greater than or equal to the `to` date\n  - The date range exceeds 12 months\n- `AllocationNotFoundError` — The specified old allocation cannot be found\n- `AllocationAlreadyExistInDatesRangeError` — The new allocation already exists within the specified date range\n- `UserNotFoundError` — The specified user in new allocation cannot be found\n- `UserNotHaveWorkDaysError` — The user does not have any work days in the new allocation dates range\n- `ProjectNotFoundError` — The specified project in new allocation cannot be found\n\n**Note:** You can use this endpoint to change a project allocation, as long as there isn't an existing allocation for the same user in the target project for any date within the range of the new allocation."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AllocationUpdateInput'
            example:
              oldAllocation:
                userId: 1111
                companyId: 11
                resource:
                  entityId: 11111
                  typeId: Project
                from: '2024-01-01'
                to: '2024-03-31'
                assignedByUserId: 1111
                allocatedHours: 0
              newAllocation:
                userId: 1111
                companyId: 11
                resource:
                  entityId: 11111
                  typeId: Project
                from: '2024-01-01'
                to: '2024-03-31'
                assignedByUserId: 1111
                allocatedHours: 10
      responses:
        '200':
          description: Allocation updated successfully
        '400':
          description: Invalid allocation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllocationError'
              examples:
                allocation_not_found:
                  summary: Old allocation not found
                  value:
                    error: AllocationNotFoundError
                    message: The specified allocation cannot be found
  /allocation/removeAllocation:
    delete:
      tags:
      - Resource Allocation
      summary: Delete Allocation
      description: 'Removes an existing resource allocation.


        **Request Body Requirements:**

        All values in the object are required.


        **Known Errors:**

        - `AllocationNotFoundError` — The specified allocation cannot be found

        - `ProjectNotFoundError` — The specified project cannot be found


        Please ensure that your request is valid and all specified resources exist to avoid these errors.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AllocationInput'
            example:
              userId: 1111
              companyId: 111
              resource:
                typeId: Project
                entityId: 1111
              from: '2024-01-01'
              to: '2024-03-31'
              assignedByUserId: 11111
              allocatedHours: 20
      responses:
        '200':
          description: Allocation deleted successfully
        '400':
          description: Allocation not found error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllocationError'
              example:
                error: AllocationNotFoundError
                message: The specified allocation cannot be found
  /allocation/getAllocations/{projectId}:
    get:
      tags:
      - Resource Allocation
      summary: Get Allocations By Project
      description: Gets information about user allocations for a given project. Returns all users allocated to the project along with their allocation details and allocations in other projects.
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: integer
        description: Project ID to get allocations for
        example: 12345
      responses:
        '200':
          description: List of user allocations for the project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectAllocationsResponse'
              example:
                users:
                - userId: 1234
                  firstName: John
                  lastName: Doe
                  positionName: Developer
                  categoryName: Engineering
                  categoryId: '10'
                  picture: ''
                  userPositionId: '5'
                  companyId: 41195
                  hidden: false
                  isDeleted: false
                  labelsByCategory: []
                  createdAt: '2024-01-15T10:00:00'
                  allocations:
                  - primaryKey: '00000001'
                    from: '2024-06-01T00:00:00'
                    to: '2024-08-31T00:00:00'
                    allocatedHours: 20
                    capacity: 160
                    availabilityLeft: 140
                    createdAt: '2024-05-20T14:30:00'
                    allocationUserAnotherProjects:
                    - projectId: 5678
                      projectName: Project Alpha
                      clientName: Client ABC
                      allocatedHours: 15
                    - projectId: 5679
                      projectName: Project Beta
                      clientName: Client XYZ
                      allocatedHours: 5
                  totalAllocatedHours: 20
components:
  schemas:
    AllocationUpdateInput:
      type: object
      required:
      - oldAllocation
      - newAllocation
      properties:
        oldAllocation:
          $ref: '#/components/schemas/AllocationInput'
          description: The existing allocation to be updated
        newAllocation:
          $ref: '#/components/schemas/AllocationInput'
          description: The new allocation data
    AllocationResource:
      type: object
      required:
      - typeId
      - entityId
      properties:
        typeId:
          type: string
          enum:
          - Project
          description: Type of resource (currently only Project is supported)
        entityId:
          type: integer
          description: Project ID
    UserAllocation:
      type: object
      properties:
        primaryKey:
          type: string
          description: Unique identifier for the allocation
        from:
          type: string
          format: date-time
          description: Start date of the allocation
        to:
          type: string
          format: date-time
          description: End date of the allocation
        allocatedHours:
          type: number
          description: Number of hours allocated
        capacity:
          type: number
          description: Total capacity in hours
        availabilityLeft:
          type: number
          description: Remaining availability (can be negative if overallocated)
        createdAt:
          type: string
          format: date-time
          description: When the allocation was created
        allocationUserAnotherProjects:
          type: array
          description: Other project allocations for this user in the same period
          items:
            type: object
            properties:
              projectId:
                type: integer
                description: Project ID
              projectName:
                type: string
                description: Name of the project
              clientName:
                type: string
                description: Name of the client
              allocatedHours:
                type: number
                description: Hours allocated to this project
    ProjectAllocationsResponse:
      type: object
      properties:
        users:
          type: array
          description: List of users allocated to the project
          items:
            $ref: '#/components/schemas/AllocatedUser'
    AllocationInput:
      type: object
      required:
      - userId
      - companyId
      - resource
      - from
      - to
      - assignedByUserId
      - allocatedHours
      properties:
        userId:
          type: integer
          description: ID of the user being allocated
        companyId:
          type: integer
          description: Company ID
        email:
          type: string
          format: email
          description: User email (optional)
        resource:
          $ref: '#/components/schemas/AllocationResource'
        from:
          type: string
          format: date
          description: Start date (YYYY-MM-DD)
        to:
          type: string
          format: date
          description: End date (YYYY-MM-DD). Must be after 'from' date and within 12 months.
        assignedByUserId:
          type: integer
          description: ID of the user who assigned the allocation
        allocatedHours:
          type: number
          description: Number of hours allocated
    AllocationError:
      type: object
      properties:
        error:
          type: string
          description: Error type
          enum:
          - InvalidAllocationError
          - AllocationAlreadyExistInDatesRangeError
          - UserNotFoundError
          - UserNotHaveWorkDaysError
          - ProjectNotFoundError
          - AllocationNotFoundError
        message:
          type: string
          description: Error description
    AllocatedUser:
      type: object
      properties:
        userId:
          type: integer
          description: User ID
        firstName:
          type: string
          description: User's first name
        lastName:
          type: string
          description: User's last name
        positionName:
          type: string
          description: User's position name
        categoryName:
          type: string
          description: User's category name
        categoryId:
          type: string
          description: User's category ID
        picture:
          type: string
          description: URL to user's profile picture
        userPositionId:
          type: string
          description: User's position ID
        companyId:
          type: integer
          description: Company ID
        hidden:
          type: boolean
          description: Whether the user is hidden
        isDeleted:
          type: boolean
          description: Whether the user is deleted
        labelsByCategory:
          type: array
          description: Labels assigned to the user grouped by category
          items:
            type: object
        createdAt:
          type: string
          format: date-time
          description: When the user was created
        allocations:
          type: array
          description: User's allocations for this project
          items:
            $ref: '#/components/schemas/UserAllocation'
        totalAllocatedHours:
          type: number
          description: Total hours allocated to this user for the project
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    basicAuth:
      type: http
      scheme: basic