--- swagger: "2.0" info: title: "mySE Order Entry FR API V2" version: "2.1" description: "The aim of the Order Entry API is create an Order in mySE.\n\nThrough\ \ this API, a user can:\n- Get the status of an Order through all the steps of\ \ ordering. This is achieved using the status method\n- Validate content of the\ \ order (Address and cart content) and get all the pricing details. This is achieved\ \ using the validate Order method.\n- Submit the Order to mySE. This is achieved\ \ using the submit Order method.\n\nUser authorization:\nThe user placing the\ \ order must be identified by his email address in the Order Entry request. This\ \ user must be registered in mySE on your account, and must have the permission\ \ to place an order on this account. If not, any request will be rejected by the\ \ API.\n\nDate format:\nThe format of all date fields follows the date format\ \ defined in ISO 8601 (YYYY-MM-DD)." contact: url: "http://se.com" name: "Contact Us" email: "distributorapiportal.global@se.com" schemes: - "https" host: "api.qa.se.com" basePath: "/v2/customer-order/system/myse-order-entry-fr" produces: - "application/json" consumes: - "application/json" tags: - name: "Order entry" paths: /orders/validate: post: tags: - "Order entry" summary: "Validate an order entry" description: "This API method is used to validate an order entry before it is\ \ submitted.\n\nThe API will then perform several validation steps (data types,\ \ mandatory parameters, various business rules depending on the country and/or\ \ purchaser account). Once completed, it will sends the response back to the\ \ requester:\n* if validation is successful, it sends back the order entry\ \ request object, optionnally completed with additional information.\n* if\ \ validation fails, the API sends back the order entry request object completed\ \ along with the detailed validation errors at request header and/or item\ \ level (see response code 200 for more details.) Other error conditions not\ \ strictly related to the validation of the order entry request (e.g. invalid\ \ authentication token, invalid Business Unit, ...) are still applicable and\ \ managed by the usual error responses.\n\nOnce the order entry request is\ \ valid, the requester can then submit it using the \"Submit order entry request\"\ \ API method.\n\n### #1. Technical error code for http return code 400\n\n\ Missing mandatory parameter or invalid parameter value\n\nHTTP status code\ \ | errorCode | errorMessage | comment\n-----------------|-----------|--------------|--------\n\ 400 | Invalid_Language | Language does not exist for the given Business unit\ \ | The provided language code / country code values do not exist for the\ \ requested Business unit.\n400 | Unsupported_Input | Input parameter XXX\ \ not supported for Business Unit YYY | A value has been provided for an optional\ \ input parameter that is not supported for the requested Business Unit.\n\ 400 | Invalid_Input | Invalid input value XXX for field YYY | The value provided\ \ has either an invalid type for the input parameter or a value that does\ \ not belong to a preset acceptable values.\n400 | Validation_Error | An error\ \ occured during validation | The input provided triggered a validation error,\ \ please validate it again to get more details\n400 | Delivery_Service_Invalid\ \ | Delivery service code does not exist in MySE | The requested Delivery\ \ Service does not exist in MySE.\n400 | Delivery_Details_Validation_Error\ \ | Error when validating the delivery details of the request | The validation\ \ process of the order failed due to an error with the delivery details of\ \ the order.\n400 | Customer_Id_Invalid | Customer id does not exist in MySE\ \ | The requested Customer does not exist in MySE.\n400 | PO_Number_Empty\ \ | PO Number is not Filled | No value provided in the mandatory PO number\ \ parameter.\n400 | Email_Empty | Email is not Filled | No value provided\ \ in the mandatory email parameter.\n400 | Invalid_Email | Email is invalid\ \ | The requested email does not correspond to an existing user in MySE.\n\ 400 | Delivery_Date_Invalid | Requested delivery date is invalid | Requested\ \ delivery date is invalid.\n400 | Partial_ShipToAddress| ShipTo address details\ \ are not all filled | Not all mandatories shipTo address fields are filled.\n\ 400 | Empty_OrderEntryItems | Order item is not provided | At least one order\ \ item should be provided.\n400 | Empty_CatalogNumber | Catalog Number is\ \ not Filled | No value provided in the mandatory CatalogNumber parameter.\n\ 400 | Empty_Quantity | Quantity is not Filled | No value provided in the mandatory\ \ Quantity parameter.\n400 | Invalid_Quantity | Quantity is invalid | No valid\ \ value provided in the mandatory Quantity parameter.\n\n### #2. Technical\ \ error code for http return code 403\n\nResource not accessible to the user\ \ or user not registered in mySE\n\nHTTP status code | errorCode | errorMessage\ \ | comment\n-----------------|-----------|--------------|--------\n403 |\ \ Not_Authorized | User is not authorized to place order for your\ \ account | User is not registered in mySE or doesn’t have permission to place\ \ an order on the requested account.\n\n### #3. Technical error code for http\ \ return code 500\n\nUnexpected error or service unavailable\n\nHTTP status\ \ code | errorCode | errorMessage | comment\n-----------------|-----------|--------------|--------\n\ 500 | NOK | An error has occured at | Any other error or exception\ \ found. All technical errors are managed within this specific code.\n500\ \ | Service_Unavailable | Unable to connect to MySE | Connection to MySE rejected\ \ or timeout." operationId: "orderEntryValidate" produces: - "application/json" consumes: - "application/json" parameters: - in: "body" name: "body" required: false schema: $ref: "#/definitions/OrderEntryRequest" x-examples: example-1: email: "France2@yopmail.com" poNumber: "TESTVALIDATE1" customerId: "1000051212" requestedDeliveryDate: "2022-11-29" comments: "test comment" deliveryService: "Express" shipToAddress: shipToName: "test" address: "my street to deliver" city: "my city" zipcode: "91120" orderEntryItems: - catalogNumber: "LRD10" quantity: 1 requestedDeliveryDate: "2022-11-29" itemReference: "test reference" responses: "200": description: "" schema: $ref: "#/definitions/ValidateResponse" examples: example-1: accountNumber: "1000051212" poNumber: "TESTVALIDATE1" customerId: "1000051212" deliveryService: "Standard" releaseDate: "2021-03-22" requestedDeliveryDate: "2022-11-28" customerAddress: shipToName: "test" address: "my street to deliver" zipcode: "91120" city: "my city" alternativeDeliveryAddress: true deliveryAddress: shipToName: "test" address: "my street to deliver" zipcode: "91120" city: "my city" comments: "test comment" surchargePrice: currency: "EUR" value: 26 display: "26,00 €" totalFreightPrice: currency: "EUR" value: 26 display: "26,00 €" totalTax: currency: "EUR" value: 19.38 display: "19,38 €" totalNetAmount: currency: "EUR" value: 44.88 display: "44,88 €" total: currency: "EUR" value: 116.26 display: "116,26 €" orderEntryItems: - itemsErrors: null itemNumber: "000010" catalogNumber: "LRD10" quantity: 1 requestedDeliveryDate: "2022-11-28" itemReference: "test reference" discount: "43,80%" unitNetPrice: currency: "EUR" value: 44.88 display: "44,88 €" advisedDeliveryDate: "2022-11-28" bomProduct: "Poste" "400": $ref: "#/responses/Common_Oas2_400" "401": $ref: "#/responses/Common_Oas2_401" "403": $ref: "#/responses/Common_Oas2_403" "404": $ref: "#/responses/Common_Oas2_404" "429": $ref: "#/responses/Common_Oas2_429" "500": $ref: "#/responses/Common_Oas2_500" parameters: [] /orders/{order-id}/status: get: tags: - "Order entry" summary: "Retrieve the order entry status" description: "Indicate on which state is the Order Entry submission.\n\n###\ \ #1. Technical error code for http return code 400\n\nMissing mandatory parameter\ \ or invalid parameter value\n\nHTTP status code | errorCode | errorMessage\ \ | comment\n-----------------|-----------|--------------|--------\n400 |\ \ Empty_OrderNumber | Order Number is not Filled | No value provided in the\ \ mandatory Order number parameter.\n400 | Invalid_OrderNumber | Order Number\ \ does not exist | The provided Order number does not exist in mySE for the\ \ requested Business Unit.\n\n### #2. Technical error code for http return\ \ code 500\n\nUnexpected error or service unavailable\n\nHTTP status code\ \ | errorCode | errorMessage | comment\n-----------------|-----------|--------------|--------\n\ 500 | NOK | An error has occured at | Any other error or exception\ \ found. All technical errors are managed within this specific code.\n500\ \ | Service_Unavailable | Unable to connect to MySE | Connection to MySE rejected\ \ or timeout." operationId: "orderEntryStatus" produces: - "application/json" parameters: [] responses: "200": description: "Success" schema: $ref: "#/definitions/OrderEntryStatus" examples: example: status: "Ouverte" draftReturnName: "draft return name" "400": $ref: "#/responses/Common_Oas2_400" "401": $ref: "#/responses/Common_Oas2_401" "403": $ref: "#/responses/Common_Oas2_403" "404": $ref: "#/responses/Common_Oas2_404" "429": $ref: "#/responses/Common_Oas2_429" "500": $ref: "#/responses/Common_Oas2_500" parameters: - type: "string" name: "order-id" in: "path" required: true /orders/submit: post: tags: - "Order entry" summary: "Submit an Order Entry" description: "This API method is used to submit an order entry request. The\ \ API will then perform several validation steps (data types, mandatory parameters,\ \ various business rules depending on the country and/or purchaser account).\ \ Once completed, it will submit the Order Entry request.\n\n### #1. Technical\ \ error code for http return code 400\n\nMissing mandatory parameter or invalid\ \ parameter value\n\nHTTP status code | errorCode | errorMessage | comment\n\ -----------------|-----------|--------------|--------\n400 | Invalid_Language\ \ | Language does not exist for the given Business unit | The provided language\ \ code / country code values do not exist for the requested Business unit.\n\ 400 | Unsupported_Input | Input parameter XXX not supported for Business Unit\ \ YYY | A value has been provided for an optional input parameter that is\ \ not supported for the requested Business Unit.\n400 | Invalid_Input | Invalid\ \ input value XXX for field YYY | The value provided has either an invalid\ \ type for the input parameter or a value that does not belong to a preset\ \ acceptable values.\n400 | Validation_Error | An error occured during validation\ \ | The input provided triggered a validation error, please validate it again\ \ to get more details\n400 | Delivery_Service_Invalid | Delivery service code\ \ does not exist in MySE | The requested Delivery Service does not exist in\ \ MySE.\n400 | Delivery_Details_Validation_Error | Error when validating the\ \ delivery details of the request | The validation process of the order failed\ \ due to an error with the delivery details of the order.\n400 | Customer_Id_Invalid\ \ | Customer id does not exist in MySE | The requested Customer does not exist\ \ in MySE.\n400 | PO_Number_Empty | PO Number is not Filled | No value provided\ \ in the mandatory PO number parameter.\n400 | Email_Empty | Email is not\ \ Filled | No value provided in the mandatory email parameter.\n400 | Invalid_Email\ \ | Email is invalid | The requested email does not correspond to an existing\ \ user in MySE.\n400 | Delivery_Date_Invalid | Requested delivery date is\ \ invalid | Requested delivery date is invalid.\n400 | Partial_ShipToAddress|\ \ ShipTo address details are not all filled | Not all mandatories shipTo address\ \ fields are filled.\n400 | Empty_OrderEntryItems | Order item is not provided\ \ | At least one order item should be provided.\n400 | Empty_CatalogNumber\ \ | Catalog Number is not Filled | No value provided in the mandatory CatalogNumber\ \ parameter.\n400 | Empty_Quantity | Quantity is not Filled | No value provided\ \ in the mandatory Quantity parameter.\n400 | Invalid_Quantity | Quantity\ \ is invalid | No valid value provided in the mandatory Quantity parameter.\n\ \n### #2. Technical error code for http return code 403\n\nResource not accessible\ \ to the user or user not registered in mySE\n\nHTTP status code | errorCode\ \ | errorMessage | comment\n-----------------|-----------|--------------|--------\n\ 403 | Not_Authorized | User is not authorized to place order for your\ \ account | User is not registered in mySE or doesn’t have permission to place\ \ an order on the requested account.\n\n### #3. Technical error code for http\ \ return code 500\n\nUnexpected error or service unavailable\n\nHTTP status\ \ code | errorCode | errorMessage | comment\n-----------------|-----------|--------------|--------\n\ 500 | NOK | An error has occured at | Any other error or exception\ \ found. All technical errors are managed within this specific code.\n500\ \ | Service_Unavailable | Unable to connect to MySE | Connection to MySE rejected\ \ or timeout." operationId: "orderSubmit" produces: - "application/json" consumes: - "application/json" parameters: - in: "body" name: "body" description: "Submit this Order Entry." required: false schema: $ref: "#/definitions/OrderEntryRequest" x-examples: example-1: email: "France2@yopmail.com" poNumber: "TESTVALIDATE" customerId: "1000051212" requestedDeliveryDate: "2020-11-29" comments: "test comment" deliveryService: "Express" shipToAddress: businessName: "test" street: "my street to deliver" additionalLine: "more informations about my address" city: "my city" state: "my state" zipcode: "91120" country: "FR" language: "en" orderEntryItems: - catalogNumber: "LRD10" quantity: 1 requestedDeliveryDate: "2020-11-29" itemReference: "" responses: "200": description: "Submit an Order Entry " schema: $ref: "#/definitions/SubmitResponse" examples: example-1: orderRequestDate: "2020-11-19" orderNumber: "25487" poNumber: "My test order" "400": $ref: "#/responses/Common_Oas2_400" "401": $ref: "#/responses/Common_Oas2_401" "403": $ref: "#/responses/Common_Oas2_403" "404": $ref: "#/responses/Common_Oas2_404" "429": $ref: "#/responses/Common_Oas2_429" "500": $ref: "#/responses/Common_Oas2_500" parameters: [] definitions: Address: type: "object" description: "Resource representing a phyiscal or postal address." properties: shipToName: type: "string" description: "Optional business name." shipToName2: type: "string" description: "Optional business name." address: type: "string" description: "Street name or PO box with optional extra address lines separated\ \ by end of line characters." address2: type: "string" description: "Optional address line to describe a suite, unit, floor number\ \ or named district within a city." city: type: "string" description: "Optional city or town name." zipcode: type: "string" description: "Optional zip code or postal code. Required in some countries." contactPersonName: type: "string" description: "Contact person name" contactPersonPhone: type: "string" description: "Contact person phone number" required: - "shipToName" - "address" - "city" - "zipcode" AddressRequest: title: "AddressRequest" type: "object" description: "Resource representing a physical or postal address in an order request." properties: shipToName: type: "string" description: "Optional business name." shipToName2: type: "string" description: "Optional business name." address: type: "string" description: "Street name or PO box with optional extra address lines separated\ \ by end of line characters." address2: type: "string" description: "Optional address line to describe a suite, unit, floor number\ \ or named district within a city." city: type: "string" description: "Optional city or town name." zipcode: type: "string" description: "Optional zip code or postal code. Required in some countries." contactPersonName: type: "string" description: "Contact person name" contactPersonPhone: type: "string" description: "Contact person phone number" required: - "shipToName" - "address" - "city" - "zipcode" - "contactPersonName" - "contactPersonPhone" Currency: type: "object" description: "Resource representing a currency amount." properties: currency: type: "string" description: "Three character currency code, as defined by ISO 4217." value: type: "number" description: "Currency amount as a decimal value." pattern: "^\\d*(.\\d+)?$" display: type: "string" example: "$45.21" description: "Optional currency amount suitable for display, including the\ \ currency symbol." amountType: type: "string" example: "Manufacturing Cost" description: "Optional type describing the nature of the amount." required: - "currency" - "value" ValidateItem: type: "object" description: "Order Entry item Validation response" title: "" properties: itemNumber: type: "string" description: "Line item number" catalogNumber: type: "string" description: "Product catalog number" itemReference: type: "string" description: "Item reference" quantity: type: "integer" format: "int32" description: "Quantity" minimum: 1 requestedDeliveryDate: type: "string" format: "date" example: "2021-05-31" description: "Requested delivery date for this item" advisedDeliveryDate: type: "string" format: "date" example: "2021-05-31" description: "Advised delivery date for this item" listPrice: $ref: "#/definitions/Currency" unitNetPrice: $ref: "#/definitions/Currency" totalNetPrice: $ref: "#/definitions/Currency" discount: type: "string" description: "Discount percentage" bomProduct: type: "string" description: "BOM product" warningMessages: type: "array" description: "Warning messages (possible token translated values)" items: type: "string" required: - "catalogNumber" - "quantity" ValidateResponse: type: "object" description: "Order Entry Validation response" x-examples: {} properties: accountNumber: type: "string" description: "Account number\nThis is the 10-digits account number, including\ \ leading 0" poNumber: type: "string" description: "Order PO number" customerId: type: "string" description: "Customer ID\nThis is the 10-digits customer ID, including leading\ \ 0" contractNumber: type: "string" description: "SE contract number\nThis is the 10-digits contract number, including\ \ leading 0." deliveryService: type: "string" enum: - "Standard" - "Express" - "Special Instruction" description: "3 possible values:\n- \"Standard\" for a standard delivery\n\ - \"Express\" for an express delivery\n- \"Special Instruction\" has to\ \ be used for the \"Dépannage\" use case" releaseDate: type: "string" format: "date" example: "2021-05-31" description: "Release date" requestedDeliveryDate: type: "string" format: "date" example: "2021-05-31" description: "Requested delivery date" customerAddress: $ref: "#/definitions/Address" alternativeDeliveryAddress: type: "boolean" description: "Indicates whether the order will be delivered to the default\ \ address or to a custom address" deliveryAddress: $ref: "#/definitions/Address" comments: type: "string" description: "Comments" surchargePrice: $ref: "#/definitions/Currency" totalFreightPrice: $ref: "#/definitions/Currency" totalTax: $ref: "#/definitions/Currency" totalNetAmount: $ref: "#/definitions/Currency" total: $ref: "#/definitions/Currency" orderEntryItems: type: "array" description: "Order line items" items: $ref: "#/definitions/ValidateItem" warningMessages: type: "array" description: "Warning messages (possible token translated values)" items: type: "string" required: - "accountNumber" - "poNumber" - "customerId" - "deliveryService" - "releaseDate" - "customerAddress" - "alternativeDeliveryAddress" - "deliveryAddress" OrderEntryRequest: type: "object" description: "Order Entry request data (for Validation and submit purpose)" x-examples: {} properties: email: type: "string" description: "Email address of the user placing the order\nThis user must\ \ be registered in mySE and have the permission to place orders." poNumber: type: "string" description: "Order PO number" customerId: type: "string" description: "Customer ID\nThis is the 10-digits customer ID, including leading\ \ 0" contractNumber: type: "string" description: "SE contract number\nThis is the 10-digits contract number, including\ \ leading 0." deliveryService: type: "string" enum: - "Standard" - "Express" - "Special Instruction" default: "Standard" example: "Standard" description: "3 possible values:\n- \"Standard\" for a standard delivery\n\ - \"Express\" for an express delivery\n- \"Special Instruction\" has to\ \ be used for the \"Dépannage\" use case" requestedDeliveryDate: type: "string" format: "date" description: "Requested delivery date" example: "2021-05-31" comments: type: "string" description: "Comments" shipToAddress: $ref: "#/definitions/AddressRequest" orderEntryItems: type: "array" description: "Order line items" items: $ref: "#/definitions/OrderEntryRequestItem" required: - "email" - "poNumber" - "orderEntryItems" OrderEntryRequestItem: type: "object" description: "Order entry item request data" properties: catalogNumber: type: "string" description: "Product catalog number" quantity: type: "integer" format: "int32" description: "Quantity" exclusiveMinimum: false minimum: 1 requestedDeliveryDate: type: "string" format: "date" description: "Requested delivery date for this item" example: "2021-05-31" itemReference: type: "string" description: "Item reference" required: - "catalogNumber" - "quantity" OrderEntryStatus: type: "object" properties: status: type: "string" enum: - "Non applicable" - "Expédiée" - "En cours de traitement" - "En cours de préparation" - "Ouverte" - "Partiellement rejetée" - "Annulée" - "En attente" - "Migrée" - "Livraison suspendue" - "Livrée" - "En cours de modification" SubmitResponse: type: "object" x-examples: example-1: orderRequestDate: "22/08/2020" orderNumber: "25487" poNumber: "My test order" properties: orderRequestDate: type: "string" description: "Date at which the order has been placed" orderNumber: type: "string" description: "SE order number" poNumber: type: "string" description: "Order PO number" required: - "orderRequestDate" - "orderNumber" - "poNumber" ErrorResponse: type: "object" title: "Error Response - OAS2" description: "Error response returned to the consumer when an HTTP error status\ \ has occurred." properties: code: type: "string" example: "MISSING_FIELD or 12345" description: "Service-defined error code which may be numeric or a string.\n\ \nErrors detected by the APIM platform result in the following codes.\n\n\ BAD_REQUEST (for 400)\nUNAUTHORIZED (for 401)\nFORBIDDEN (for 403)\nNOT_FOUND\ \ (for 404)\nGONE (for 410)\nPRECONDITION_FAILED (for 412)\nTOO_MANY_REQUESTS\ \ (for 429)\nINTERNAL_SERVER_ERROR (for 500)\nNOT_IMPLEMENTED (for 501)\n\ \nAny specific service validation errors would replace BAD_REQUEST." userMessage: type: "string" example: "Required field is missing: productSku" description: "Human-readable general description of the error." developerMessage: type: "string" description: "Optional human-readable description of the error details." example: "Product master API ParseException: required tag expected" moreInfo: type: "string" description: "Optional link to error documentation, which has more information\ \ about the error." format: "uri" example: "https://example.com/product-master/v1/error/12345" required: - "code" - "userMessage" securityDefinitions: oauth2: type: "oauth2" flow: "application" scopes: {} tokenUrl: "https://api.qa.se.com/token" description: "For system to system uses cases where the API service does not need\ \ a user context to execute, please use the provided APIM developer credentials\ \ to request a token, then submit the token via the Authorization Bearer header\ \ when calling an API operation.\n\nAfter one hour, a fresh APIM token needs\ \ to be requested." security: - oauth2: [] responses: Common_Oas2_400: description: "Request is invalid and cannot be processed due one or more issues\ \ such as syntax errors, missing required fields, out of range values, conflicting\ \ query parameters, or unknown URI." schema: $ref: "#/definitions/ErrorResponse" examples: Example: code: "BAD_REQUEST" userMessage: "Request is invalid and cannot be processed due one or more issues\ \ such as syntax errors, missing required fields, out of range values, conflicting\ \ query parameters, or unknown URI." developerMessage: "Request content is malformed or exceeded structural limits" Common_Oas2_401: description: "The client is not authorized to perform this request because its\ \ identity has not yet been established, or the token is invalid or has expired." schema: $ref: "#/definitions/ErrorResponse" examples: Example: code: "UNAUTHORIZED" userMessage: "The client is not authorized to perform this request because\ \ its identity has not yet been established, or the token is invalid or\ \ has expired." developerMessage: "Invalid Access Token" Common_Oas2_403: description: "The client does not have permission to perform the requested action\ \ e.g. POST or DELETE." schema: $ref: "#/definitions/ErrorResponse" examples: Example: code: "FORBIDDEN" userMessage: "The client does not have permission to perform the requested\ \ action e.g. POST or DELETE." developerMessage: "Http verb DELETE is not supported for path suffix /installed-products/track" Common_Oas2_404: description: "Requested resource does not exist on the server. It is assumed that\ \ the URI is valid for this type of resource." schema: $ref: "#/definitions/ErrorResponse" examples: Example: code: "NOT_FOUND" userMessage: "Requested resource does not exist on the server. It is assumed\ \ that the URI is valid for this type of resource." developerMessage: "Records not found" Common_Oas2_429: description: "Number of requests has exceeded the client's rate limits." schema: $ref: "#/definitions/ErrorResponse" examples: Example: code: "TOO_MANY_REQUESTS" userMessage: "Number of requests has exceeded the client’s rate limits." developerMessage: "Spike arrest violation" Common_Oas2_500: description: "Requested operation encountered an unexpected server error." schema: $ref: "#/definitions/ErrorResponse" examples: Example: code: "INTERNAL_SERVER_ERROR" userMessage: "Requested operation encountered an unexpected server error." developerMessage: "Target service is unavailable, please try again later."