openapi: 3.0.0
info:
  description: >-
    This API provides services to upload, manipulate and download Global Trade
    Item data in the CDQ Cloud
  version: '1'
  title: Product Identification API
servers:
  - description: Production
    url: https://api.cdq.com/product-identification/rest
    x-cdq-soap-url: https://api.corporate-data-league.ch/product-identification/soap/v1
security:
  - apiKey: []
tags:
  - name: Global Trade Items
    description: >-
      -> Covers several operations including the creation, reading, updating,
      and deletion of Global Trade Items, as well as the management of
      references between Global Trade Items and business partners. The endpoints
      under this tag are designed to handle data related to Global Trade Items,
      which are unique identifiers for products in the global marketplace.
paths:
  /globaltradeitems:
    get:
      tags:
        - Global Trade Items
      summary: List Global Trade Items
      description: >-
        Provide a list of Global Trade Items with optional filtering and
        pagination.
      parameters:
        - $ref: '#/components/parameters/startAfterQueryParam'
        - $ref: '#/components/parameters/limitQueryParam'
        - name: businessPartnerIds
          in: query
          required: false
          description: >
            Filter Global Trade Items by Business Partners ID that are
            referenced.
          schema:
            type: array
            description: List of Business Partner IDs.
            items:
              $ref: '#/components/schemas/BusinessPartnerId'
        - name: featuresOn
          in: query
          required: false
          description: >
            Features to be turned on:

            * `FETCH_BUSINESS_PARTNER_REFERENCES` - Includes
            businessPartnerReferences. By default, turned off.

            * `NUMBER_OF_TOTAL` - Allows switching fetching the total number of
            Global Trade Items to improve performance. By default turned off.
          schema:
            type: array
            description: List of features to be activated.
            items:
              $ref: '#/components/schemas/GlobalTradeItemsReadFeatureParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalTradeItemsPage'
          description: OK
    post:
      tags:
        - Global Trade Items
      summary: Create Global Trade Item
      description: Provide a new Global Trade Item with unique GTIN and name.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GlobalTradeItemCreate'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalTradeItemSearchResult'
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
  /globaltradeitems/{gtin}:
    parameters:
      - name: gtin
        description: Unique Global Trade Item Number.
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/Gtin'
          maxLength: 50
    patch:
      tags:
        - Global Trade Items
      summary: Update Global Trade Items
      description: Allows updating the Global Trade Item.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GlobalTradeItemUpdate'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalTradeItemUpdateResult'
          description: OK
    get:
      tags:
        - Global Trade Items
      summary: Read Global Trade Item
      description: Provide a single Global Trade Item with the given GTIN.
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalTradeItemReadResult'
          description: OK
  /globaltradeitems/delete:
    post:
      tags:
        - Global Trade Items
      summary: Delete Global Trade Items
      description: Delete multiple Global Trade Items by GTIN.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GlobalTradeItemDeletes'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalTradeItemDeleteResults'
          description: OK
  /globaltradeitems/{gtin}/businesspartnerreferences:
    parameters:
      - name: gtin
        description: Unique Global Trade Item Number.
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/Gtin'
          maxLength: 50
    post:
      tags:
        - Global Trade Items
      summary: Create Global Trade Item Reference
      description: Create a reference between Global Trade Item and Business Partner.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessPartnerReferenceCreates'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessPartnerReferenceCreateResults'
          description: OK
        '400':
          description: Bad Request
  /globaltradeitems/{gtin}/businesspartnerreferences/delete:
    parameters:
      - name: gtin
        description: Unique Global Trade Item Number.
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/Gtin'
          maxLength: 50
    post:
      tags:
        - Global Trade Items
      summary: Delete Global Trade Item References
      description: Delete references between Global Trade Item and Business Partner.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessPartnerReferenceDeletes'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessPartnerReferenceDeleteResults'
          description: OK
        '400':
          description: Bad Request
components:
  parameters:
    startAfterQueryParam:
      name: startAfter
      description: >
        Use nextStartAfter provided in the response of previous call as an
        indicator for a next page.
      in: query
      required: false
      schema:
        type: string
        example: NjI4ZGNkZjAzYjlkMjY4NjhlNjQxNDRm
    limitQueryParam:
      name: limit
      description: Number of items to be returned on the page.
      in: query
      required: false
      schema:
        type: integer
        format: int32
        minimum: 1
        default: 500
        example: '500'
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  schemas:
    GlobalTradeItemCreate:
      type: object
      description: >
        Typed string describing and identifying a resource. Custom information
        about the resource in the form of a tag.
      required:
        - gtin
        - name
      properties:
        gtin:
          $ref: '#/components/schemas/Gtin'
          maxLength: 50
        name:
          $ref: '#/components/schemas/ItemName'
    GlobalTradeItemUpdate:
      type: object
      description: Updates provided for a Global Trade Item.
      properties:
        name:
          $ref: '#/components/schemas/ItemName'
    GlobalTradeItemUpdateResult:
      type: object
      description: Result of the update operation.
      properties:
        globalTradeItem:
          $ref: '#/components/schemas/GlobalTradeItemUpdate'
        status:
          $ref: '#/components/schemas/GlobalTradeItemUpdateResultStatus'
    GlobalTradeItemUpdateResultStatus:
      type: string
      description: |
        Status of the update operation:
        * OK - the global trade item has been updated
        * NOT_FOUND - the global trade item is not found
      example: OK
    GlobalTradeItemReadResult:
      type: object
      description: Result of the read operation.
      properties:
        globalTradeItem:
          $ref: '#/components/schemas/GlobalTradeItemSearchResult'
        status:
          $ref: '#/components/schemas/GlobalTradeItemReadResultStatus'
    GlobalTradeItemReadResultStatus:
      type: string
      description: |
        Status of the read operation:
        * OK - the global trade item has been found
        * NOT_FOUND - the global trade item is not found
      example: OK
    GlobalTradeItemSearchResult:
      type: object
      description: An item or product.
      properties:
        gtin:
          $ref: '#/components/schemas/Gtin'
          maxLength: 50
        name:
          $ref: '#/components/schemas/ItemName'
        businessPartnerReferences:
          type: array
          description: List of Business Partners that are referenced.
          items:
            $ref: '#/components/schemas/BusinessPartnerReferenceSearchResult'
    BusinessPartnerReferenceSearchResult:
      type: object
      description: Reference between Global Trade Item and Business Partner.
      properties:
        storageId:
          $ref: '#/components/schemas/BusinessPartnerStorageId'
        dataSourceId:
          $ref: '#/components/schemas/BusinessPartnerStorageDataSourceId'
        businessPartnerId:
          $ref: '#/components/schemas/BusinessPartnerId'
        externalId:
          $ref: '#/components/schemas/BusinessPartnerExternalId'
    GlobalTradeItemsPage:
      type: object
      description: Page with listed Global Trade Items and pagination information.
      properties:
        total:
          $ref: '#/components/schemas/PageTotal'
        limit:
          $ref: '#/components/schemas/Limit'
        startAfter:
          $ref: '#/components/schemas/StartAfter'
        nextStartAfter:
          $ref: '#/components/schemas/NextStartAfter'
        values:
          type: array
          description: List of Global Trade Items.
          items:
            $ref: '#/components/schemas/GlobalTradeItemSearchResult'
    GlobalTradeItemDeletes:
      type: object
      description: Deletion of multiple Global Trade Items.
      required:
        - globalTradeItems
      properties:
        globalTradeItems:
          type: array
          description: List of Global Trade Items to be deleted.
          items:
            $ref: '#/components/schemas/GlobalTradeItemDelete'
          minItems: 1
    GlobalTradeItemDelete:
      type: object
      description: Deletion of a single Global Trade Item.
      required:
        - gtin
      properties:
        gtin:
          $ref: '#/components/schemas/Gtin'
          maxLength: 50
    GlobalTradeItemDeleteResults:
      type: object
      description: Result of the delete operation.
      properties:
        results:
          type: array
          description: List of Global Trade Items that have been deleted.
          items:
            $ref: '#/components/schemas/GlobalTradeItemDeleteResult'
    GlobalTradeItemDeleteResult:
      type: object
      description: Result of the delete operation.
      properties:
        globalTradeItem:
          $ref: '#/components/schemas/GlobalTradeItemDelete'
        status:
          $ref: '#/components/schemas/GlobalTradeItemDeleteResultStatus'
    GlobalTradeItemDeleteResultStatus:
      type: string
      description: |
        Status of the delete operation:
        * OK - the GlobalTradeItem has been deleted
        * NOT_FOUND - the GlobalTradeItem is not found
      example: OK
    GlobalTradeItemsReadFeatureParam:
      type: string
      description: Features to be used in the request.
      example: FETCH_BUSINESS_PARTNER_RELATIONS
      enum:
        - FETCH_BUSINESS_PARTNER_RELATIONS
        - NUMBER_OF_TOTAL
      x-enumDescriptions:
        FETCH_BUSINESS_PARTNER_RELATIONS: Includes businessPartnerReferences.
        NUMBER_OF_TOTAL: >-
          Allows switching fetching the total number of Global Trade Items to
          improve performance.
    BusinessPartnerReferenceCreates:
      type: object
      description: Reference between Global Trade Item and Business Partner.
      required:
        - businessPartnerReferences
      properties:
        businessPartnerReferences:
          type: array
          description: List of Business Partners to be referenced.
          maxItems: 30
          items:
            $ref: '#/components/schemas/BusinessPartnerReferenceCreate'
    BusinessPartnerReferenceCreate:
      type: object
      description: Reference between Global Trade Item and Business Partner.
      required:
        - storageId
        - businessPartnerId
        - dataSourceId
      properties:
        storageId:
          $ref: '#/components/schemas/BusinessPartnerStorageId'
          maxLength: 50
        dataSourceId:
          $ref: '#/components/schemas/BusinessPartnerStorageDataSourceId'
          maxLength: 50
        businessPartnerId:
          $ref: '#/components/schemas/BusinessPartnerId'
          maxLength: 50
        externalId:
          $ref: '#/components/schemas/BusinessPartnerExternalId'
          maxLength: 50
    BusinessPartnerReferenceCreateResults:
      type: object
      description: Result of the create operation.
      properties:
        results:
          type: array
          description: List of Business Partner References that have been created.
          items:
            $ref: '#/components/schemas/BusinessPartnerReferenceCreateResult'
    BusinessPartnerReferenceCreateResult:
      type: object
      description: Result of the create operation.
      properties:
        businessPartnerReference:
          $ref: '#/components/schemas/BusinessPartnerReferenceSearchResult'
        status:
          $ref: '#/components/schemas/BusinessPartnerReferenceCreateResultStatus'
    BusinessPartnerReferenceCreateResultStatus:
      type: string
      description: |
        Status of the create operation:
        * OK - the business partner reference has been created
        * DUPLICATE - the business partner reference already existed
      example: OK
    BusinessPartnerReferenceDeletes:
      type: object
      description: Deletion of multiple Business Partner References.
      required:
        - businessPartnerReferences
      properties:
        businessPartnerReferences:
          type: array
          description: List of Business Partner References to be deleted.
          maxItems: 30
          items:
            $ref: '#/components/schemas/BusinessPartnerReferenceDelete'
    BusinessPartnerReferenceDelete:
      type: object
      description: |
        Reference between Global Trade Item and Business Partner.
      required:
        - storageId
        - businessPartnerId
      properties:
        storageId:
          $ref: '#/components/schemas/BusinessPartnerStorageId'
        businessPartnerId:
          $ref: '#/components/schemas/BusinessPartnerId'
    BusinessPartnerReferenceDeleteResults:
      type: object
      description: Result of the delete operation.
      properties:
        results:
          type: array
          description: List of Business Partner References that have been deleted.
          items:
            $ref: '#/components/schemas/BusinessPartnerReferenceDeleteResult'
    BusinessPartnerReferenceDeleteResult:
      type: object
      description: Result of the delete operation.
      properties:
        businessPartnerReference:
          $ref: '#/components/schemas/BusinessPartnerReferenceDelete'
        status:
          $ref: '#/components/schemas/BusinessPartnerReferenceDeleteStatus'
    BusinessPartnerReferenceDeleteStatus:
      type: string
      description: |
        Status of the delete operation:
        * OK - the BusinessPartnerReference has been deleted
        * NOT_FOUND - the BusinessPartnerReference is not found
      example: OK
    BusinessPartnerId:
      type: string
      description: >-
        A CDQ ID identifies a business partner uniquely in the context of the
        Corporate Data League.
      example: 63e635235c06b7396330fe40
    PageTotal:
      description: Total number of items which can be paged.
      example: '67'
      type: integer
    Limit:
      type: integer
      description: Number of items per page.
      example: '100'
    StartAfter:
      type: string
      description: The ID which is used to read the page.
      example: '5712566172571652'
    NextStartAfter:
      type: string
      description: Provides a value to be used as a startAfter in next page request.
      example: '5712566172571652'
    Gtin:
      type: string
      description: A 13 digit Global Trade Item Number that uniquely identifies the item
      example: '5099206081901'
    ItemName:
      type: string
      description: Human readable name of the item.
      example: Business Partner Update Browser
    BusinessPartnerStorageId:
      type: string
      description: Unique identifier of the Storage.
      example: 72d6900fce6b326088f5d9d91049e3e6
    BusinessPartnerStorageDataSourceId:
      type: string
      description: Unique identifier for a Data Source of the Storage.
      example: 648824a691d8d2503d65103e
    BusinessPartnerExternalId:
      type: string
      description: >-
        Arbitrary identifier type to mark customer IDs that are "external" from
        CDQ's perspective. This is the identifier a customer provides to
        identify its records.
      example: The ID managed in the customer's SAP systems.
    ApiErrorTimestamp:
      type: string
      deprecated: true
      description: ISO 8601 representation of the timestamp.
      example: '2025-10-14T07:32:46Z'
    ApiErrorMessage:
      type: string
      deprecated: true
      description: Details about the error.
      example: This user is not allowed to access this service.
    HttpError:
      type: string
      description: RFC 7231 error which belongs to the status code.
      example: BAD_REQUEST
      deprecated: true
    HttpStatus:
      type: integer
      description: RFC 7231 status code for this error.
      example: '400'
      deprecated: true
    HttpPath:
      type: string
      description: Requested path which caused this error.
      example: /v2/businesspartners/lookup
    ApiError:
      type: object
      description: Detailed information about API errors.
      deprecated: true
      properties:
        timestamp:
          $ref: '#/components/schemas/ApiErrorTimestamp'
        message:
          $ref: '#/components/schemas/ApiErrorMessage'
        error:
          $ref: '#/components/schemas/HttpError'
        status:
          $ref: '#/components/schemas/HttpStatus'
        path:
          $ref: '#/components/schemas/HttpPath'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-KEY
