openapi: 3.0.0
info:
  title: Shopware Admin API usage
  description: >-
    This endpoint reference contains an overview of all Ratepay relevant
    endpoints for the Shopware Admin API.
  version: for the Ratepay SW6 module v7.x and above
servers:
  - url: http://your_shopware_url/api
components:
  schemas:
    ratepayOrderOperationRequestBody:
      type: object
      properties:
        items:
          type: array
          description: Items to deliver/cancel/return
          items:
            required:
              - id
              - quantity
              - updateStock
            properties:
              id:
                type: string
                description: >-
                  Identifier of order-line-item. Can be also `shipping` for the
                  shipping item.
                pattern: ^([0-9a-f]{32}|shipping)$
                example: a06c753d068c487991d6a833b4133560
              quantity:
                type: number
                description: >-
                  Identifier of order-line-item. Needs to be `1` if the item is
                  the shipping-item.
                example: 1
              updateStock:
                type: boolean
                description: >-
                  In case of cancellation or refund, this flag will return the
                  cancelled/returned items back to stock. Will be ignored in
                  case of delivery.
                example: true
    ratepayOrderOperationResponse500:
      properties:
        status:
          type: boolean
          default: false
        message:
          type: string
          description: Details about the error
  securitySchemes:
    oAuth:
      type: oauth2
      description: Authentication API
      flows:
        password:
          tokenUrl: http://your_shopware_url/api/oauth/token
          scopes:
            write: Full write access
        clientCredentials:
          tokenUrl: http://your_shopware_url/api/oauth/token
          scopes:
            write: Full write access
security:
  - oAuth:
      - write
paths:
  /_action/order/{orderId}/ratepay/info:
    get:
      summary: Get the current state of Ratepay processed order-items
      operationId: ratepayOrderItemsInfo
      description: ''
      parameters:
        - name: orderId
          in: path
          required: true
          description: Identifier of the order
          schema:
            type: string
            pattern: ^[0-9a-f]{32}$
          example: a06c753d068c487991d6a833b4133560
      responses:
        '200':
          description: Information about the line-items which got processed by Ratepay
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    default: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: >-
                            Identifier of the order-line-item. Can be also
                            `shipping` for the shipping position.
                          example: a06c753d068c487991d6a833b4133560
                          pattern: ^[0-9a-f]{32}$
                        name:
                          type: string
                          description: Name of the order-line-item
                          example: Yellow shirt
                        ordered:
                          type: number
                          description: >-
                            Ordered quantity of order-line-item. In case of the
                            shipping item, this will be always `1`.
                          example: 5
                        unitPrice:
                          type: number
                          description: Unit price of order-line-item
                          example: 8.99
                        totalPrice:
                          type: number
                          description: Total price of order-line-item
                          example: 39.95
                        position:
                          description: >-
                            Information about how many items has been
                            shipped/returned/canceled on the Ratepay gateway
                          type: object
                          properties:
                            id:
                              type: string
                              description: Identifier of entity which stores these data.
                              pattern: ^[0-9a-f]{32}$
                            canceled:
                              type: number
                              description: Count of items which has been marked as canceled
                            returned:
                              type: number
                              description: Count of items which has been marked as returned
                            delivered:
                              type: number
                              description: >-
                                Count of items which has been marked as
                                delivered
                            maxDelivery:
                              type: number
                              description: >-
                                Remaining number of products which can be
                                shipped
                            maxCancel:
                              type: number
                              description: >-
                                Remaining number of products which can be
                                canceled
                            maxReturn:
                              type: number
                              description: >-
                                Remaining number of products which can be
                                returned
        '404':
          description: If order is not found
          content:
            application/json:
              schema:
                properties:
                  status:
                    type: boolean
                    default: false
                  message:
                    type: string
                    default: Order not found
                type: object
  /_action/order/{orderId}/ratepay/deliver:
    post:
      summary: Report delivery of order-line-items of order processed by Ratepay
      operationId: ratepayOrderItemDeliver
      parameters:
        - name: orderId
          in: path
          required: true
          description: Identifier of the order
          schema:
            type: string
            pattern: ^[0-9a-f]{32}$
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ratepayOrderOperationRequestBody'
      responses:
        '204':
          description: Item(s) has been successfully delivered
        '400':
          description: >-
            The provided order-line-items does not belongs to the order, or the
            quantity is zero.
        '404':
          description: The order does not exist.
        '500':
          description: An error occurred during the delivery
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ratepayOrderOperationResponse500'
  /_action/order/{orderId}/ratepay/cancel:
    post:
      summary: Cancel order-line-items of order processed by Ratepay
      operationId: ratepayOrderItemCancel
      parameters:
        - name: orderId
          in: path
          required: true
          description: Identifier of the order
          schema:
            type: string
            pattern: ^[0-9a-f]{32}$
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ratepayOrderOperationRequestBody'
      responses:
        '204':
          description: Item(s) has been successfully canceled
        '400':
          description: >-
            The provided order-line-items does not belongs to the order, or the
            quantity is zero.
        '404':
          description: The order does not exist.
        '500':
          description: An error occurred during the cancellation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ratepayOrderOperationResponse500'
  /_action/order/{orderId}/ratepay/refund:
    post:
      summary: Refund order-line-items of order processed by Ratepay
      operationId: ratepayOrderItemRefund
      parameters:
        - name: orderId
          in: path
          required: true
          description: Identifier of the order
          schema:
            type: string
            pattern: ^[0-9a-f]{32}$
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ratepayOrderOperationRequestBody'
      responses:
        '204':
          description: Item(s) has been successfully refunded
        '400':
          description: >-
            The provided order-line-items does not belongs to the order, or the
            quantity is zero.
        '404':
          description: The order does not exist.
        '500':
          description: An error occurred during the refunding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ratepayOrderOperationResponse500'
  /_action/order/{orderId}/ratepay/addItem:
    post:
      summary: Add order-line-items of order processed by Ratepay
      description: >-
        You can add a debit or credit to the processed order by Ratepay. It is
        required that at least one order-item has been marked as shipped and not
        returned.
      operationId: ratepayOrderItemAddItem
      parameters:
        - name: orderId
          in: path
          required: true
          description: Identifier of the order
          schema:
            type: string
            pattern: ^[0-9a-f]{32}$
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - grossAmount
                - name
                - taxId
              properties:
                grossAmount:
                  type: number
                  description: >-
                    Gross amount of debit/credit. Have to be negative for
                    credits.
                  example: -5
                name:
                  type: string
                  description: Description of the order-line-item.
                  example: Discount for damaged goods
                taxId:
                  type: string
                  description: Tax-id to apply
                  pattern: ^[0-9a-f]{32}$
                  example: a06c753d068c487991d6a833b4133560
      responses:
        '204':
          description: Item(s) has been successfully added
        '400':
          description: >-
            The provided order-line-items does not belongs to the order, or the
            quantity is zero.
        '404':
          description: The order does not exist.
        '500':
          description: An error occurred during the adding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ratepayOrderOperationResponse500'
