Inspectorio CUSTOMER DATA API

openapi: 3.0.3
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
                    nullable: true
                  previous:
                    type: string
                    nullable: true
        '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:
  schemas:
    StatusCode:
      type: integer
      enum:
      - 200
      - 202
      - 400
      - 500
    ItemSetReference:
      type: object
      required:
      - custom_id
      properties:
        custom_id:
          $ref: '#/components/schemas/CustomId'
          description: The unique custom identifier of the product in your system
        quantity:
          type: integer
          default: 1
    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.'
    ProductIntegrationLocalOrg:
      type: object
      properties:
        id:
          type: integer
          nullable: true
        globalOrgId:
          type: integer
          nullable: true
        customId:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
    ProductsIntegrationSuccessResponse:
      allOf:
      - $ref: '#/components/schemas/ProductsIntegrationBaseResponse'
      - type: object
        properties:
          action:
            $ref: '#/components/schemas/ResponseAction'
          synchronization:
            $ref: '#/components/schemas/Synchronization'
    BomComponentSupplierIntegrationObject:
      type: object
      properties:
        name:
          type: string
          description: Name of the supplier
        customId:
          type: string
          description: Custom ID of the supplier
        address:
          type: string
          description: Address of the supplier
        city:
          type: string
          description: City of the supplier
        stateProvince:
          type: string
          description: State/Province of the supplier
        postalZipCode:
          type: string
          description: Postal/Zip code of the supplier
        country:
          type: string
          description: Country of the supplier
        phone:
          type: string
          description: Phone of the supplier
        contactName:
          type: string
          description: Contact name of the supplier
        contactEmail:
          type: string
          description: Contact email of the supplier
        contactPhone:
          type: string
          description: Contact phone of the supplier
    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`)
    schemas-Product:
      allOf:
      - $ref: '#/components/schemas/BaseProduct'
      - type: object
        properties:
          entity_type:
            type: string
            enum:
            - product
          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`)
    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'
    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
    BaseProduct:
      allOf:
      - $ref: '#/components/schemas/CustomRevision'
      - $ref: '#/components/schemas/ForceUpdate'
      type: object
      required:
      - custom_id
      - custom_revision
      - entity_type
      - status
      properties:
        domain:
          $ref: '#/components/schemas/Domain'
        custom_id:
          $ref: '#/components/schemas/CustomId'
          description: Unique Custom identifier for products in your system
        entity_type:
          $ref: '#/components/schemas/EntityType'
        name:
          type: string
          maxLength: 255
          description: Name of the product
        description:
          type: string
          description: Description of the product
        status:
          $ref: '#/components/schemas/Status'
          description: Status of the product
        domain_attributes:
          type: object
          description: Domain attributes for products natively supported by our Platform
          additionalProperties:
            type: string
          example:
            color: Blue
            size: XL
            origin_country:
            - US
            - CN
        additional_attributes:
          type: object
          description: Additional attributes for products which are not natively supported by our Platform which are configurable by the client
          additionalProperties:
            type: string
          example:
            business_unit: US
        contributions:
          type: array
          items:
            $ref: '#/components/schemas/ItemContribution'
    ProductIntegrationStyleRef:
      type: object
      description: Present for items when the item has a parent style product.
      properties:
        styleUuid:
          type: string
          nullable: true
        styleId:
          type: string
          nullable: true
        styleName:
          type: string
          nullable: true
    BomUpdateRequest:
      type: object
      required:
      - name
      - active
      allOf:
      - $ref: '#/components/schemas/BomCommonFields'
      - type: object
        properties:
          active:
            type: boolean
            description: Status of the BOM (required for updates)
          components:
            type: array
            description: Components of the BOM
            items:
              $ref: '#/components/schemas/BomComponentCreateObject'
            nullable: true
            default: []
    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
    BomComponentSupplierCreateObject:
      type: object
      properties:
        name:
          type: string
          maxLength: 255
          description: Name of the supplier
        customId:
          type: string
          description: Custom ID of the supplier
          nullable: true
        address:
          type: string
          description: Address of the supplier
          nullable: true
        city:
          type: string
          description: City of the supplier
          nullable: true
        stateProvince:
          type: string
          description: State/Province of the supplier
          nullable: true
        postalZipCode:
          type: string
          description: Postal/Zip code of the supplier
          nullable: true
        country:
          type: string
          description: Country of the supplier
          nullable: true
        phone:
          type: string
          description: Phone of the supplier
          nullable: true
        contactName:
          type: string
          description: Contact name of the supplier
          nullable: true
        contactEmail:
          type: string
          description: Contact email of the supplier
          nullable: true
        contactPhone:
          type: string
          description: Contact phone of the supplier
          nullable: true
      required:
      - name
    BomComponentIntegrationObject:
      type: object
      properties:
        customId:
          type: string
          description: Custom ID of the component
        name:
          type: string
          description: Name of the component
        description:
          type: string
          description: Description of the component
        supplierComponentId:
          type: string
          description: Supplier component ID
        group:
          type: string
          description: Group of the component
        unitYield:
          type: number
          description: Unit yield of the component
        yieldUom:
          type: string
          description: Yield unit of the component
        unitWeight:
          type: number
          description: Unit weight of the component
        weightUom:
          type: string
          description: Weight unit of the component
        unitCost:
          type: number
          description: Unit cost of the component
        totalYield:
          type: number
          description: Total yield of the component
        totalWeight:
          type: number
          description: Total weight of the component
        costCurrency:
          type: string
          description: Cost currency of the component
        countryOfOrigin:
          type: array
          description: ISO 3166-1 alpha-2 codes for country of origin.
          items:
            type: string
            minLength: 2
            maxLength: 2
          example:
          - VN
          - US
        attribute:
          type: array
          description: 'Attribute labels (e.g. sustainability tags). Typical values match BOM form tagbox choices:

            Organic, Recycled, Sustainable.

            '
          items:
            type: string
            maxLength: 255
          example:
          - Organic
          - Recycled
        supplier:
          $ref: '#/components/schemas/BomComponentSupplierIntegrationObject'
        facilities:
          type: array
          description: Facilities of the component
          items:
            $ref: '#/components/schemas/BomComponentFacilityIntegrationObject'
        bom:
          $ref: '#/components/schemas/BomDetailIntegrationObject'
    EntityType:
      type: string
      enum:
      - product
      - item
      - material
      - category
      description: The type of entity to be updated, unique with the provided custom identifier
    ItemContribution:
      type: object
      required:
      - role
      - org_custom_id
      properties:
        role:
          $ref: '#/components/schemas/ContributionRole'
          description: This will be pre-defined by Inspectorio in the 1st phase. "manufacturer" role will only have "read" permission to access the items' attributes / properties.
        org_custom_id:
          $ref: '#/components/schemas/CustomId'
          example: S208
          description: Local Organization ID or BP ID / Vendor ID of the item's provider (Vendor/Supplier)
        product_custom_id:
          nullable: true
          $ref: '#/components/schemas/CustomId'
          description: (Optional) The item ID from Vendor/Supplier's internal system if available (e.g. vendor/supplier article number)
    ProductIntegrationCategory:
      type: object
      properties:
        taxonomy:
          type: string
          nullable: true
        levelCustomId:
          type: string
          nullable: true
        levelIdentifier:
          type: string
          nullable: true
        customId:
          type: string
        name:
          type: string
        businessId:
          type: string
        customIdentifierId:
          type: string
          nullable: true
    ContributionRole:
      type: string
      enum:
      - provider
      - manufacturer
    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
    BomCommonFields:
      type: object
      properties:
        name:
          type: string
          maxLength: 255
          description: Name of the BOM
        description:
          type: string
          maxLength: 5000
          description: Description of the BOM
        poNumber:
          type: string
          maxLength: 255
          description: PO Number (custom ID) of the PO that BOM is attached to (if available)
        contributions:
          type: array
          description: List of contributions to associate with the BOM
          items:
            $ref: '#/components/schemas/BomContributionRequest'
    BomComponentFacilityCreateObject:
      type: object
      properties:
        name:
          type: string
          description: Name of the facility
        capabilities:
          type: array
          description: Capabilities of the facility
          items:
            type: string
            description: Capability of the facility
            nullable: true
          nullable: true
        customId:
          type: string
          description: Custom ID of the facility
          nullable: true
        address:
          type: string
          description: Address of the facility
          nullable: true
        city:
          type: string
          description: City of the facility
          nullable: true
        stateProvince:
          type: string
          description: State/Province of the facility
          nullable: true
        postalZipCode:
          type: string
          description: Postal/Zip code of the facility
          nullable: true
        country:
          type: string
          description: Country of the facility
          nullable: true
        phone:
          type: string
          description: Phone of the facility
          nullable: true
        contactName:
          type: string
          description: Contact name of the facility
          nullable: true
        contactEmail:
          type: string
          description: Contact email of the facility
          nullable: true
        contactPhone:
          type: string
          description: Contact phone of the facility
          nullable: true
      required:
      - name
    Material:
      allOf:
      - $ref: '#/components/schemas/BaseProduct'
      - type: object
        properties:
          entity_type:
            type: string
            enum:
            - material
          categories:
            type: array
            items:
              $ref: '#/components/schemas/MaterialCategory'
            description: The lowest level reference to the hierarchies used to categorize the product. Only one value accepted per taxonomy (`taxonomy_category_id`)
    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'
    BomComponentCreateObject:
      type: object
      properties:
        customId:
          type: string
          maxLength: 255
          description: Custom ID of the component
          nullable: true
        supplierComponentId:
          type: string
          maxLength: 255
          description: Supplier component ID
          nullable: true
        name:
          type: string
          maxLength: 255
          description: Name of the component
        description:
          type: string
          maxLength: 2000
          description: Description of the component
          nul

# --- 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