Ankorstore Catalog Exchange API

openapi: 3.1.0
info:
  version: 1.2.2-oas3.1
  title: Ankorstore Stock Tracking and Logistics Applications Catalog Exchange API
  summary: API specification for the Ankorstore Stock Tracking and Logistics system
  description: Ankorstore Stock Tracking and Logistics (ASTRAL) API specification
  contact:
    name: Ankorstore
    url: https://www.ankorstore.com
    email: api@ankorstore.com
  license:
    url: https://creativecommons.org/publicdomain/zero/1.0/
    name: CC0 1.0 Universal
servers:
- url: http://www.ankorlocal.com:8000
  description: Local Development Server
- url: https://www.preprod.ankorstore.com
  description: Staging Environment
- url: https://www.ankorstore.com
  description: Prod Environment
tags:
- name: Catalog Exchange
paths:
  /api/v1/catalog/exchange/error-reports:
    post:
      summary: Request an error report for a PIM import job
      operationId: catalog-exchange-error-reports-create
      description: 'Triggers the asynchronous generation of an XLSX error report listing the failed items of a given PIM

        import job. Failed cells are highlighted and carry the validation message as a cell comment. Items whose

        failure is technical (PIM-side operational error) are included in the file but not highlighted, so the

        brand can simply re-upload them.


        The operation is idempotent per PIM import job: a second call for the same `pim_import_job_id` returns

        the existing report instead of creating a new one.

        '
      tags:
      - Catalog Exchange
      requestBody:
        required: true
        description: Request body to create an error report for a given PIM import job.
        content:
          application/vnd.api+json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  type: object
                  required:
                  - type
                  - attributes
                  properties:
                    type:
                      type: string
                      enum:
                      - catalog-exchange-error-report
                    attributes:
                      type: object
                      required:
                      - pim_import_job_id
                      properties:
                        pim_import_job_id:
                          type: string
                          format: uuid
                          description: Identifier of the PIM import job to build the error report from.
      responses:
        '200':
          description: Single error report
          content: &id001
            application/vnd.api+json:
              schema:
                type: object
                required:
                - data
                - jsonapi
                properties:
                  jsonapi:
                    description: An object describing the server's implementation
                    type: object
                    properties: &id002
                      version:
                        type: string
                      meta:
                        description: Non-standard meta-information that can not be represented as an attribute or relationship.
                        type: object
                        additionalProperties: true
                    additionalProperties: false
                  data:
                    type: object
                    properties:
                      type:
                        type: string
                        description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)'
                      id:
                        type: string
                        description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)'
                        format: uuid
                      attributes:
                        type: object
                        properties:
                          pimImportJobId:
                            type: string
                            format: uuid
                            description: Identifier of the PIM import job whose failed items are reported.
                          brandUuid:
                            type: string
                            format: uuid
                            description: Owning brand UUID.
                          status:
                            type: string
                            description: Lifecycle status of the error report.
                            enum:
                            - created
                            - started
                            - completed
                            - failed
                          filename:
                            type: string
                            description: Name the file will be served as.
                          failureReason:
                            type:
                            - 'null'
                            - string
                            description: Reason of failure, set only when the status is `failed`.
                          createdAt:
                            type: string
                            format: date-time
                          startedAt:
                            type:
                            - 'null'
                            - string
                            format: date-time
                          completedAt:
                            type:
                            - 'null'
                            - string
                            format: date-time
                          expiresAt:
                            type:
                            - 'null'
                            - string
                            format: date-time
                            description: Moment after which the file is no longer downloadable. Reports are retained for 30 days after completion.
                          downloadUrl:
                            type:
                            - 'null'
                            - string
                            format: uri
                            description: Present when the report is completed and not expired.
                        required:
                        - pimImportJobId
                        - brandUuid
                        - status
                        - filename
                        - createdAt
                    required:
                    - type
                    - id
                    - attributes
        '201':
          description: Single error report
          content: *id001
        '401':
          description: Unauthorized
          content:
            application/vnd.api+json:
              schema:
                type: object
                additionalProperties: false
                properties: &id003
                  errors:
                    type: array
                    uniqueItems: true
                    items:
                      type: object
                      properties:
                        code:
                          description: An application-specific error code, expressed as a string value.
                          type: string
                        detail:
                          description: A human-readable explanation specific to this occurrence of the problem.
                          type: string
                        status:
                          description: The HTTP status code applicable to this problem, expressed as a string value.
                          type: string
                        title:
                          description: The HTTP status code description applicable to this problem
                          type: string
                        source:
                          type: object
                          description: Optional object pointing towards the problematic field
                          properties:
                            pointer:
                              type: string
                              description: The field key
                        meta:
                          description: Non-standard meta-information that can not be represented as an attribute or relationship.
                          type: object
                          additionalProperties: true
                      additionalProperties: false
                  jsonapi:
                    description: An object describing the server's implementation
                    type: object
                    properties: *id002
                    additionalProperties: false
                required: &id004
                - errors
              example:
                jsonapi:
                  version: '1.0'
                errors:
                - detail: Unauthorized
                  status: '401'
        '403':
          description: '[Forbidden](https://jsonapi.org/format/#crud-creating-responses-403)'
          content:
            application/vnd.api+json:
              schema:
                type: object
                additionalProperties: false
                properties: *id003
                required: *id004
              example:
                jsonapi:
                  version: '1.0'
                errors:
                - detail: Forbidden
                  status: '403'
        '406':
          description: Not Acceptable
          content:
            application/vnd.api+json:
              schema:
                type: object
                additionalProperties: false
                properties: *id003
                required: *id004
              example:
                jsonapi:
                  version: '1.0'
                errors:
                - detail: Not Acceptable
                  status: '406'
        '415':
          description: Unsupported Media Type
          content:
            application/vnd.api+json:
              schema:
                type: object
                additionalProperties: false
                properties: *id003
                required: *id004
              example:
                jsonapi:
                  version: '1.0'
                errors:
                - detail: Unsupported Media Type
                  status: '415'
        '422':
          description: 'Unprocessable Entity : Data provided are invalid'
          content:
            application/vnd.api+json:
              schema:
                type: object
                additionalProperties: false
                properties: *id003
                required: *id004
              example:
                jsonapi:
                  version: string
                errors:
                - detail: The field is required.
                  source:
                    pointer: data.attributes.field
                  status: '422'
                  title: Unprocessable Content
        '500':
          description: '[Server Error](https://jsonapi.org/format/#errors)'
          content:
            application/vnd.api+json:
              schema:
                type: object
                additionalProperties: false
                properties: *id003
                required: *id004
              example:
                jsonapi:
                  version: '1.0'
                errors:
                - detail: Server Error
                  status: '500'
    get:
      summary: List error reports
      operationId: catalog-exchange-error-reports-list
      description: Returns the error reports owned by the authenticated brand, sorted by descending creation date.
      tags:
      - Catalog Exchange
      responses:
        '200':
          description: List of error reports for the authenticated brand, sorted by descending creation date.
          content:
            application/vnd.api+json:
              schema:
                type: object
                required:
                - data
                - jsonapi
                properties:
                  jsonapi:
                    description: An object describing the server's implementation
                    type: object
                    properties: &id005
                      version:
                        type: string
                      meta:
                        description: Non-standard meta-information that can not be represented as an attribute or relationship.
                        type: object
                        additionalProperties: true
                    additionalProperties: false
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)'
                        id:
                          type: string
                          description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)'
                          format: uuid
                        attributes:
                          type: object
                          properties:
                            pimImportJobId:
                              type: string
                              format: uuid
                              description: Identifier of the PIM import job whose failed items are reported.
                            brandUuid:
                              type: string
                              format: uuid
                              description: Owning brand UUID.
                            status:
                              type: string
                              description: Lifecycle status of the error report.
                              enum:
                              - created
                              - started
                              - completed
                              - failed
                            filename:
                              type: string
                              description: Name the file will be served as.
                            failureReason:
                              type:
                              - 'null'
                              - string
                              description: Reason of failure, set only when the status is `failed`.
                            createdAt:
                              type: string
                              format: date-time
                            startedAt:
                              type:
                              - 'null'
                              - string
                              format: date-time
                            completedAt:
                              type:
                              - 'null'
                              - string
                              format: date-time
                            expiresAt:
                              type:
                              - 'null'
                              - string
                              format: date-time
                              description: Moment after which the file is no longer downloadable. Reports are retained for 30 days after completion.
                            downloadUrl:
                              type:
                              - 'null'
                              - string
                              format: uri
                              description: Present when the report is completed and not expired.
                          required:
                          - pimImportJobId
                          - brandUuid
                          - status
                          - filename
                          - createdAt
                      required:
                      - type
                      - id
                      - attributes
        '401':
          description: Unauthorized
          content:
            application/vnd.api+json:
              schema:
                type: object
                additionalProperties: false
                properties: &id006
                  errors:
                    type: array
                    uniqueItems: true
                    items:
                      type: object
                      properties:
                        code:
                          description: An application-specific error code, expressed as a string value.
                          type: string
                        detail:
                          description: A human-readable explanation specific to this occurrence of the problem.
                          type: string
                        status:
                          description: The HTTP status code applicable to this problem, expressed as a string value.
                          type: string
                        title:
                          description: The HTTP status code description applicable to this problem
                          type: string
                        source:
                          type: object
                          description: Optional object pointing towards the problematic field
                          properties:
                            pointer:
                              type: string
                              description: The field key
                        meta:
                          description: Non-standard meta-information that can not be represented as an attribute or relationship.
                          type: object
                          additionalProperties: true
                      additionalProperties: false
                  jsonapi:
                    description: An object describing the server's implementation
                    type: object
                    properties: *id005
                    additionalProperties: false
                required: &id007
                - errors
              example:
                jsonapi:
                  version: '1.0'
                errors:
                - detail: Unauthorized
                  status: '401'
        '403':
          description: '[Forbidden](https://jsonapi.org/format/#crud-creating-responses-403)'
          content:
            application/vnd.api+json:
              schema:
                type: object
                additionalProperties: false
                properties: *id006
                required: *id007
              example:
                jsonapi:
                  version: '1.0'
                errors:
                - detail: Forbidden
                  status: '403'
        '406':
          description: Not Acceptable
          content:
            application/vnd.api+json:
              schema:
                type: object
                additionalProperties: false
                properties: *id006
                required: *id007
              example:
                jsonapi:
                  version: '1.0'
                errors:
                - detail: Not Acceptable
                  status: '406'
        '415':
          description: Unsupported Media Type
          content:
            application/vnd.api+json:
              schema:
                type: object
                additionalProperties: false
                properties: *id006
                required: *id007
              example:
                jsonapi:
                  version: '1.0'
                errors:
                - detail: Unsupported Media Type
                  status: '415'
        '500':
          description: '[Server Error](https://jsonapi.org/format/#errors)'
          content:
            application/vnd.api+json:
              schema:
                type: object
                additionalProperties: false
                properties: *id006
                required: *id007
              example:
                jsonapi:
                  version: '1.0'
                errors:
                - detail: Server Error
                  status: '500'
  /api/v1/catalog/exchange/error-reports/{id}:
    get:
      summary: Retrieve an error report
      operationId: catalog-exchange-error-reports-show
      description: Fetches a single error report. Use to poll its status until `completed` (or `failed`).
      tags:
      - Catalog Exchange
      parameters:
      - schema:
          type: string
          format: uuid
        name: id
        in: path
        required: true
        description: UUID of the error report.
      responses:
        '200':
          description: Single error report
          content:
            application/vnd.api+json:
              schema:
                type: object
                required:
                - data
                - jsonapi
                properties:
                  jsonapi:
                    description: An object describing the server's implementation
                    type: object
                    properties: &id008
                      version:
                        type: string
                      meta:
                        description: Non-standard meta-information that can not be represented as an attribute or relationship.
                        type: object
                        additionalProperties: true
                    additionalProperties: false
                  data:
                    type: object
                    properties:
                      type:
                        type: string
                        description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)'
                      id:
                        type: string
                        description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)'
                        format: uuid
                      attributes:
                        type: object
                        properties:
                          pimImportJobId:
                            type: string
                            format: uuid
                            description: Identifier of the PIM import job whose failed items are reported.
                          brandUuid:
                            type: string
                            format: uuid
                            description: Owning brand UUID.
                          status:
                            type: string
                            description: Lifecycle status of the error report.
                            enum:
                            - created
                            - started
                            - completed
                            - failed
                          filename:
                            type: string
                            description: Name the file will be served as.
                          failureReason:
                            type:
                            - 'null'
                            - string
                            description: Reason of failure, set only when the status is `failed`.
                          createdAt:
                            type: string
                            format: date-time
                          startedAt:
                            type:
                            - 'null'
                            - string
                            format: date-time
                          completedAt:
                            type:
                            - 'null'
                            - string
                            format: date-time
                          expiresAt:
                            type:
                            - 'null'
                            - string
                            format: date-time
                            description: Moment after which the file is no longer downloadable. Reports are retained for 30 days after completion.
                          downloadUrl:
                            type:
                            - 'null'
                            - string
                            format: uri
                            description: Present when the report is completed and not expired.
                        required:
                        - pimImportJobId
                        - brandUuid
                        - status
                        - filename
                        - createdAt
                    required:
                    - type
                    - id
                    - attributes
        '401':
          description: Unauthorized
          content:
            application/vnd.api+json:
              schema:
                type: object
                additionalProperties: false
                properties: &id009
                  errors:
                    type: array
                    uniqueItems: true
                    items:
                      type: object
                      properties:
                        code:
                          description: An application-specific error code, expressed as a string value.
                          type: string
                        detail:
                          description: A human-readable explanation specific to this occurrence of the problem.
                          type: string
                        status:
                          description: The HTTP status code applicable to this problem, expressed as a string value.
                          type: string
                        title:
                          description: The HTTP status code description applicable to this problem
                          type: string
                        source:
                          type: object
                          description: Optional object pointing towards the problematic field
                          properties:
                            pointer:
                              type: string
                              description: The field key
                        meta:
                          description: Non-standard meta-information that can not be represented as an attribute or relationship.
                          type: object
                          additionalProperties: true
                      additionalProperties: false
                  jsonapi:
                    description: An object describing the server's implementation
                    type: object
                    properties: *id008
                    additionalProperties: false
                required: &id010
                - errors
              example:
                jsonapi:
                  version: '1.0'
                errors:
                - detail: Unauthorized
                  status: '401'
        '403':
          description: '[Forbidden](https://jsonapi.org/format/#crud-creating-responses-403)'
          content:
            application/vnd.api+json:
              schema:
                type: object
                additionalProperties: false
                properties: *id009
                required: *id010
              example:
                jsonapi:
                  version: '1.0'
                errors:
                - detail: Forbidden
                  status: '403'
        '404':
          description: '[Not found](https://jsonapi.org/format/#fetching-resources-responses-404)'
          content:
            application/vnd.api+json:
              schema:
                type: object
                additionalProperties: false
                properties: *id009
                required: *id010
              example:
                jsonapi:
                  version: '1.0'
                errors:
                - detail: Not found
                  status: '404'
        '406':
          description: Not Acceptable
          content:
            application/vnd.api+json:
              schema:
                type: object
                additionalProperties: false
                properties: *id009
                required: *id010
              example:
                jsonapi:
                  version: '1.0'
                errors:
                - detail: Not Acceptable
                  status: '406'
        '415':
          description: Unsupported Media Type
          content:
            application/vnd.api+json:
              schema:
                type: object
                additionalProperties: false
                properties: *id009
                required: *id010
              example:
                jsonapi:
                  version: '1.0'
                errors:
                - detail: Unsupported Media Type
                  status: '415'
        '500':
          description: '[Server Error](https://jsonapi.org/format/#errors)'
          content:
            application/vnd.api+json:
              schema:
                type: object
                additionalProperties: false
                properties: *id009
                required: *id010
              example:
                jsonapi:
                  version: '1.0'
                errors:
                - detail: Server Error
                  status: '500'
  /api/v1/catalog/exchange/storage/error-reports/{id}:
    get:
      summary: Download a completed error report
      operationId: catalog-exchange-error-reports-download
      description: 'Streams the generated XLSX file for a completed error report. The endpoint returns 404 if the report is

        not yet completed or if it has expired (reports are retained for 30 days after completion).

        '
      tags:
      - Catalog Exchange
      parameters:
      - schema:
          type: string
          format: uuid
        name: id
        in: path
        required: true
        description: UUID of the error report.
      responses:
        '200':
          description: XLSX file containing the failed rows of the PIM import, with each cell that needs to be corrected highlighted in red and carrying a comment with the validation message.
          content:
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized
          content:
            application/vnd.api+json:
              schema:
                type: object
                additionalProperties: false
                properties: &id011
                  errors:
                    type: array
                    uniqueItems: true
                    items:
                      type: object
                      properties:
                        code:
                          description: An application-specific error code, expressed as a string value.
                          type: string
                        detail:
                          description: A human-readable explanation specific to this occurrence of the problem.
                          type: string
                        status:
                          description: The HTTP status code applicable to this problem, expressed as a string value.
                          type: string
                        title:
                          description: The HTTP status code description applicable to this problem
                          type: string
                        source:
                          type: object
                          description: Optional object pointing towards the problematic field
                          properties:
                            pointer:
                              type: string
                              description: The field key
                        meta:
                          description: Non-standard meta-information that can not be represented as an attribute or relationship.
                          type: object
                          additionalProperties: true
                      additionalProperties: false
                  jsonapi:
                    description: An object describing the server's implementation
                    type: object
                    properties:
                      version:
                        type: string
                      meta:
                        description: Non-standard meta-information that can not be represented as an attribute or relationship.
                        type: object
                        additionalProperties: true
                    additi

# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ankorstore/refs/heads/main/openapi/ankorstore-catalog-exchange-api-openapi.yml