1WorldSync FetchProduct API

openapi: 3.0.1
info:
  title: 1WorldSync Content1 FetchProduct API
  description: "<div class=\"info_title\">1WorldSync Content1 API</div>\n<div class=\"info_description markdown\">\n<p>Content1 will provide access to accurate, trusted product data sourced directly from the Brand Owners through 1WorldSync’s APIs. This full set of product information is readily available to you through a set of web services, allowing you to get up-to-date, complete product information.</P>\n\nThe following APIs are available\n <ul>\n    <li><b>Product Count API</b> - Performs a search against the product data published in ContentNOW to find product count that meet the supplied criteria. You can user only four fields i.e. GLN, GTIN, Target Market and Last Modified Date to search data.</li>\n    <li><b>Product Fetch API</b> - Once a Product Search has been performed (and you have received a count), the full set of atrribute information on a given product can be retrieved using the Product Fetch API. This is a paginated API which means you need to mention the offset count and the page size. It is preferred that you make sequential calls. </li>         \n </ul>\n<p>This tool features a fully functional form which will call the Content1 API in real time. To unlock the API call, you must have your client secret key provided through <a href=https://developer.1worldsync.com>developer.1worldsync.com</a>. Enter that key in the top right of this page to unlock the API calls used below.</P>"
  contact:
    url: http://support.1worldsync.com
    email: 1ws-im-apps-build@syndigo.com
  version: V1
servers:
- url: https://content1-api.1worldsync.com
  description: Production Server
tags:
- name: FetchProduct
paths:
  /V1/product/count:
    post:
      tags:
      - FetchProduct
      summary: This method will return product count for a given search criteria.
      description: This method will return product count for a given search criteria.
      operationId: fetchItemCountByCriteria
      parameters:
      - name: appid
        in: header
        description: API User App Id
        required: true
        allowEmptyValue: false
        schema:
          type: string
        example: ''
      - name: hashcode
        in: header
        description: Hash of secret key, URL and timestamp
        required: true
        allowEmptyValue: false
        schema:
          type: string
        example: hashcode
      - name: timestamp
        in: query
        description: Current Timestamp in YYYY-MM-DDTHH:mm:ssZ format
        required: true
        allowEmptyValue: false
        schema:
          type: string
        example: '2023-02-28T13:37:59Z'
      - name: gln
        in: header
        description: Data requested for the GLNs (comma separated for multiple, no space required or Click the "Add Item" button)
        required: false
        allowEmptyValue: false
        schema:
          type: Array
        example: ''
      requestBody:
        description: Criteria JSON
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ItemFetchRequest'
        required: true
      responses:
        '500':
          description: when error occurred in processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemFetchError'
        '200':
          description: will return count of products on a given criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemCount'
        '401':
          description: For any Authorization, Authentication and validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemFetchError'
  /V1/product/fetch:
    post:
      tags:
      - FetchProduct
      summary: This method will return list of products for a given search criteria.
      description: This method will search for products on a given search criteria and will return data in paged way. Page size can be mentioned in the request parameter. Using of "searchAfter" in request body will give you next page data.
      operationId: fetchItemByCriteria
      parameters:
      - name: appid
        in: header
        description: API User App Id
        required: true
        allowEmptyValue: false
        schema:
          type: string
        example: ''
      - name: hashcode
        in: header
        description: Hash of secret key, URL and timestamp
        required: true
        allowEmptyValue: false
        schema:
          type: string
        example: hashcode
      - name: timestamp
        in: query
        description: Current Timestamp in YYYY-MM-DDTHH:mm:ssZ format
        required: true
        allowEmptyValue: false
        schema:
          type: string
        example: '2023-02-28T13:37:59Z'
      - name: pageSize
        in: query
        description: Page size, default to 1000
        required: true
        allowEmptyValue: false
        schema:
          maximum: 1000
          type: integer
        example: '1000'
      - name: gln
        in: header
        description: Data requested for the GLNs (comma separated for multiple, no space required or Click the "Add Item" button)
        required: false
        allowEmptyValue: false
        schema:
          type: Array
        example: ''
      requestBody:
        description: Criteria JSON
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ItemFetchRequest'
        required: true
      responses:
        '500':
          description: <p><ul><li>when page size is more then 1000</li><li>when error occurred in processing</li></ul></p>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemFetchError'
        '200':
          description: 'Will return list of products. '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemFetchResult'
        '204':
          description: When no products found.
        '401':
          description: For any Authorization, Authentication and validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemFetchError'
  /V1/product/hierarchy:
    post:
      tags:
      - FetchProduct
      summary: Fetch item hierarchy details.
      description: This method will return item hierarchy details based on a given search criteria and will return data with pagination. Page size can be mentioned in the "size" parameter. Using of "searchAfter" in request body loads next page.
      operationId: fetchHierarchiesByCriteria
      parameters:
      - name: appid
        in: header
        description: API User App Id
        required: true
        allowEmptyValue: false
        schema:
          type: string
        example: ''
      - name: hashcode
        in: header
        description: Hash of secret key, URL and timestamp
        required: true
        allowEmptyValue: false
        schema:
          type: string
        example: hashcode
      - name: timestamp
        in: query
        description: Current Timestamp in YYYY-MM-DDTHH:mm:ssZ format
        required: true
        allowEmptyValue: false
        schema:
          type: string
        example: '2023-02-28T13:37:59Z'
      - name: pageSize
        in: query
        description: Page size, default to 1000
        required: true
        allowEmptyValue: false
        schema:
          maximum: 1000
          type: integer
        example: '1000'
      - name: gln
        in: header
        description: Data requested for the GLNs (comma separated for multiple, no space required or Click the "Add Item" button)
        required: false
        allowEmptyValue: false
        schema:
          type: Array
        example: ''
      requestBody:
        description: Criteria JSON
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FetchHierarchyRequest'
        required: true
      responses:
        '500':
          description: <p><ul><li>Requested page size is grater than 1000</li><li>Internal error occured</li></ul></p>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemFetchError'
        '200':
          description: Returns item hierarchy details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HierarchyFetchResult'
        '401':
          description: For any Authorization, Authentication and validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemFetchError'
components:
  schemas:
    ItemFetchRequest:
      type: object
      properties:
        gtins:
          type: array
          items:
            type: string
        pullHierarchy:
          type: boolean
          description: Flag to indicate whether to include hierarchy in the response
          nullable: true
          example: false
        gtin:
          type: array
          description: Item GTIN array
          nullable: true
          example: []
          items:
            type: string
            description: Item GTIN array
            nullable: true
            example: '[]'
        ipGln:
          maxLength: 14
          minLength: 14
          type: string
          description: Information Provider GLN
          format: d{14}
          nullable: true
          example: 0838016005012
        targetMarket:
          maxLength: 3
          minLength: 1
          type: string
          description: Target Market
          nullable: true
          example: US
        lastModifiedDate:
          $ref: '#/components/schemas/LastModifiedDate'
        brandName:
          type: string
          description: Brand name (supports wildcard)
          nullable: true
          example: Brand Name
        productType:
          maxLength: 3
          minLength: 1
          type: string
          description: Product Type
          nullable: true
          example: EA
        isConsumerUnit:
          type: string
          description: Consumer Unit
          nullable: true
          example: 'false'
        gpcCode:
          type: string
          description: GPC code or name (supports wildcard)
          nullable: true
          example: '10000248'
        upcCode:
          type: string
          description: UPC code (supports wildcard)
          nullable: true
          example: '123456789128'
        sortFields:
          uniqueItems: true
          type: array
          description: Fields that will be sorted upon
          nullable: true
          example:
          - field: lastModifiedDate
            desc: 'true'
          - field: gtin
            desc: 'false'
          items:
            $ref: '#/components/schemas/SortField'
        fields:
          $ref: '#/components/schemas/FetchFields'
        searchAfter:
          type: array
          description: This field is used to fetch item in batch. To retrieve the next page of the items. You need to set searchAfter in search criteria from previous result.
          nullable: true
          example: []
          items:
            type: object
            description: This field is used to fetch item in batch. To retrieve the next page of the items. You need to set searchAfter in search criteria from previous result.
            nullable: true
            example: []
      description: Product search criteria object
    SortField:
      type: object
      properties:
        field:
          type: string
          description: 'Fields that will be sorted upon. Ex: gtin, informationProviderGLN and targetMarket etc.'
        desc:
          type: boolean
      description: Fields that will be sorted upon
      nullable: true
      example:
      - field: lastModifiedDate
        desc: 'true'
      - field: gtin
        desc: 'false'
    HierarchyFetchResult:
      type: object
      properties:
        hierarchies:
          type: array
          description: Hierarchies of the item.
          items:
            $ref: '#/components/schemas/HierarchyDetails'
        message:
          type: string
          description: Response message.
          example: To retrieve the next page of products, pick what you have received in searchAfter and set it in next request.
        searchAfter:
          type: array
          description: This value is used to fetch next page of hierarchies.
          example: '[00637827872406,"US"]'
          items:
            type: object
            description: This value is used to fetch next page of hierarchies.
            example: '[00637827872406,"US"]'
      description: Hierarchy search result
    ItemFetchError:
      properties:
        requestId:
          type: string
          description: An unique id generated at server end to track processing of this request
          example: '12222'
        code:
          type: string
          description: Error code
          example: '[INTERNAL_SERVER_ERROR | REQUIRED_HEADER_APPID_MISSING]'
        reason:
          type: string
          description: Error reason in human readable form
          example: appId is missing
      description: Error response object. you will receive this object when there is an error in server side in processing
      example: '{"requestId":1334426,"code":"REQUIRED_HEADER_APPID_MISSING", "reason":"appId is missing in header" }'
    LastModifiedDate:
      type: object
      properties:
        from:
          $ref: '#/components/schemas/DateField'
        to:
          $ref: '#/components/schemas/DateField'
      description: Item last modified date
      nullable: true
      example:
        from:
          date: '2023-01-01'
          op: GTE
        to:
          date: '2023-01-31'
          op: LTE
    FetchHierarchyRequest:
      type: object
      properties:
        gtin:
          type: array
          description: Item GTIN array
          nullable: true
          example: []
          items:
            type: string
            description: Item GTIN array
            nullable: true
            example: '[]'
        ipGln:
          maxLength: 14
          minLength: 14
          type: string
          description: Information Provider GLN
          format: d{14}
          nullable: true
          example: 0838016005012
        lastModifiedDate:
          $ref: '#/components/schemas/LastModifiedDate'
        sortFields:
          uniqueItems: true
          type: array
          description: Fields that will be sorted upon
          nullable: true
          example:
          - field: lastModifiedDate
            desc: 'true'
          - field: gtin
            desc: 'false'
          items:
            $ref: '#/components/schemas/SortField'
        searchAfter:
          type: array
          description: This field is used to fetch item in batch. To retrieve the next page of the items. You need to set searchAfter in search criteria from previous result.
          nullable: true
          example: []
          items:
            type: object
            description: This field is used to fetch item in batch. To retrieve the next page of the items. You need to set searchAfter in search criteria from previous result.
            nullable: true
            example: []
      description: Hierarchy search criteria
    ItemFetchResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        totalPages:
          type: integer
          description: This field used to set total page number for given search criteria.
          format: int64
        currentPage:
          type: integer
          description: This field used to set pagination page number.
          format: int64
        message:
          type: string
          description: This field used to set any warning message.
          example: Warning message
        totalCount:
          type: integer
          description: This field used to set total count.
          format: int64
        searchAfter:
          type: array
          description: This field is used to fetch item in batch. To retrieve the next page of the items. You need to set it in search criteria.
          example: '[00637827872406,"US"]'
          items:
            type: object
            description: This field is used to fetch item in batch. To retrieve the next page of the items. You need to set it in search criteria.
            example: '[00637827872406,"US"]'
      description: Product search result
    ItemFetchHierarchy:
      type: object
      properties:
        parentGtin:
          type: string
        gtin:
          type: string
        quantity:
          type: string
        children:
          type: array
          items:
            $ref: '#/components/schemas/ItemFetchHierarchy'
      description: Hierarchy mapping
    Item:
      type: object
      properties:
        objId:
          type: string
          description: Elasticsearch objId
          example: '2334322'
        gln:
          type: string
          description: Item shared with gln
          example: 0838016005012
        dataPoolType:
          type: string
          description: Item belongs to which data pool
          example: SDP
        item:
          type: object
          additionalProperties:
            type: object
            description: Item as map
            example: {}
          description: Item as map
          example: {}
    ItemCount:
      type: object
      properties:
        count:
          type: integer
          description: This is total product count for given criteria.
          format: int64
          example: 1000
      description: Product count result
    DateField:
      type: object
      properties:
        date:
          type: string
          description: Date
          example: '2022-01-15T00:00:00'
        op:
          type: string
          description: Date comparison operation type (ENUM)
          example: GT
          enum:
          - GT
          - GTE
          - LT
          - LTE
          - EQ
      description: LastModifiedDate To
    FetchFields:
      type: object
      properties:
        include:
          uniqueItems: true
          type: array
          description: 'To retrieve subset of attributes from item. Ex: ["gtin","informationProviderGLN","targetMarket","lastModifiedDate","brandName","gpcCategory","externalFileLink"]'
          example: []
          items:
            type: string
            description: 'To retrieve subset of attributes from item. Ex: ["gtin","informationProviderGLN","targetMarket","lastModifiedDate","brandName","gpcCategory","externalFileLink"]'
            example: '[]'
        exclude:
          uniqueItems: true
          type: array
          description: 'To abandon some of attributes from item. Ex: ["*.gln","externalFileLink.authorizedRecipients"]'
          example: []
          items:
            type: string
            description: 'To abandon some of attributes from item. Ex: ["*.gln","externalFileLink.authorizedRecipients"]'
            example: '[]'
      description: Fields to be include or exclude in result; By default all fields will be included
      nullable: true
    HierarchyDetails:
      type: object
      properties:
        gtin:
          type: string
          description: Item GTIN.
          example: 03007687545289
        informationProviderGLN:
          type: string
          description: Information provider GLN.
        targetMarket:
          type: string
          description: Target market.
        hierarchy:
          type: array
          description: Item hierarchy list.
          items:
            $ref: '#/components/schemas/ItemFetchHierarchy'
      description: Item hierarchy details