Phasio Manufacturer Part Specification Controller API

openapi: 3.2.0
info:
  title: Phasio Manufacturer Part Specification Controller API
  description: This is the API documentation for the Phasio application.
  version: '1.0'
servers:
- url: https://m-api.eu.phas.io
  description: Generated server url
security:
- Phasio API Bearer Token: []
tags:
- name: Manufacturer Part Specification Controller
  description: Endpoints for managing part specifications and customer article references
paths:
  /api/manufacturer/v1/part-specification:
    get:
      tags:
      - Manufacturer Part Specification Controller
      summary: Get part specifications with filtering
      description: Retrieves a paginated list of part specifications with optional filtering and search
      operationId: get_1
      parameters:
      - name: filter
        in: query
        description: filter specification
        required: true
        schema:
          type: string
      - name: page
        in: query
        description: Zero-based page index (0..N)
        required: false
        schema:
          type: integer
          default: 0
          minimum: 0
      - name: size
        in: query
        description: The size of the page to be returned
        required: false
        schema:
          type: integer
          default: 20
          minimum: 1
      - name: sort
        in: query
        description: 'Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.'
        required: false
        schema:
          type: array
          default:
          - createdAt,DESC
          items:
            type: string
      - name: search
        in: query
        description: Optional search term
        required: false
        schema:
          type: string
      - name: customerOrganisationId
        in: query
        description: Optional customer organisation. Restricts results to specifications whose part revision is claimed by that customer organisation.
        required: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Successfully retrieved part specifications
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Paginated'
        '400':
          description: 'Invalid filter specification (error code: INVALID_FILTER)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
    post:
      tags:
      - Manufacturer Part Specification Controller
      summary: Create a part specification
      description: Creates a part specification from a part revision and a set of manufacturing parameters. If a part specification with the same manufacturing parameters already exists for the part revision, it is returned instead of creating a duplicate.
      operationId: create_1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePartSpecificationDto'
        required: true
      responses:
        '200':
          description: Part specification created or existing part specification returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartSpecificationDto'
        '400':
          description: 'Post-processing selection is invalid (error codes: POST_PROCESSING_MATERIAL_INCOMPATIBLE, POST_PROCESSING_MUTUALLY_EXCLUSIVE)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized - operator not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: 'A referenced entity was not found (error codes: PART_REVISION_NOT_FOUND, PROCESS_PRICES_NOT_FOUND, MATERIAL_NOT_FOUND, COLOR_NOT_FOUND, INFILL_NOT_FOUND, PRECISION_PRICES_NOT_FOUND, POST_PROCESSING_NOT_FOUND)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/manufacturer/v1/part-specification/bulk:
    post:
      tags:
      - Manufacturer Part Specification Controller
      summary: Get part specifications by IDs
      description: Retrieves part specifications by a list of unique identifiers
      operationId: getByIds
      requestBody:
        content:
          application/json:
            schema:
              type: array
              description: Set of part specification IDs to retrieve
              items:
                type: string
                format: uuid
              uniqueItems: true
        required: true
      responses:
        '200':
          description: Part specifications retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PartSpecificationDto'
        '401':
          description: Unauthorized - operator not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/manufacturer/v1/part-specification/{id}:
    get:
      tags:
      - Manufacturer Part Specification Controller
      summary: Get part specification by ID
      description: Retrieves a specific part specification by its unique identifier
      operationId: getById_3
      parameters:
      - name: id
        in: path
        description: ID of the part specification to retrieve
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Part specification found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartSpecificationDto'
        '401':
          description: Unauthorized - operator not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: 'Part specification not found (error code: PART_SPECIFICATION_NOT_FOUND)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/manufacturer/v1/part-specification/{id}/derived-routing:
    get:
      tags:
      - Manufacturer Part Specification Controller
      summary: Preview the system-derived routing for a part specification
      description: Returns the ordered operations a new work order would snapshot when the specification has no designated default routing template. Read-only — nothing is materialized; may be empty when the process and post-processings define no operations.
      operationId: getDerivedRouting
      parameters:
      - name: id
        in: path
        description: ID of the part specification to derive a routing for
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Derived routing retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DerivedRoutingStepDto'
        '401':
          description: Unauthorized - operator not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: 'Part specification not found (error code: PART_SPECIFICATION_NOT_FOUND)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/manufacturer/v1/part-specification/part-revision/{partRevisionId}:
    get:
      tags:
      - Manufacturer Part Specification Controller
      summary: Get part specifications by part revision
      description: Retrieves all part specifications associated with a specific part revision
      operationId: getByPartRevision
      parameters:
      - name: partRevisionId
        in: path
        description: ID of the part revision
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Part specifications retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PartSpecificationDto'
        '401':
          description: Unauthorized - operator not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/manufacturer/v1/part-specification/customer-reference:
    get:
      tags:
      - Manufacturer Part Specification Controller
      summary: Find part specifications by customer reference
      description: Searches for part specifications matching a specific customer reference string
      operationId: getCustomerReference
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LookupString'
        required: true
      responses:
        '200':
          description: Part specifications retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PartSpecificationDto'
        '401':
          description: Unauthorized - operator not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/manufacturer/v1/part-specification/customer-organisation/{customerOrganisationId}:
    get:
      tags:
      - Manufacturer Part Specification Controller
      summary: Get part specifications by customer organization
      description: Retrieves all part specifications associated with a specific customer organization
      operationId: getByCustomerOrganisation
      parameters:
      - name: customerOrganisationId
        in: path
        description: ID of the customer organization
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Part specifications retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PartSpecificationDto'
        '401':
          description: Unauthorized - operator not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
components:
  schemas:
    DerivedRoutingStepDto:
      type: object
      properties:
        operationId:
          type: string
          format: uuid
        operationName:
          type: string
        sequence:
          type: integer
          format: int32
      required:
      - operationId
      - sequence
    PartSpecificationDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        partRevisionId:
          type: string
          format: uuid
        partRevisionName:
          type: string
        units:
          type: string
          enum:
          - CENTIMETERS
          - MILLIMETERS
          - METRES
          - INCHES
          - FEET
        processPricesId:
          type: string
          format: uuid
        materialId:
          type: integer
          format: int64
        colorId:
          type: integer
          format: int64
        precisionId:
          type: integer
          format: int64
        infillId:
          type: integer
          format: int64
        postProcessingIds:
          type: array
          items:
            type: integer
            format: int64
        customerReferences:
          type: array
          items:
            $ref: '#/components/schemas/CustomerArticleReferenceDto'
        createdAt:
          type: string
          format: date-time
        lastUpdated:
          type: string
          format: date-time
        constraints:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/ConstraintDto'
            - $ref: '#/components/schemas/FixedOrientationConstraintDto'
        weight:
          type: number
      required:
      - createdAt
      - customerReferences
      - id
      - lastUpdated
      - materialId
      - partRevisionId
      - partRevisionName
      - postProcessingIds
      - units
      - weight
    Paginated:
      type: object
      properties:
        content:
          type: array
          items: {}
        totalElements:
          type: integer
        totalPages:
          type: integer
        pageNumber:
          type: integer
        pageSize:
          type: integer
        isEmpty:
          type: boolean
        isFirst:
          type: boolean
        isLast:
          type: boolean
      required:
      - content
      - isEmpty
      - isFirst
      - isLast
      - pageNumber
      - pageSize
      - totalElements
      - totalPages
    CustomerArticleReferenceDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        customerOrganisationId:
          type: integer
          format: int64
        customerOrganisationName:
          type: string
        reference:
          type: string
        pricingTiers:
          type: array
          items:
            $ref: '#/components/schemas/CustomerArticleReferencePricingTierDto'
        showInCatalog:
          type: boolean
      required:
      - customerOrganisationId
      - pricingTiers
      - reference
    FixedOrientationConstraintDto:
      allOf:
      - $ref: '#/components/schemas/ConstraintDto'
      - type: object
        properties:
          rotationMatrix:
            type: array
            items:
              type: array
              items:
                type: number
      required:
      - constraintType
      - createdAt
      - id
      - partSpecificationId
      - rotationMatrix
      - updatedAt
    LookupString:
      type: object
      description: Reference string to search for
      properties:
        value:
          type: string
      required:
      - value
    ConstraintDto:
      type: object
      discriminator:
        propertyName: constraintType
      properties:
        id:
          type: string
          format: uuid
        constraintType:
          type: string
        partSpecificationId:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
      - constraintType
      - createdAt
      - id
      - partSpecificationId
      - updatedAt
    CustomerArticleReferencePricingTierDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        quantity:
          type: integer
          format: int32
        price:
          type: number
      required:
      - price
      - quantity
    CreatePartSpecificationDto:
      type: object
      description: Manufacturing parameters of the part specification
      properties:
        partRevisionId:
          type: string
          format: uuid
          description: ID of the part revision the specification is for
        processPricesId:
          type: string
          format: uuid
          description: ID of the process prices (technology) to manufacture the part with
        materialId:
          type: integer
          format: int64
          description: ID of the material to manufacture the part with
        units:
          type: string
          description: Measurement units of the part revision geometry
          enum:
          - CENTIMETERS
          - MILLIMETERS
          - METRES
          - INCHES
          - FEET
        colorId:
          type: integer
          format: int64
          description: Optional ID of the color
        infillId:
          type: integer
          format: int64
          description: Optional ID of the infill
        precisionId:
          type: integer
          format: int64
          description: Optional ID of the precision prices
        postProcessingIds:
          type: array
          description: Optional IDs of the post-processings to apply
          items:
            type: integer
            format: int64
      required:
      - materialId
      - partRevisionId
      - postProcessingIds
      - processPricesId
      - units
    ApiError:
      type: object
      additionalProperties: true
      description: Stable error contract. `error` is a SCREAMING_SNAKE code that clients match on; `message` is a human-readable sentence. Some errors add extra string fields (for example organisationId).
      properties:
        error:
          type: string
          example: ORDER_NOT_FOUND
        message:
          type: string
          example: Order not found
      required:
      - error
      - message
  securitySchemes:
    Phasio_API_Bearer_Token:
      type: http
      name: Authorization
      in: header
      scheme: bearer
      bearerFormat: JWT