Inspectorio CUSTOMER DATA API

openapi: 3.2.0
info:
  title: File Management ANALYTICS CUSTOMER DATA API
  version: v3
servers:
- description: Production Environment
  url: https://files-integration.inspectorio.com
- description: Pre-Production Environment
  url: https://files-integration.pre.inspectorio.com
tags:
- name: CUSTOMER DATA
paths:
  /api/v1/customer-data/products:
    put:
      summary: Create or Update (Upsert) products, items and materials
      description: This endpoint allows you to create or update products, items, materials and item sets in your Data Set in Inspectorio Platform. Take special attention on the constraints documented about `force_update`and API Rate Limits in our 429 Response Headers.
      operationId: upsertItems
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                oneOf:
                - title: Product
                  $ref: '#/components/schemas/schemas-Product'
                - title: Item
                  $ref: '#/components/schemas/schemas-Item'
                - title: Material
                  $ref: '#/components/schemas/Material'
                - title: Item Set
                  $ref: '#/components/schemas/ItemSet'
      responses:
        '207':
          description: Multi-Status
          content:
            application/json:
              schema:
                type: array
                items:
                  oneOf:
                  - title: Successful Product Response
                    $ref: '#/components/schemas/ProductsIntegrationSuccessResponse'
                  - title: Error Product Response
                    $ref: '#/components/schemas/ProductsIntegrationErrorResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '429':
          description: Too Many Requests
          headers:
            RateLimit-Reset:
              description: The number of seconds to wait before making a new request.
              schema:
                type: integer
            RateLimit-Remaining:
              description: The number of requests remaining in the current rate limit window.
              schema:
                type: integer
            RateLimit-Limit:
              description: The maximum number of requests that can be made in a given amount of time.
              schema:
                type: integer
            Retry-After:
              description: The number of seconds to wait before making a new request.
              schema:
                type: integer
      tags:
      - CUSTOMER DATA
  /api/v1/customer-data/synchronization/{entity_type}/{id}:
    get:
      summary: Get synchronization status
      operationId: getSynchronization
      parameters:
      - $ref: '#/components/parameters/EntityType'
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Synchronization'
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
      tags:
      - CUSTOMER DATA
  /api/v1/customer-data/boms:
    post:
      summary: Create a new BOM
      operationId: createBom
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BomCreateRequest'
      responses:
        '204':
          description: BOM created successfully
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BomErrorResponse'
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
      tags:
      - CUSTOMER DATA
  /api/v1/customer-data/{entity_type}/{entity_custom_id}/boms:
    get:
      summary: List all BOMs for an entity
      operationId: listBoms
      parameters:
      - $ref: '#/components/parameters/parameters-EntityType'
      - name: entity_custom_id
        in: path
        required: true
        schema:
          type: string
        description: The custom ID of the entity that the BOM is attached to
      responses:
        '200':
          description: List of BOMs
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/BomDetailIntegrationObject'
                  count:
                    type: integer
                  next:
                    type:
                    - string
                    - 'null'
                  previous:
                    type:
                    - string
                    - 'null'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BomErrorResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: Not found.
        '500':
          description: Internal Server Error
      tags:
      - CUSTOMER DATA
  /api/v1/customer-data/{entity_type}/{entity_custom_id}/boms/{bom_custom_id}:
    put:
      summary: Update an existing BOM
      operationId: updateBom
      parameters:
      - $ref: '#/components/parameters/parameters-EntityType'
      - name: entity_custom_id
        in: path
        required: true
        schema:
          type: string
        description: The custom ID of the entity that the BOM is attached to
      - name: bom_custom_id
        in: path
        required: true
        schema:
          type: string
        description: The custom ID of the BOM itself
      - $ref: '#/components/parameters/PoNumber'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BomUpdateRequest'
      responses:
        '204':
          description: BOM updated successfully
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BomErrorResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: Not found.
        '500':
          description: Internal Server Error
      tags:
      - CUSTOMER DATA
    get:
      summary: Get BOM details
      operationId: getBomDetails
      parameters:
      - $ref: '#/components/parameters/parameters-EntityType'
      - name: entity_custom_id
        in: path
        required: true
        schema:
          type: string
        description: The custom ID of the entity that the BOM is attached to
      - name: bom_custom_id
        in: path
        required: true
        schema:
          type: string
        description: The custom ID of the BOM itself
      - $ref: '#/components/parameters/PoNumber'
      responses:
        '200':
          description: BOM details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BomDetailIntegrationObject'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BomErrorResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: Not found.
        '500':
          description: Internal Server Error
      tags:
      - CUSTOMER DATA
    delete:
      summary: Delete a BOM
      operationId: deleteBom
      parameters:
      - $ref: '#/components/parameters/parameters-EntityType'
      - name: entity_custom_id
        in: path
        required: true
        schema:
          type: string
        description: The custom ID of the entity that the BOM is attached to
      - name: bom_custom_id
        in: path
        required: true
        schema:
          type: string
        description: The custom ID of the BOM itself
      - $ref: '#/components/parameters/PoNumber'
      responses:
        '204':
          description: BOM deleted successfully
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BomErrorResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: Not found.
        '500':
          description: Internal Server Error
      tags:
      - CUSTOMER DATA
  /api/v1/customer-data/{entity_type}:
    get:
      summary: List products, items, or materials
      operationId: listProductIntegration
      parameters:
      - $ref: '#/components/parameters/components-parameters-EntityType'
      - $ref: '#/components/parameters/DataProviderCustomId'
      - $ref: '#/components/parameters/ProductIntegrationLimit'
      - $ref: '#/components/parameters/ProductIntegrationOffset'
      - $ref: '#/components/parameters/ProductIntegrationCreatedFrom'
      - $ref: '#/components/parameters/ProductIntegrationCreatedTo'
      - $ref: '#/components/parameters/ProductIntegrationUpdatedFrom'
      - $ref: '#/components/parameters/ProductIntegrationUpdatedTo'
      - $ref: '#/components/parameters/ProductIntegrationStatusFilter'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductIntegrationListResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductIntegrationErrorResponse'
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
      tags:
      - CUSTOMER DATA
  /api/v1/customer-data/{entity_type}/{custom_id}:
    get:
      summary: Get a product, item, or material by custom ID
      operationId: getProductIntegrationDetail
      parameters:
      - $ref: '#/components/parameters/components-parameters-EntityType'
      - $ref: '#/components/parameters/CustomId'
      - $ref: '#/components/parameters/DataProviderCustomId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductIntegrationDetail'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductIntegrationErrorResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
      tags:
      - CUSTOMER DATA
components:
  parameters:
    parameters-EntityType:
      name: entity_type
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/schemas-EntityType'
    CustomId:
      name: custom_id
      in: path
      required: true
      schema:
        type: string
    DataProviderCustomId:
      name: dataProviderCustomId
      in: query
      required: false
      description: 'Optional Local org custom id whose global organization is used

        as the data scope for the lookup. When omitted, the authenticated organization is used.

        '
      schema:
        type: string
    ProductIntegrationUpdatedFrom:
      name: updatedFrom
      in: query
      required: false
      description: Lower bound (inclusive) on `updatedAt`, ISO 8601 datetime.
      schema:
        type: string
        format: date-time
        example: '2024-06-01T00:00:00+00:00'
    ProductIntegrationOffset:
      name: offset
      in: query
      required: false
      description: Number of records to skip before returning results.
      schema:
        type: integer
        minimum: 0
        default: 0
    ProductIntegrationUpdatedTo:
      name: updatedTo
      in: query
      required: false
      description: Upper bound (inclusive) on `updatedAt`, ISO 8601 datetime.
      schema:
        type: string
        format: date-time
        example: '2024-12-31T23:59:59+00:00'
    PoNumber:
      name: poNumber
      in: query
      required: false
      schema:
        type: string
      description: Optional Purchase Order number to use when filtering BOMs. Use this when multiple BOMs exist with the same custom ID but different POs.
    components-parameters-EntityType:
      name: entity_type
      in: path
      required: true
      schema:
        type: string
        enum:
        - product
        - item
        - material
    ProductIntegrationLimit:
      name: limit
      in: query
      required: false
      description: Page size; default 10.
      schema:
        type: integer
        minimum: 1
        maximum: 50
        default: 10
    ProductIntegrationStatusFilter:
      name: status
      in: query
      required: false
      description: Filter by lifecycle status.
      schema:
        type: string
        enum:
        - active
        - inactive
    ProductIntegrationCreatedTo:
      name: createdTo
      in: query
      required: false
      description: Upper bound (inclusive) on `createdAt`, ISO 8601 datetime.
      schema:
        type: string
        format: date-time
        example: '2024-12-31T23:59:59+00:00'
    EntityType:
      name: entity_type
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/EntityType'
    ProductIntegrationCreatedFrom:
      name: createdFrom
      in: query
      required: false
      description: Lower bound (inclusive) on `createdAt`, ISO 8601 datetime.
      schema:
        type: string
        format: date-time
        example: '2024-06-01T00:00:00+00:00'
  schemas:
    ContributionRole:
      type: string
      enum:
      - provider
      - manufacturer
    BomErrorResponse:
      type: object
      properties:
        customId:
          type: array
          items:
            type: string
          description: Error messages for custom ID field
          example:
          - BOM with custom_id 'BOM-001' already exists for this product and purchase order
        name:
          type: array
          items:
            type: string
          description: Error messages for name field
          example:
          - BOM with name 'Manufacturing BOM for Winter Line' already exists for this product and purchase order
        active:
          type: array
          items:
            type: string
          description: Error messages for active field
          example:
          - This field is required.
        productType:
          type: array
          items:
            type: string
          description: Error messages for product type field
          example:
          - This field is required.
        productCustomId:
          type: array
          items:
            type: string
          description: Error messages for product custom ID field
          example:
          - This field is required.
        contributions:
          type: array
          items:
            type: object
            properties:
              role:
                type: array
                items:
                  type: string
              orgCustomId:
                type: array
                items:
                  type: string
          example:
          - role:
            - This field is required.
            orgCustomId:
            - This field is required.
        orgCustomId:
          type: array
          items:
            type: string
          description: Error messages for local org custom ID
          example:
          - Local organization with custom ID 'non_existent_org' not found
    MaterialCategory:
      type: object
      required:
      - taxonomy_custom_id
      - custom_id
      properties:
        taxonomy_custom_id:
          type: string
          description: Custom Identifier of the Hierarchy for which you want to set a category
          enum:
          - material
        custom_id:
          type: string
          description: Custom Identifier of the Category within the Hierarchy
          example: 540.120884014
    BomIntegrationComponentAttributeValue:
      type: string
      description: Component sustainability attribute (typical BOM form tagbox choices).
      enum:
      - Organic
      - Recycled
      - Sustainable
    CustomId:
      type: string
      maxLength: 128
      description: Custom identifier for the entity provided
    ProductIntegrationOrg:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        customId:
          type: string
        type:
          type: string
    BomAttachmentIntegrationObject:
      type: object
      properties:
        fileName:
          type: string
          description: File name of the attachment
        fileUrl:
          type: string
          description: URL of the attachment
    BomComponentCreateObject:
      type: object
      properties:
        customId:
          type:
          - string
          - 'null'
          maxLength: 255
          description: Custom ID of the component
        supplierComponentId:
          type:
          - string
          - 'null'
          maxLength: 255
          description: Supplier component ID
        name:
          type: string
          maxLength: 255
          description: Name of the component
        description:
          type:
          - string
          - 'null'
          maxLength: 2000
          description: Description of the component
        productType:
          type: string
          description: Product type of the component
          enum:
          - product
          - item
          - material
        group:
          type:
          - string
          - 'null'
          maxLength: 255
          description: Group of the component
        unitYield:
          type:
          - number
          - 'null'
          description: Unit yield of the component
        yieldUom:
          type:
          - string
          - 'null'
          maxLength: 50
          description: Yield unit of the component
        unitWeight:
          type:
          - number
          - 'null'
          description: Unit weight of the component
        weightUom:
          type:
          - string
          - 'null'
          maxLength: 255
          description: Weight unit of the component
        unitCost:
          type:
          - number
          - 'null'
          description: Unit cost of the component
        costCurrency:
          type:
          - string
          - 'null'
          maxLength: 50
          description: Cost currency of the component
        totalYield:
          type:
          - number
          - 'null'
          description: Total yield of the component
        totalWeight:
          type:
          - number
          - 'null'
          description: Total weight of the component
        countryOfOrigin:
          type:
          - array
          - 'null'
          description: Optional. ISO 3166-1 alpha-2 country codes.
          items:
            type: string
            minLength: 2
            maxLength: 2
          example:
          - VN
          - US
        attribute:
          type:
          - array
          - 'null'
          description: 'Optional. Component attribute tags. Each entry must be one of the integration enum values

            (aligned with common BOM form `component_attribute` choices).

            '
          items:
            $ref: '#/components/schemas/BomIntegrationComponentAttributeValue'
          example:
          - Organic
          - Recycled
        supplier:
          $ref: '#/components/schemas/BomComponentSupplierCreateObject'
        facilities:
          type:
          - array
          - 'null'
          description: Facilities of the component
          items:
            $ref: '#/components/schemas/BomComponentFacilityCreateObject'
        esgs:
          type:
          - array
          - 'null'
          description: ESGs of the component
          items:
            $ref: '#/components/schemas/BomComponentEsgCreateObject'
        bom:
          type:
          - object
          - 'null'
          properties:
            components:
              type: array
              items:
                $ref: '#/components/schemas/BomComponentCreateObject'
      required:
      - name
      - productType
    Synchronization:
      allOf:
      - $ref: '#/components/schemas/CustomRevision'
      type: object
      properties:
        entity_type:
          $ref: '#/components/schemas/EntityType'
        last_update_source:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        status:
          $ref: '#/components/schemas/Status'
    ForceUpdate:
      type: object
      properties:
        force_update:
          type:
          - boolean
          - 'null'
          description: Force update defines whether the data should be updated even in case the last update source happened by user action in Inspectorio Platform
    ProductIntegrationDetail:
      type: object
      properties:
        name:
          type: string
        customId:
          type: string
        entityType:
          type: string
          enum:
          - pdt
          - itm
          - mat
          description: Internal entity type code.
        description:
          type: string
        categories:
          type: array
          items:
            $ref: '#/components/schemas/ProductIntegrationCategory'
        ownerOrg:
          $ref: '#/components/schemas/ProductIntegrationOrg'
        creatorOrg:
          allOf:
          - $ref: '#/components/schemas/ProductIntegrationOrg'
        lastUpdateSource:
          type: string
        createdAt:
          type: string
          example: '2024-06-01T14:30:05Z'
        updatedAt:
          type: string
          example: '2024-06-01T14:30:05Z'
        status:
          type: string
          enum:
          - active
          - inactive
        style:
          $ref: '#/components/schemas/ProductIntegrationStyleRef'
        productId:
          type: string
        revisionId:
          type: integer
        isSet:
          type: boolean
        set:
          type: array
          items:
            $ref: '#/components/schemas/ProductIntegrationSetElement'
        domainAttributes:
          type: object
          additionalProperties: true
        additionalAttributes:
          type: object
          additionalProperties: true
        suppliers:
          type: array
          items:
            $ref: '#/components/schemas/ProductIntegrationLocalOrg'
        factories:
          type: array
          items:
            $ref: '#/components/schemas/ProductIntegrationLocalOrg'
    BomDetailIntegrationObject:
      type: object
      properties:
        customId:
          type: string
          description: Custom ID of the BOM
        name:
          type: string
          description: Name of the BOM
        description:
          type: string
          description: Description of the BOM
        enabled:
          type: boolean
          description: Is the BOM active
        createdAt:
          type: string
          description: Created at date of the BOM
          format: date-time
        productType:
          type: string
          description: Product type of the BOM
        productCustomId:
          type: string
          description: Custom ID of the product (item/style)
        poNumber:
          type: string
          description: Purchase order number of the BOM
        attachments:
          type: array
          description: Attachments of the BOM
          items:
            $ref: '#/components/schemas/BomAttachmentIntegrationObject'
        contributions:
          type: array
          description: Contributors of the BOM
          items:
            $ref: '#/components/schemas/BomContributionIntegrationObject'
        components:
          type: array
          description: Components of the BOM
          items:
            $ref: '#/components/schemas/BomComponentIntegrationObject'
        customFields:
          type: object
          description: 'Custom fields defined in the BOM Form with API Integration Keys configured.

            Keys are the user-defined API Integration Keys (apiIntegrationKey or apiIntegrationKey1).

            Values can be strings, numbers, booleans, arrays, or nested objects depending on the field type.

            This field is only present when at least one field has an API Integration Key configured.

            System ID fields (bom_id, component_id, supplier_id, etc.) are preserved with their original names for row identification.

            '
          additionalProperties: true
          example:
            bom_id: BOM-001
            bom_description_custom: Custom description
            components:
            - supplier_component_id: COMP-001
              component_name_api: Fabric A
              suppliers_custom:
              - supplier_id: SUP-001
                supplier_address_custom: 123 Main St
    schemas-Item:
      allOf:
      - $ref: '#/components/schemas/BaseProduct'
      - type: object
        required:
        - parent_custom_id
        properties:
          entity_type:
            type: string
            enum:
            - item
          parent_custom_id:
            $ref: '#/components/schemas/CustomId'
            description: The unique custom identifier of the parent product in your system
          categories:
            type: array
            items:
              $ref: '#/components/schemas/schemas-ProductCategory'
            description: The lowest level reference to the hierarchies used to categorize the product. Only one value accepted per taxonomy (`taxonomy_category_id`)
    ProductsIntegrationErrorResponse:
      allOf:
      - $ref: '#/components/schemas/ProductsIntegrationBaseResponse'
      - type: object
        properties:
          errors:
            type: array
            items:
              type: string
            example:
            - 'custom_revision: This field is required'
            - 'custom_id: Invalid format'
            - 'status: "INVALID" is not a valid choice.'
    ItemSet:
      allOf:
      - $ref: '#/components/schemas/BaseProduct'
      - type: object
        required:
        - set
        properties:
          entity_type:
            type: string
            enum:
            - item
          categories:
            type: array
            items:
              $ref: '#/components/schemas/schemas-ProductCategory'
            description: The lowest level reference to the hierarchies used to categorize the product. Only one value accepted per taxonomy (`taxonomy_category_id`)
          set:
            type: object
            required:
            - entity_type
            - elements
            properties:
              entity_type:
                type: string
                enum:
                - product
                - item
                - material
              elements:
                type: array
                items:
                  $ref: '#/components/schemas/ItemSetReference'
    schemas-ProductCategory:
      type: object
      required:
      - taxonomy_custom_id
      - custom_id
      properties:
        taxonomy_custom_id:
          type: string
          description: Custom Identifier of the Hierarchy for which you want to set a category
          enum:
          - product
          - merchandise
          - brand
        custom_id:
          type: string
          description: Custom Identifier of the Category within the Hierarchy
          example: 540.120884014
    BomComponentSupplierCreateObject:
      type: object
      properties:
        name:
          type: string
          maxLength: 255
          description: Name of the supplier
        customId:
          type:
          - string
          - 'null'
          description: Custom ID of the supplier
        address:
          type:
          - string
          - 'null'
          description: Address of the supplier
        city:
          type:
          - string
          - 'null'
          description: City of the supplier
        stateProvince:
          type:
          - string
          - 'null'
          description: State/Province of the supplier
        postalZipCode:
          type:
          - string
          - 'null'
          description: Postal/Zip code of the supplier
        country:
          type:
          - string
          - 'null'
          description: Country of the supplier
        phone:
          type:
          - string
          - 'null'
          description: Phone of the supplier
        contactName:
          type:
          - string
          - 'null'
          description: Contact name of the supplier
        contactEmail:
          type:
          - string
          - 'null'
          description: Contact email of the supplier
        contactPhone:
          type:
          - string
          - 'null'
          description: Contact phone of the supplier
      required:
      - name
    Domain:
      type: string
      default: apparel
      enum:
      - apparel
    StatusCode:
      type: integer
      enum:
      - 200
      - 202
      - 400
      - 500
    ProductsIntegrationBaseResponse:
      type: object
      properties:
        custom_id:
          $ref: '#/components/schemas/CustomId'
        status_code:
          $ref: '#/components/schemas/StatusCode'
    ProductIntegrationLocalOrg:
      type: object
      properties:
        id:
          type:
          - integer
          - 'null'
        globalOrgId:
          type:
          - integer
          - 'null'
        customId:
          type:
          - string
          - 'null'
        name:
          type:
          - string
          - 'null'
    ProductIntegrationCategory:
      type: object
      properties:
        taxonomy:
          type:
          - string
          - 'null'
        levelCustomId:
          type:
          - string
          - 'null'
        levelIdentifier:
          type:
          - string
          - 'null'
        customId:
          type: string
        name:
          type: string
        businessId:
          type: string
        customIdentifierId:
          type:
          - string
          - 'null'
    ProductIntegrationListResponse:
      type: object
      description: Paginated list of products, items, or materials.
      properties:
        code:
          type: integer
          example: 200
        status:
          type: string
          example: success
        count:
          type: integer
          description: Total number of records matching the query.
        next:
          type:
          - string
          - 'null'
          description: URL of the next page, if any.
        previous:
          type:
          - string
          - 'null'
          description: URL of the previous page, if any.
        results:
          type: array
          items:
            $ref: '#/components/schemas/ProductIntegrationDetail'
    ProductIntegrationSetElement:
      type: object
      properties:
        styleUuid:
          type:
          - string
          - 'null'
        s

# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/inspectorio/refs/heads/main/openapi/inspectorio-customer-data-api-openapi.yml