Zalando Reports API

openapi: 3.2.0
info:
  version: 4.2.0
  x-api-id: cc2c30ca-2969-403e-87b1-e27df78ed655
  x-audience: external-partner
  title: zDirect Platform ZFS Stock Movements Reports API
  description: "The Stock Movements API is a service offered by Zalando Fulfillment Solutions (ZFS).\n\nThe API makes ZFS business to business movements processes more transparent for partners.\nThe API enables increased transparency for:\n  - Inbound receive process\n  - Outbound return process\n  - Liquidation Data\n\n!!! note\n\n  The retention time for data in this service is 100 days. After that, data may be deleted without notice.  \n  Please note that this limitation has been removed for `GET /reports/received-items/{merchant-id}` endpoint. Now it is the current year and previous year.\n\n\n## Inbound receive process\n\nThe inbound receive process is the process of receiving items in the warehouse (goods receipt) that were delivered by any partner.\n\nEvery item will get a unique ID the Quality Label (QL) that later identifies the item through all warehouse processes.\n\n## Outbound return process\n\nThe outbound return process is the process of returning items from the warehouse to the owning partner.\n\nThe information is enhanced by the quality of the good, if it is known.\n\n## Liquidation Data\n\n  This call returns all items that have been liquidated for a merchant within a specified time frame.\n\n```http\n  GET /zfs/stock-movements/liquidated-items/{merchant_ID}?from=$FROM_DATE&to=$TO_DATE&purchase_order_number=$PURCHASE_ORDER_NUMBER\n```\n  **Note that>>**\n\n  In exceptional scenarios such as system lags or integration delays,\nthere is a possibility that `From` & `To` dates may not fecth 100% items which were liquidated in that duration. In such cases, we request you to retry the report in next 48 hours.\n\n## Fetch strategy\n\nTo get a constant stream of received events the partner has to call the endpoint in regular intervals.\nThe client has to ensure that the intervals (`from` and `to` query parameter) will not lead to data gaps on client side.\n\nSo partners can:\n\n  * build a complete copy of received/returned items in it's database\n  * Can read a \"constant\" stream of item receive/return information\n\nLimitations / Suggestions:\n\n  * Use `GET /returned-items/{merchant_id}?from=&to=` endpoint\n  * Use fetch intervals between 15 and 60 minutes, this ensures that:\n    * the data sets are not too big\n    * the partner get regular updates\n  * The request intervals must not have gaps in between\n  * Request intervals are allowed to overlap. The client has to ensure to not consume received items more than once.\n    * The `quality_label` is unique. It should be used to ensure to not consume `receive-items` more than once.\n  * The query field `from` and `to` relates to `consumed_timestamp`\n  * In case of every non `200` response the result should be ignored and refetched after interval of at least 2 minutes.\n\n## Fetch strategy for the received items endpoint\n\nReceived items endpoint uses a cursor based pagination to fetch the data. Partners do\nnot have to split requested time interval to smaller chunks. Thus we recommend the following way to retrieve the data:\n  * Use `GET /reports/received-items/{merchant_id}` endpoint without cursor query parameter\n  * Use received cursor (if not empty) from the response to fetch the next page of data (include the cursor in the next request)\n  * Repeat the previous step until the cursor in the response is empty"
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
tags:
- name: Reports
paths:
  /reports/received-items/{merchant-id}:
    get:
      summary: Retrieve inbounded items
      description: Returns all items inbounded at Zalando warehouses for specific `merchant-id` and `zalando_advice_ids`. Endpoint has no 100 days time limitation, but to not overload the client, it provides cursor based pagination. The cursor is a string that is returned in the response and can be used to fetch the next page of results. Please note that if `from` and `to` parameters are not provided the API will return the data for the last 100 days.
      security:
      - BearerAuth:
        - partner-inbound-tracker.received.read
      parameters:
      - in: path
        name: merchant-id
        schema:
          type: string
          format: uuid
        example: 29809185-6a98-4691-a15b-e8d16839b6e8
        description: Merchant ID
        required: true
      - in: query
        name: zalando_advice_ids
        schema:
          type: array
          items:
            $ref: '#/components/schemas/AdviceId'
        description: Zalando advice ids to filter inbounded items by. Returns items for all advice ids if not provided.
        required: false
      - in: query
        name: from
        schema:
          $ref: '#/components/schemas/DateTime'
        description: Start timestamp. Default is now minus 100 days.
        required: false
      - in: query
        name: to
        schema:
          $ref: '#/components/schemas/DateTime'
        description: End timestamp. Default is now.
        required: false
      - in: query
        name: cursor
        schema:
          type: string
        description: Cursor to paginate through results
        example: MjAxNy0wNy0yMVQxNzozMjoyOFoK
        required: false
      - in: query
        name: limit
        schema:
          type: string
          default: 100000
        description: Number of inbounded items to fetch per page. Maximum is 200000.
        required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboundedItemsResponse'
        default:
          description: A specific error occurred - see status code for more information.
          content:
            application/problem+json:
              schema:
                $ref: https://opensource.zalando.com/restful-api-guidelines/problem-1.0.1.yaml#/Problem
      tags:
      - Reports
components:
  schemas:
    InboundedItem:
      type: object
      description: Inbounded Item
      properties:
        zalando_advice_id:
          allOf:
          - $ref: '#/components/schemas/AdviceId'
          description: The ID of the advice the item belongs to.
        ean:
          $ref: '#/components/schemas/Ean13'
        quality_label:
          type: string
          description: A unique identifier per EAN per item.
          example: 00014D02W8V
        merchant_article_id:
          type: string
          description: A merchant specified article id if provided. E.g. UPOS-8
        merchant_item_id:
          type: string
          description: A merchant specified item id if provided. E.g. UPOS-15
        merchant_b2b_reference:
          type: string
          description: A merchant specific optional reference id or information for the advice (for example a merchant's order name or number)
          example: reference
        location_id:
          type: string
          format: uuid
          description: Location ID of the warehouse that inbounded the item.
          example: 29809185-6a98-4691-a15b-e8d16839b6e8
        received_timestamp:
          allOf:
          - $ref: '#/components/schemas/DateTime'
          description: Timestamp when actual inbound has happened.
      required:
      - zalando_advice_id
      - ean
      - quality_label
      - location_id
      - received_timestamp
    DateTime:
      type: string
      format: date-time
      description: Date time
      example: '2017-07-21T17:32:28Z'
    AdviceId:
      type: string
      pattern: ^[0-9]{8}$
      example: 99200001
    InboundedItemsResponse:
      type: object
      properties:
        received_items:
          type: array
          items:
            $ref: '#/components/schemas/InboundedItem'
        next:
          type: string
          description: Cursor reference. Used to fetch the next page of results.
          example: MjAxNy0wNy0yMVQxNzozMjoyOFoK
    Ean13:
      type: string
      format: ean
      pattern: ^[0-9]{13}$
      maxLength: 13
      description: A 13-digit EAN
      example: 0191476239145
  securitySchemes:
    merchant_platform:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api-sandbox.merchants.zalando.com/auth/token
          scopes:
            zfs/received-item/read: Access to ZFS received items of a merchant.
            zfs/returned-item/read: Access to ZFS returned items of a merchant.