{
  "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"
                }
              }
            }
          }
        }
      }
    }
  }
}