diff --git a/api_docs/swagger/components/requestBodies/partner_order_payload.yaml b/api_docs/swagger/components/requestBodies/partner_order_payload.yaml index 0adb0b19..2ce6b36d 100644 --- a/api_docs/swagger/components/requestBodies/partner_order_payload.yaml +++ b/api_docs/swagger/components/requestBodies/partner_order_payload.yaml @@ -1,4 +1,3 @@ -description: Payload to create an OEM partner order on SCC API. required: true content: application/json: @@ -8,7 +7,7 @@ content: partner_order: required: true type: object - description: Main object containing all required data to create an order. + description: Object which represents the order to be placed. properties: oem_token: $ref: '/swagger/components/requestBodies/fields.yaml#/oem_token' @@ -22,3 +21,45 @@ content: description: List of all order items. items: $ref: '/swagger/components/requestBodies/partner_order_item_payload.yaml' +description: |- + Payload to create an OEM partner order on SCC API. + + The request's payload *must* contain a JSON object that *should* correspond to + a single order. + + At the root of the main JSON object, there *must* be an unique key named + `"partner_order"`, whose value *should* be an JSON object representing an OEM + partner order, containing the following keys: + + - `"oem_token"`: string, **required** + + Value *must* be a string, with a maximum length of 255 characters. + It *should not* be empty, and must be unique per OEM partner at the moment + of placing a new order. It is generated and kept by the OEM partner. + + - `"purchased_at"`: string, **required** + + Value *must* be a string, ISO8601-formatted. It must be older than the + current date and time (cannot be a moment in the future). It represents + the date and time at which the customer placed the order with the OEM + partner. + + - `"email"`: string, *optional* + + Value *must* be a string, email-formatted. The key-value pair *may* be + ommited. It represents the customer's email address to be notified aboutt + activated subscriptions. + + - `"partner_order_items"`: array of JSON objects, **required** + + Value *must* be an array of JSON objects representing the order items. + Those objects *should* contain the following keys: + + - `"sku"`: string, **required** + + Value *must* be a string and *must* match a valid SUSE SKU. + + - `"system_limit"`: integer, **required** + + Value *must* be an integer greater than one. It represents the maximum + number of systems which can use the given SKU simultaneously. diff --git a/api_docs/swagger/components/requestBodies/pre_activation/partner_order_payload.yaml b/api_docs/swagger/components/requestBodies/pre_activation/partner_order_payload.yaml index 1f1cece8..df96a7ae 100644 --- a/api_docs/swagger/components/requestBodies/pre_activation/partner_order_payload.yaml +++ b/api_docs/swagger/components/requestBodies/pre_activation/partner_order_payload.yaml @@ -1,4 +1,3 @@ -description: Partner order object required: true content: application/json: @@ -24,3 +23,59 @@ content: description: List of all order items. items: $ref: '/swagger/components/requestBodies/pre_activation/partner_order_item_payload.yaml' +description: |- + Payload to create an OEM partner order and pre-activate it on SCC API. + + The request's payload *must* contain a JSON object that *should* correspond to + a single order. + + At the root of the main JSON object, there *must* be an unique key named + `"partner_order"`, whose value *should* be an JSON object representing an OEM + partner order, containing the following keys: + + - `"oem_token"`: string, **required** + + Value *must* be a string, with a maximum length of 255 characters. + It *should not* be empty, and must be unique per OEM partner at the moment + of placing a new order. It is generated and kept by the OEM partner. + + - `"purchased_at"`: string, **required** + + Value *must* be a string, ISO8601-formatted. It must be older than the + current date and time (cannot be a moment in the future). It represents + the date and time at which the customer placed the order with the OEM + partner. + + - `"end_user_account_number"`: string, **required** + + Value *must* be a string which identifies the end user (customer) within + the SCC domain. It *must* be either the end user's UC site ID or the end + user's Sales Force account number. It *should* be informed by the end user + to the OEM partner prior to placing an order to SUSE. + + - `"email"`: string, *optional* + + Value *must* be a string, email-formatted. The key-value pair *may* be + ommited. It represents the customer's email address to be notified aboutt + activated subscriptions. + + - `"partner_order_items"`: array of JSON objects, **required** + + Value *must* be an array of JSON objects representing the order items. + Those objects *should* contain the following keys: + + - `"sku"`: string, **required** + + Value *must* be a string and *must* match a valid SUSE SKU. + + - `"system_limit"`: integer, **required** + + Value *must* be an integer greater than one. It represents the maximum + number of systems which can use the given SKU simultaneously. + + - `"starts_at"`: string, *optional* + + Value *must* be a string, ISO8601-formatted. It *must* be newer than + the current date and time (cannot be a moment in the past). It is used + to define the start date of a SKU lifetime. If omited, the lifetime + starts once SCC successfully activates the order item. diff --git a/api_docs/swagger/components/requestBodies/renewal/partner_order_payload.yaml b/api_docs/swagger/components/requestBodies/renewal/partner_order_payload.yaml new file mode 100644 index 00000000..cf4677c9 --- /dev/null +++ b/api_docs/swagger/components/requestBodies/renewal/partner_order_payload.yaml @@ -0,0 +1,79 @@ +required: true +content: + application/json: + schema: + type: object + properties: + partner_order: + required: true + type: object + description: Object which represents the order to be renewed. + properties: + oem_token: + $ref: '/swagger/components/requestBodies/fields.yaml#/oem_token' + purchased_at: + $ref: '/swagger/components/requestBodies/fields.yaml#/purchased_at' + email: + $ref: '/swagger/components/requestBodies/fields.yaml#/email' + partner_order_items: + required: true + type: array + description: List of order items to be changed. + items: + $ref: '/swagger/components/requestBodies/partner_order_item_payload.yaml' +description: |- + Payload to renew an existing OEM partner order on SCC API. + + The request's payload *must* contain a JSON object that *should* correspond to + a single order. + + At the root of the main JSON object, there *must* be an unique key named + `"partner_order"`, whose value *should* be an JSON object representing an OEM + partner order, containing the following keys: + + - `"oem_token"`: string, **required** + + Value *must* be a string, with a maximum length of 255 characters. + It *should not* be empty. The informed token *should* match one of an + existing order placed by the OEM partner. This means that renewals + *should* only be applied to existing orders whose subscriptions are active. + + - `"purchased_at"`: string, **required** + + Value *must* be a string, ISO8601-formatted. It must be older than the + current date and time (cannot be a moment in the future). It represents + the date and time at which the customer placed the order with the OEM + partner. + + - `"email"`: string, *optional* + + Value *must* be a string, email-formatted. The key-value pair *may* be + ommited. It represents the customer's email address to be notified aboutt + activated subscriptions. + + - `"partner_order_items"`: array of JSON objects, **required** + + Value *must* be an array of JSON objects representing the order items. + It *may* be empty if there are no items to be changed. Those objects + *should* contain the following keys: + + - `"sku"`: string, **required** + + Value *must* be a string and *must* match a valid SUSE SKU. Renewal + orders *should* only contain SKUs that match active subscriptions from + the initial order. + + E.g., suppose an initial order which contains exactly the order items + **SUSE-SKU-PRODUCT-A-1Y** and **SUSE-SKU-PRODUCT-B-1Y*,* both 1-year + subscriptions. A renewal order *may* contain the same SKUs or SKUs + which related to the same products, like **SUSE-SKU-PRODUCT-A-3Y** + (3 years) or **SUSE-SKU-PRODUCT-B-5Y** (5 years), but not a SKU for a + new subscription, like **SKU-PRODUCT-C-1Y** for product C, which is + not included in the initial order. + + - `"system_limit"`: integer, **required** + + Value *must* be an integer greater than one. It represents the maximum + number of systems which can use the given SKU simultaneously. It *may* + be different from values of a previous order, meaning the system limit + for a given SKU *may* be updated. diff --git a/api_docs/swagger/paths/partner_orders.yaml b/api_docs/swagger/paths/partner_orders.yaml index 475c754a..18df6b16 100644 --- a/api_docs/swagger/paths/partner_orders.yaml +++ b/api_docs/swagger/paths/partner_orders.yaml @@ -27,8 +27,8 @@ post: requestBody: $ref: '/swagger/swagger.yaml#/components/requestBodies/PartnerOrderPayload' responses: - '200': - description: Partner order created successfully. + '201': + description: Created content: application/json: schema: diff --git a/api_docs/swagger/paths/partner_orders/renewal.yaml b/api_docs/swagger/paths/partner_orders/renewal.yaml index 9e884235..b855a4d8 100644 --- a/api_docs/swagger/paths/partner_orders/renewal.yaml +++ b/api_docs/swagger/paths/partner_orders/renewal.yaml @@ -13,7 +13,7 @@ post: only to extend the lifespan of active subscriptions and/or change the system limits. requestBody: - $ref: '/swagger/swagger.yaml#/components/requestBodies/PartnerOrderPayload' + $ref: '/swagger/swagger.yaml#/components/requestBodies/RenewalPartnerOrderPayload' responses: '200': description: Partner order created successfully. diff --git a/api_docs/swagger/swagger.yaml b/api_docs/swagger/swagger.yaml index c9cd6b84..73c63b34 100644 --- a/api_docs/swagger/swagger.yaml +++ b/api_docs/swagger/swagger.yaml @@ -71,6 +71,8 @@ components: $ref: "/swagger/components/requestBodies/partner_order_payload.yaml" PreActivationPartnerOrderPayload: $ref: "/swagger/components/requestBodies/pre_activation/partner_order_payload.yaml" + RenewalPartnerOrderPayload: + $ref: "/swagger/components/requestBodies/renewal/partner_order_payload.yaml" schemas: PartnerOrder: $ref: "/swagger/components/schemas/partner_order.yaml"