openapi: 3.0.0
info:
  version: 2.1.0
  x-api-id: "fda2af80-0e99-4e24-b448-40d1d26770bb"
  x-audience: "external-partner"
  title: "ICM Reports API"
  description: |-
    The Intra Community Movement (ICM) Report provides data on movement of items between Zalando facilities in EU countries, which merchants can use to meet compliance obligations, if needed.

    This API endpoint allows merchants to request reports on movements of their stock for the specified date range.

    So partners can:

      * Fetch a report on all the cross border movements for the specified date range.
      * The date range reflects the date when the transaction was recorded in the API.

    Limitations / Suggestions:

      * Use `GET /intra-community-movements/{merchant-id}?from={from}&to={to}` endpoint
      * The report will be fetched for the specified date range.
      * A report for a specific date can contain transactions from previous days.
      * We recommend that you fetch data for a specific day no sooner than 12pm CET on the next business day following the date you want to fetch.
      * Data is available for the last 2 years, due to our data retention policy.
      * In case of every non `200` response the result should be ignored and refetched after interval of at least 2 minutes.

servers:
  - url: "api.merchants.zalando.com/zfs/stock-movements"
    description: "Production instance"
  - url: "api-sandbox.merchants.zalando.com/zfs/stock-movements"
    description: "Sandbox instance for merchant center"

paths:
  "/intra-community-movements/{merchant-id}":
    get:
      summary: "Returns the ICM Report"
      description:  |
        Returns all the cross border, intra community movements matching the given query, ordered by movement date in ascending.
        This endpoint can be used by merchants to get access to all ICM Report data for a specified month.
      security:
        - merchant_platform:
          - "zfs/icm-reports/read"
      parameters:
        - in: path
          name: "merchant-id"
          schema:
            type: string
            format: uuid
          description: The Zalando specific UUID representing a merchant.
          required: true
        - in: query
          name: "from"
          schema:
            type: string
            format: date
          description: The start date for the query.
          example: "2020-04-01"
          required: true
        - in: query
          name: "to"
          schema:
            type: string
            format: date
          description: The end date (inclusive) for the query.
          example: "2020-04-10"
          required: true
      responses:
        200:
          description: |
            Returns a list of all the intra community movements in the requested month.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IcmReportResponse"
        default:
          description: "A specific error occurred - see status code for more information."
          content:
              application/problem+json:
                schema:
                  $ref: "https://opensource.zalando.com/problem/schema.yaml#/Problem"
components:
  securitySchemes:
    merchant_platform:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: "https://api-sandbox.merchants.zalando.com/auth/token"
          scopes:
            "zfs/icm-reports/read": "Access to ZFS ICM Reports of a merchant."
  schemas:
    IcmReportResponse:
      type: object
      properties:
        merchant_id:
          type: string
          format: uuid
          description: "Merchant ID"
        reports:
          type: array
          description: "A set of reports for each day of the specified month"
          items:
            $ref: "#/components/schemas/Report"
      required:
        - merchant_id
    Report:
      type: object
      description: "Intra Community Movement report"
      properties:
        transaction_date:
          type: string
          format: date
          description: "Transaction date of the movement."
          example: "2020-04-08"
        movements:
          type: array
          items:
            $ref: "#/components/schemas/Movement"
      required:
        - transaction_date
        - movements
    Movement:
      type: object
      description: "Intra Community Movement"
      properties:
        product_sku:
          type: string
          description: "Unique Identifier of the product."
        ean:
          $ref: "#/components/schemas/Ean13"
        quantity:
          type: integer
          format: int64
          description: "Quantity of the specific product defined by the ean been moved."
        source_stock_location:
          $ref: "#/components/schemas/StockLocation"
        destination_stock_location:
          $ref: "#/components/schemas/StockLocation"
        movement_type:
          type: string
          enum:
            - return_center_inbound
            - customer_return_inbound
            - customer_order_relocation
            - automatic_relocation
          description: "Type of movement"
        order_number:
          type: string
          description: "Identifier for the set of movements on a particular day between 2 locations"
        merchant_sku:
          type: string
          description: "Product identifier provided by merchant during article onboarding"
      required:
        - product_sku
        - ean
        - quantity
        - destination_stock_location
        - source_stock_location
    StockLocation:
      type: object
      description: "Details of the Stock Location"
      properties:
        location_id:
          type: string
          format: uuid
          description: "Unique identifier for the Stock Location."
        name:
          type: string
          description: "The name / location of the Stock Location."
          example: "Erfurt"
        country_code:
          type: string
          description: "Country code in ISO 3166-1 alpha-2 of the country, the location is in."
          example: "DE"
      required:
        - location_id
        - name
        - country_code
    Ean13:
      type: string
      format: ean
      pattern: "^[0-9]{13}$"
      maxLength: 13
      description: "A 13-digit EAN"
      example: 0191476239145
