Inspectorio CUSTOMER DATA API

openapi: 3.2.0
info:
  title: Inspectorio Quality Risk Management CUSTOMER DATA API
  version: v1
servers:
- description: Production Environment
  url: https://sight.inspectorio.com
- description: Pre-Production Environment
  url: https://sight.pre.inspectorio.com
security:
- ApiKeyAuth: []
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:
  schemas:
    EntityType:
      type: string
      enum:
      - product
      - item
      - material
      - category
      description: The type of entity to be updated, unique with the provided custom identifier
    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
    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'
    ProductIntegrationErrorResponse:
      type: object
      description: Validation or client error (shape may include field keys or DRF `detail`).
      additionalProperties: true
    BomComponentFacilityIntegrationObject:
      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
        customId:
          type: string
          description: Custom ID of the facility
        address:
          type: string
          description: Address of the facility
        city:
          type: string
          description: City of the facility
        stateProvince:
          type: string
          description: State/Province of the facility
        postalZipCode:
          type: string
          description: Postal/Zip code of the facility
        country:
          type: string
          description: Country of the facility
        phone:
          type: string
          description: Phone of the facility
        contactName:
          type: string
          description: Contact name of the facility
        contactEmail:
          type: string
          description: Contact email of the facility
        contactPhone:
          type: string
          description: Contact phone of the facility
    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
            - 'null'
            description: Components of the BOM
            items:
              $ref: '#/components/schemas/BomComponentCreateObject'
            default: []
    Status:
      type: string
      enum:
      - active
      - inactive
    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'
    BomAttachmentIntegrationObject:
      type: object
      properties:
        fileName:
          type: string
          description: File name of the attachment
        fileUrl:
          type: string
          description: URL of the attachment
    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
    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`)
    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`)
    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
    ContributionRole:
      type: string
      enum:
      - provider
      - manufacturer
    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'
    ProductIntegrationLocalOrg:
      type: object
      properties:
        id:
          type:
          - integer
          - 'null'
        globalOrgId:
          type:
          - integer
          - 'null'
        customId:
          type:
          - string
          - 'null'
        name:
          type:
          - string
          - 'null'
    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'
    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
    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
    BomComponentEsgCreateObject:
      type: object
      properties:
        group:
          type:
          - string
          - 'null'
          description: Group of the ESG
        standard:
          type: string
          description: Standard of the ESG
        unitAmount:
          type:
          - number
          - 'null'
          description: Unit amount of the ESG
        amountUom:
          type:
          - string
          - 'null'
          description: amount uom of the ESG
      required:
      - standard
    ProductsIntegrationSuccessResponse:
      allOf:
      - $ref: '#/components/schemas/ProductsIntegrationBaseResponse'
      - type: object
        properties:
          action:
            $ref: '#/components/schemas/ResponseAction'
          synchronization:
            $ref: '#/components/schemas/Synchronization'
    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'
    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
        co

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