openapi: 3.1.0
info:
  version: 1.2.2-oas3.1
  title: Ankorstore Stock Tracking and Logistics Applications Movements 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: Movements
paths:
  /api/astral/v1/stock/postings:
    get:
      tags:
      - Movements
      summary: List postings
      description: 'Returns movement history for a set of product variants and locations, based on the provided filters.

        To receive information on which specific lots were involved in the movement, include the `lot` resource. You

        may also include the transaction resource to get more information on what caused the posting.

        '
      operationId: list-postings
      parameters:
      - $ref: '#/components/parameters/acceptInHeader'
      - $ref: '#/components/parameters/xAksBrandUuidHeader'
      - $ref: '#/components/parameters/xAksRetailerUuidHeader'
      - $ref: '#/components/parameters/productVariantIdFilter'
      - $ref: '#/components/parameters/locationTypeFilter'
      - $ref: '#/components/parameters/locationIdFilter'
      - $ref: '#/components/parameters/locationStatusFilter'
      - $ref: '#/components/parameters/pageLimit'
      - $ref: '#/components/parameters/pageBeforeUuidTimestamp'
      - $ref: '#/components/parameters/pageAfterUuidTimestamp'
      - name: sort
        in: query
        description: Specify what to sort by
        required: false
        allowEmptyValue: false
        schema:
          type: string
          enum:
          - transaction.createdAt
          - -transaction.createdAt
      - name: filter[movementType][in][]
        in: query
        description: Include only specific movement types
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/MovementType'
      - name: filter[movementType][notIn][]
        in: query
        description: Exclude specific movement types
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/MovementType'
      - name: include
        in: query
        description: A comma-separated list of resources to include. Options are transaction, lot, state. The states that will be included represent the quantities at the start of the set of postings. Eg. when sorted ascending, the state will represent the quantities at cursor `meta.page.from`. When sorting descending, `meta.page.to`
        schema:
          type: string
      responses:
        default:
          $ref: '#/components/responses/ErrorResponse'
        '200':
          $ref: '#/components/responses/PostingCollectionResponse'
  /api/astral/v1/stock/transactions:
    get:
      tags:
      - Movements
      summary: List transactions
      description: 'Returns transaction history for a set of product variants and locations, based on the provided filters.

        Filters include relatedId, which is typically filled with the masterOrderUuid, fulfillmentOrderUuid or in case

        of reservations, a user-specified identifier. You may also include the posting resource to get the individual

        postings contained within the transaction(s).

        '
      operationId: list-transactions
      parameters:
      - $ref: '#/components/parameters/acceptInHeader'
      - $ref: '#/components/parameters/xAksBrandUuidHeader'
      - $ref: '#/components/parameters/xAksRetailerUuidHeader'
      - $ref: '#/components/parameters/productVariantIdFilter'
      - $ref: '#/components/parameters/locationTypeFilter'
      - $ref: '#/components/parameters/locationIdFilter'
      - $ref: '#/components/parameters/locationStatusFilter'
      - $ref: '#/components/parameters/pageLimit'
      - $ref: '#/components/parameters/pageBeforeUuidTimestamp'
      - $ref: '#/components/parameters/pageAfterUuidTimestamp'
      - name: filter[relatedIds][]
        in: query
        description: A set of related identifiers to fetch transactions for
        required: false
        schema:
          type: array
          minItems: 1
          items:
            type: string
      - name: sort
        in: query
        description: Specify what to sort by
        required: false
        allowEmptyValue: false
        schema:
          type: string
          enum:
          - createdAt
          - -createdAt
      - name: include
        in: query
        description: 'A comma-separated list of resources to include. Options are: posting'
        schema:
          type: string
      responses:
        default:
          $ref: '#/components/responses/ErrorResponse'
        '200':
          $ref: '#/components/responses/TransactionCollectionResponse'
components:
  schemas:
    type:
      type: string
      description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)'
    meta:
      type: object
      description: Non-standard meta-information that can not be represented as an attribute or relationship.
    Lot:
      type: object
      properties:
        number:
          type: string
        expiryDate:
          type: string
          nullable: true
          format: date
          x-go-type: civil.Date
          x-go-type-import:
            path: github.com/ankorstore/astral/pkg/civil
            name: civil
      required:
      - number
    relationshipToOne:
      description: References to other resource objects in a to-one (`relationship`). Relationships can be specified by including a member in a resource's links object.
      $ref: '#/components/schemas/linkage'
    paginationMeta:
      type: object
      description: Meta with Pagination Details
      additionalProperties: true
      properties:
        page:
          $ref: '#/components/schemas/paginationPage'
      required:
      - page
    linkage:
      description: Resource identification present in Resource Objects and Resource Identifier Objects.
      type: object
      required:
      - id
      - type
      properties:
        id:
          $ref: '#/components/schemas/id'
        type:
          $ref: '#/components/schemas/type'
        meta:
          $ref: '#/components/schemas/meta'
      additionalProperties: false
    metadata:
      type: object
      additionalProperties:
        type: string
    PostingCollection:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PostingResource'
        jsonapi:
          $ref: '#/components/schemas/jsonapi'
        meta:
          $ref: '#/components/schemas/paginationMeta'
        links:
          $ref: '#/components/schemas/paginationLinks'
        included:
          type: array
          items:
            anyOf:
            - $ref: '#/components/schemas/TransactionResource'
            - $ref: '#/components/schemas/ProductVariantStockStateResource'
      required:
      - data
      - jsonapi
    PostingsRelationships:
      type: object
      properties:
        transaction:
          $ref: '#/components/schemas/PostingRelationshipsTransactions'
        state:
          $ref: '#/components/schemas/PostingRelationshipsStates'
    ProductVariantStockStateResource:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type'
        id:
          $ref: '#/components/schemas/id'
        attributes:
          $ref: '#/components/schemas/ProductVariantStockState'
      required:
      - type
      - id
      - attributes
    Posting:
      type: object
      title: Posting
      properties:
        locationId:
          type: string
          format: uuid
        productVariantId:
          type: string
          format: uuid
        locationStatus:
          $ref: '#/components/schemas/LocationStatus'
        quantity:
          type: integer
          description: Signed quantity delta
        movementType:
          $ref: '#/components/schemas/MovementType'
        unitMultiplier:
          type: integer
          minimum: 1
          description: The number of units each item consists of at the time of this posting
        expiryDate:
          type: string
          format: date
          x-go-type: civil.Date
          x-go-type-import:
            path: github.com/ankorstore/astral/pkg/civil
            name: civil
        lotNumber:
          type: string
      required:
      - locationId
      - productVariantId
      - locationStatus
      - quantity
      - movementType
      - unitMultiplier
    id:
      type: string
      format: uuid
      description: '[resource object identifier](https://jsonapi.org/format/#document-resource-object-identification)'
    ErrorMeta:
      type: object
      properties:
        stack:
          type: array
          items:
            type: string
    PostingResource:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type'
        id:
          $ref: '#/components/schemas/id'
        attributes:
          $ref: '#/components/schemas/Posting'
        relationships:
          $ref: '#/components/schemas/PostingsRelationships'
      required:
      - type
      - id
      - attributes
    TransactionRelationshipsPostings:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/relationshipToMany'
    PostingRelationshipsStates:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/relationshipToOne'
    TransactionRelationships:
      type: object
      properties:
        postings:
          $ref: '#/components/schemas/TransactionRelationshipsPostings'
    ProductVariantStockState:
      type: object
      title: ProductVariantStockState
      properties:
        quantities:
          type: array
          items:
            $ref: '#/components/schemas/ProductVariantStockQuantity'
      required:
      - quantities
    TransactionCollection:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TransactionResource'
        jsonapi:
          $ref: '#/components/schemas/jsonapi'
        meta:
          $ref: '#/components/schemas/paginationMeta'
        links:
          $ref: '#/components/schemas/paginationLinks'
        included:
          type: array
          items:
            anyOf:
            - $ref: '#/components/schemas/PostingResource'
      required:
      - data
      - jsonapi
    Error:
      type: object
      required:
      - status
      - title
      properties:
        status:
          type: integer
        source:
          type: object
          properties:
            pointer:
              type: string
        title:
          type: string
        detail:
          type: string
        meta:
          $ref: '#/components/schemas/ErrorMeta'
    MovementType:
      type: string
      enum:
      - order_created
      - order_cancelled
      - order_reserved
      - order_shipped
      - order_received
      - replenishment
      - snapshot
      - manual
      - broken
      - lost
      - found
      - destroyed
      - replenishment_mismatch
      - delivery_refused
      - returned_to_brand
      - adjustment_reversed
      - quality_control
      - expired
      - brand_request
      - blocked_by_provider
      - unblocked
      - batched
      - unbatched
      - returned
      - batch_modified
      - expiry_date_modified
    ProductType:
      type: string
      enum:
      - single
      - bundle
    PostingRelationshipsTransactions:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/relationshipToOne'
    TransactionResource:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type'
        id:
          $ref: '#/components/schemas/id'
        attributes:
          $ref: '#/components/schemas/Transaction'
        relationships:
          $ref: '#/components/schemas/TransactionRelationships'
      required:
      - type
      - id
      - attributes
    jsonapi:
      type: object
      description: An object describing the server's implementation
      additionalProperties: false
      properties:
        version:
          type: string
        meta:
          $ref: '#/components/schemas/meta'
    relationshipToMany:
      description: An array of objects each containing `type` and `id` members for to-many relationships.
      type: array
      items:
        $ref: '#/components/schemas/linkage'
      uniqueItems: true
    paginationPage:
      description: Cursor pagination details
      type: object
      properties:
        from:
          type: string
          pattern: ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}(,\d{10})?$
          nullable: true
        to:
          type: string
          pattern: ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}(,\d{10})?$
          nullable: true
        hasMore:
          type: boolean
        perPage:
          type: integer
      required:
      - from
      - to
      - hasMore
      - perPage
    Transaction:
      type: object
      title: Transaction
      properties:
        relatedId:
          type: string
        createdAt:
          type: string
          format: date-time
        metadata:
          $ref: '#/components/schemas/metadata'
      required:
      - relatedId
      - createdAt
      - metadata
    ProductVariantStockQuantity:
      type: object
      title: ProductVariantStockQuantity
      properties:
        quantity:
          type: integer
        locationId:
          type: string
          format: uuid
        locationType:
          $ref: '#/components/schemas/LocationType'
        status:
          $ref: '#/components/schemas/StockStatus'
        lot:
          $ref: '#/components/schemas/Lot'
        unitMultiplier:
          type: integer
          minimum: 1
          description: The number of units each product variant (batch) consists of
        productType:
          $ref: '#/components/schemas/ProductType'
      required:
      - quantity
      - locationId
      - locationType
      - status
      - unitMultiplier
    LocationStatus:
      type: string
      enum:
      - available
      - damaged
      - reserved
      - qualityControl
      - blocked
      - incoming
      - void
    paginationLinks:
      description: Pagination links
      type: object
      properties:
        first:
          type: string
          example: https://www.ankorstore.com/api/v1/orders?page[limit]=15
          nullable: true
        prev:
          type: string
          example: https://www.ankorstore.com/api/v1/orders?page[before]=1189606a-139e-4b4e-917c-b0c992498bad2&page[limit]=15
          nullable: true
        next:
          type: string
          example: https://www.ankorstore.com/api/v1/orders?page[after]=1189606a-139e-4b4e-917c-b0c992498bad&page[limit]=15
          nullable: true
      required:
      - first
      - next
      - prev
    LocationType:
      type: string
      enum:
      - warehouse
      - brand
      - retailer
    StockStatus:
      type: string
      enum:
      - onHand
      - available
      - damaged
      - reserved
      - qualityControl
      - blocked
      - incoming
  parameters:
    locationIdFilter:
      name: filter[locationIds][]
      in: query
      description: A set of identifiers representing the locations to check quantities at
      required: false
      schema:
        type: array
        minItems: 1
        items:
          type: string
          format: uuid
    xAksBrandUuidHeader:
      name: X-Aks-Brand-Uuid
      in: header
      description: Brand entity when none provided via auth token
      schema:
        type: string
        format: uuid
        nullable: true
    productVariantIdFilter:
      name: filter[productVariantIds][]
      in: query
      description: A set of identifiers representing the items to check quantities for
      required: false
      schema:
        type: array
        minItems: 1
        items:
          type: string
          format: uuid
    locationTypeFilter:
      name: filter[locationTypes][]
      in: query
      description: A set of location types to check quantities at
      required: false
      schema:
        type: array
        minItems: 1
        items:
          $ref: '#/components/schemas/LocationType'
    locationStatusFilter:
      name: filter[locationStatus][]
      in: query
      description: A set of (location) statuses to check quantities for
      required: false
      schema:
        type: array
        minItems: 1
        items:
          $ref: '#/components/schemas/LocationStatus'
    pageBeforeUuidTimestamp:
      name: page[before]
      in: query
      description: show items before the provided cursors (uuid<,timestamp> format)
      required: false
      schema:
        type: string
        pattern: ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}(,\d{10})?$
    pageLimit:
      name: page[limit]
      in: query
      description: limit the amount of results returned
      required: false
      schema:
        type: integer
        format: int
        default: 10
    xAksRetailerUuidHeader:
      name: X-Aks-Retailer-Uuid
      in: header
      description: Retailer entity when none provided via auth token
      schema:
        type: string
        format: uuid
        nullable: true
    pageAfterUuidTimestamp:
      name: page[after]
      in: query
      description: show items after the provided cursors (uuid<,timestamp> format)
      required: false
      schema:
        type: string
        pattern: ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}(,\d{10})?$
    acceptInHeader:
      name: Accept
      in: header
      description: application/vnd.api+json
      schema:
        type: string
        default: application/vnd.api+json
  responses:
    PostingCollectionResponse:
      description: Set of postings
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/PostingCollection'
          examples:
            example-get-postings-simple:
              value:
                data:
                - type: posting
                  id: 018fc37f-5c0a-7913-a672-9569d7b48756
                  attributes:
                    locationId: 20e62581-67a5-4166-8b1f-344e9b06b58b
                    productVariantId: 018fc380-1c43-75f9-a101-49447fbadeb7
                    locationStatus: available
                    movementType: order_reserved
                    quantity: -10
                    unitMultiplier: 1
                - type: posting
                  id: 018fc385-5d99-7305-9cf5-a18b40005fbc
                  attributes:
                    locationId: 20e62581-67a5-4166-8b1f-344e9b06b58b
                    productVariantId: 018fc380-1c43-75f9-a101-49447fbadeb7
                    locationStatus: reserved
                    movementType: order_reserved
                    quantity: 10
                    unitMultiplier: 1
            example-get-postings-with-relations:
              value:
                data:
                - type: posting
                  id: 018fc386-3078-75b3-8e75-6bed4e01c144
                  attributes:
                    locationId: 20e62581-67a5-4166-8b1f-344e9b06b58b
                    productVariantId: 018fc380-1c43-75f9-a101-49447fbadeb7
                    locationStatus: incoming
                    movementType: replenishment
                    quantity: -227
                    unitMultiplier: 2
                  relationships:
                    transaction:
                      data:
                        type: transaction
                        id: 018fc399-3240-78b2-abfa-e8c5df1c304f
                    state:
                      data:
                        type: stock-state
                        id: 018fc380-1c43-75f9-a101-49447fbadeb7
                - type: posting
                  id: 018fc386-4c76-76cf-9319-533c7dd9b66c
                  attributes:
                    locationId: 20e62581-67a5-4166-8b1f-344e9b06b58b
                    productVariantId: 018fc380-1c43-75f9-a101-49447fbadeb7
                    locationStatus: available
                    movementType: replenishment
                    quantity: 200
                    unitMultiplier: 2
                    lotNumber: lot-Y
                    expiryDate: '2025-02-02'
                  relationships:
                    transaction:
                      data:
                        type: transaction
                        id: 018fc399-3240-78b2-abfa-e8c5df1c304f
                    state:
                      data:
                        type: stock-state
                        id: 018fc380-1c43-75f9-a101-49447fbadeb7
                - type: posting
                  id: 018fc3d3-cd9b-7c96-9b29-fd90bf0eff7b
                  attributes:
                    locationId: 20e62581-67a5-4166-8b1f-344e9b06b58b
                    productVariantId: 018fc380-1c43-75f9-a101-49447fbadeb7
                    locationStatus: available
                    movementType: replenishment
                    quantity: 24
                    unitMultiplier: 2
                    lotNumber: lot-X
                    expiryDate: '2025-01-01'
                  relationships:
                    transaction:
                      data:
                        type: transaction
                        id: 018fc399-3240-78b2-abfa-e8c5df1c304f
                    state:
                      data:
                        type: stock-state
                        id: 018fc380-1c43-75f9-a101-49447fbadeb7
                - type: posting
                  id: 018fc388-467e-7e9f-9745-0d2feb2b7b51
                  attributes:
                    locationId: 20e62581-67a5-4166-8b1f-344e9b06b58b
                    productVariantId: 018fc380-1c43-75f9-a101-49447fbadeb7
                    locationStatus: blocked
                    movementType: replenishment_mismatch
                    quantity: 3
                    unitMultiplier: 2
                    lotNumber: lot-X
                    expiryDate: '2025-01-01'
                  relationships:
                    transaction:
                      data:
                        type: transaction
                        id: 018fc399-3240-78b2-abfa-e8c5df1c304f
                    state:
                      data:
                        type: stock-state
                        id: 018fc380-1c43-75f9-a101-49447fbadeb7
                included:
                - type: transaction
                  id: 018fc399-3240-78b2-abfa-e8c5df1c304f
                  attributes:
                    relatedId: R_8P1P1LAX_681
                    createdAt: '2024-05-29T09:07:26.339Z'
                    metadata:
                      webhookId: 018fc39b-6248-7aa6-a8ed-3b1b86a2628e
                - type: stock-state
                  id: 018fc380-1c43-75f9-a101-49447fbadeb7
                  attributes:
                    quantities:
                    - status: incoming
                      locationId: 20e62581-67a5-4166-8b1f-344e9b06b58b
                      quantity: 0
                      unitMultiplier: 2
                    - status: available
                      locationId: 20e62581-67a5-4166-8b1f-344e9b06b58b
                      quantity: 200
                      unitMultiplier: 2
                      lotNumber: lot-Y
                      expiryDate: '2025-02-02'
                    - status: available
                      locationId: 20e62581-67a5-4166-8b1f-344e9b06b58b
                      quantity: 24
                      unitMultiplier: 2
                      lotNumber: lot-X
                      expiryDate: '2025-01-01'
                    - status: blocked
                      locationId: 20e62581-67a5-4166-8b1f-344e9b06b58b
                      quantity: 3
                      unitMultiplier: 2
                      lotNumber: lot-X
                      expiryDate: '2025-01-01'
    TransactionCollectionResponse:
      description: Set of transactions
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/TransactionCollection'
          examples:
            example-get-transactions-simple:
              value:
                data:
                - type: transaction
                  id: 018fc3cd-80d9-7c27-ba48-d5e4e0cba379
                  attributes:
                    relatedId: 0408720a-5a88-434c-82c2-36a0e015bba6
                    createdAt: '2024-05-28T09:07:26.339Z'
                    metadata:
                      transition: submitted
                      masterOrderUuid: 0408720a-5a88-434c-82c2-36a0e015bba6
                - type: transaction
                  id: 018fc3cf-2b19-7392-ba9a-37114eaaba6c
                  attributes:
                    relatedId: 0408720a-5a88-434c-82c2-36a0e015bba6
                    createdAt: '2024-05-29T13:07:26.339Z'
                    metadata:
                      transition: shipped
                      masterOrderUuid: 0408720a-5a88-434c-82c2-36a0e015bba6
            example-get-transactions-with-relations:
              value:
                data:
                - type: transaction
                  id: 018fc399-3240-78b2-abfa-e8c5df1c304f
                  attributes:
                    relatedId: R_8P1P1LAX_681
                    createdAt: '2024-05-29T09:07:26.339Z'
                    metadata:
                      webhookId: 018fc39b-6248-7aa6-a8ed-3b1b86a2628e
                  relationships:
                    postings:
                      data:
                      - type: posting
                        id: 018fc386-3078-75b3-8e75-6bed4e01c144
                      - type: posting
                        id: 018fc386-4c76-76cf-9319-533c7dd9b66c
                      - type: posting
                        id: 018fc3d3-cd9b-7c96-9b29-fd90bf0eff7b
                      - type: posting
                        id: 018fc388-467e-7e9f-9745-0d2feb2b7b51
                included:
                - type: posting
                  id: 018fc386-3078-75b3-8e75-6bed4e01c144
                  attributes:
                    locationId: 20e62581-67a5-4166-8b1f-344e9b06b58b
                    productVariantId: 018fc380-1c43-75f9-a101-49447fbadeb7
                    locationStatus: incoming
                    movementType: replenishment
                    quantity: -227
                    unitMultiplier: 2
                - type: posting
                  id: 018fc386-4c76-76cf-9319-533c7dd9b66c
                  attributes:
                    locationId: 20e62581-67a5-4166-8b1f-344e9b06b58b
                    productVariantId: 018fc380-1c43-75f9-a101-49447fbadeb7
                    locationStatus: available
                    movementType: replenishment
                    quantity: 200
                    unitMultiplier: 2
                - type: posting
                  id: 018fc3d3-cd9b-7c96-9b29-fd90bf0eff7b
                  attributes:
                    locationId: 20e62581-67a5-4166-8b1f-344e9b06b58b
                    productVariantId: 018fc380-1c43-75f9-a101-49447fbadeb7
                    locationStatus: available
                    movementType: replenishment
                    quantity: 24
                    unitMultiplier: 2
                - type: posting
                  id: 018fc388-467e-7e9f-9745-0d2feb2b7b51
                  attributes:
                    locationId: 20e62581-67a5-4166-8b1f-344e9b06b58b
                    productVariantId: 018fc380-1c43-75f9-a101-49447fbadeb7
                    locationStatus: blocked
                    movementType: replenishment_mismatch
                    quantity: 3
                    unitMultiplier: 2
    ErrorResponse:
      description: Example response
      content:
        application/vnd.api+json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/Error'
              jsonapi:
                $ref: '#/components/schemas/jsonapi'
            required:
            - errors
  securitySchemes:
    CookieKey:
      type: apiKey
      name: ankorstore_session
      in: cookie