Return call and response

.gitignore

@@ -0,0 +1,5 @@
+################################################################################
+# This .gitignore file was automatically created by Microsoft(R) Visual Studio.
+################################################################################
+
+/.vs

Return Response.js

@@ -0,0 +1,22 @@
+Example of a response to a resellers return to its digital warehouse.
+
+{
+	clientId: "gleerups.se",
+	serviceProviderId:"goteborgsregionen.se",
+
+	licenses: [{
+		orderRowId: "64b879b1-1fdc-4a42-ae7c-b4f9b287a2cc",
+		articleNumber: "9789140123456",
+		status: "Ok",
+		reason: "",
+		licenseKey:"235572d0-a26d-4975-97f4-72e4734ff341",
+		brokenRules:[]
+	},{
+		orderRowId: "64b879b1-1fdc-4a42-ae7c-b4f9b287a2cc",
+		articleNumber: "9789140123456",
+		status: "NotOk",
+		reason: "Returns not allowed after 6 months.",
+		licenseKey:"61893cba-5572-458b-ba91-53320be8bb44",
+		brokenRules:["unassigned"]
+	}]
+}

Return.js

@@ -0,0 +1,23 @@
+Example of a return from the reseller's customer to the reseller. The license is stored in the reseller's digital warehouse that is provided by the supplier.
+
+{
+    clientId: "goteborgsregionen.se",
+    serviceProviderId: "gleerups.se"
+
+    account: {
+            id: "GRAB",
+            identitySource: "client",
+            schoolUnitCode: "456781",
+            organizationNumber: "2120001355",
+            name: "G�teborgs stad",
+            rules: ["unassigned", "notUsed"]
+    },
+
+    rows: [{
+        quantity: null,
+        licenseKeys: ["235572d0-a26d-4975-97f4-72e4734ff341", "61893cba-5572-458b-ba91-53320be8bb44"],
+        articleNumber: "9789140123456",
+	    orderRowId: "64b879b1-1fdc-4a42-ae7c-b4f9b287a2cc"
+    }]
+
+}

readme.md

@@ -14,6 +14,8 @@ FYI: Some terms have the Swedish name in parenthesis and the file names of the s
 
 **[3. Statistics](#3-statistics)**: A license portal can fetch data from the producers and present the customer with how many licenses that have been acquired and how many that are actually being used. The data includes information on when the licenses were purchased and when they expire.
 
+**[4. Return](#4-return)**: Returns from the reseller's customers to the reseller. The licenses is stored in the reseller's digital warehouse that is provided by the supplier.
+
 Samples files are available via GitHub together with the most up to date information.
 
 # 1. Order
@@ -437,6 +439,144 @@ Call for getting an update on a certain license on a certain school.
 
 Call for getting licenses and status update for either an entire organisation (Statistik Metod 2 Anrop med organisationsnummer.js) or school unit code (Statistik Metod 2 Anrop med skolenhetskoder.js). 
 
+# 4. Return
+
+This call is made when a reseller's customer wants to create a return and the reseller has the ambition to sell the license to another customer. The license is stored in a 'digital warehouse' provided by the supplier.
+
+## Call from webshop
+
+```javascript
+{
+    clientId: "goteborgsregionen.se",
+    serviceProviderId: "gleerups.se",
+
+    account: {
+            id: "GRAB",
+			identitySource: "client",
+			schoolUnitCode: "456781",
+            organizationNumber: "2120001355",
+            name: "Göteborgs stad",
+            rules: ["unassigned", "notUsed"]
+    },
+
+    rows: [{
+		licenseKeys: ["235572d0-a26d-4975-97f4-72e4734ff341", "61893cba-5572-458b-ba91-53320be8bb44"],
+        articleNumber: "9789140123456",
+	    orderRowId: "64b879b1-1fdc-4a42-ae7c-b4f9b287a2cc"
+    }]
+
+}
+```
+
+| Property | Type | Mandatory | Description |
+| --- | --- | --- | --- |
+| clientId | string | x | Webshop id, E.g. goteborgsregionen.se |
+| serviceProviderId | string | x | Supplier id, E.g. nok.se |
+| account | object | x | Principal organization, commonly a school unit |
+| account.id | string | x | Customer ID, e.g. account number |
+| account.identitySource | string | x | Type of id. E.g. if it is the account number of the customer it should be set to "client" |
+| account.schoolUnitCode | string |  | School unit code |
+| account.organizationNumber | string | x | Organization number |
+| account.name | string | x | Name of the school unit |
+| account.rules | array | | Return rules determined by the reseller and verified by the supplier |
+| rows | array | x | Rows that is going to be returned. A row represent a whole or a subset of a purchase row. |
+| rows.licenseKeys | array | x | Array of licensekeys that is being return. Either licensekeys or quantity has to be specified. |
+| rows.articleNumber | string | x | Article number of the product being returned |
+| rows.orderRowId | number | x | Row ID, that is used in the purchase call, is used to match return replys with the response|
+
+
+### Value list for Return - identitySource
+| identitySource | Description |
+| --- | --- |
+| client | Webshop prorietary id |
+| EGIL | EGIL-client id |
+| Google | Google-id |
+| Microsoft | Microsoft-id |
+
+### Value list for Return - rules
+| rules | Description |
+| --- | --- |
+| notAssigned | Return allowed only on licenses that are not assigned |
+| notUsed | Return allowed only if the license has not been used |
+| expired | Return allowed only if the license has not been expired |
+
+
+## Return reply
+
+The supplier is expected to reply directly. A return row is either a success or not. Partially succeded rows are not allowed, i.e. if any license on a row does not go well, no licenses on that row is not returned even if possible. The reseller can however se the status of each license to determine which one needs to be changed. For instance if there is a rule that says a license must be unassigned, the reseller can help their customer unassigned it and later retry the return. 
+
+```javascript
+{
+	clientId:"gleerups.se",
+	serviceProviderId:"goteborgsregionen.se",
+
+	rows: [{
+        licenseKeys: [
+        		{
+					key: "61893cba-5572-458b-ba91-53320be8bb44",
+	        		status: "Ok"
+	        	}
+	        	{
+					key: "235572d0-a26d-4975-97f4-72e4734ff341",
+	        		status: "rulesBroken",
+					brokenRules: [
+						{
+							rule: "notAssigned",
+							userId: [email protected]
+						},
+						{
+							rule: "notUsed",
+							date: "YYYY-MM-DD TT:MM:SS"
+						},
+						{
+							rule: "expired",
+							date: "YYYY-MM-DD TT:MM:SS"
+						}]
+	        	},
+	        	"27f03df5-5495-4a3b-a775-1ac1578ac368" : {
+	        		status: "NotOk",
+					reason: "Some other reason",
+	        	}, 
+        	],
+        articleNumber: "9789140123456",
+	    orderRowId: "64b879b1-1fdc-4a42-ae7c-b4f9b287a2cc"
+    }]
+}
+
+```
+
+| Property | Type | Mandatory | Description |
+| --- | --- | --- | --- |
+| clientId | string | x | Webshop id, e.g. goteborgsregionen.se |
+| serviceProviderId | string | x | Supplier id, t.ex. nok.se |
+| rows | array | x | Answer with the same rows and licenses as the call |
+| rows.orderRowId | string | x | Row ID, used to match return replys with the response |
+| rows.articleNumber | string | x | Article number of the product being returned |
+| rows.licenseKeys | array | x | Array of the license keys that were in the call|
+| rows.licenseKeys.key | string | x | License key |
+| rows.licenseKeys.status | string | x | error, ok, rulesBroken. See value list below |
+| rows.licenseKeys.reason | string | | Used with status NotOk |
+| rows.licenseKeys.brokenRules | array | | Array with objects of broken rules and can contain more info depending on the rule broken. Can be the same or a subset of the rules sent in the return call. See value list above |
+| rows.licenseKeys.rule | string | x | The broken rule |
+| rows.licenseKeys.userId | string | x | Is mandatory for rule 'notAssigned', id for the user using the key |
+| rows.licenseKeys.date | date | x | Is mandatory for rule 'notUsed', start date of using the article. Is also mandatory for expired, date of when the article was expired.|
+
+
+
+
+### Value list return reply
+| Status | Description |
+| --- | --- |
+| NotOk | The supplier does not accept this return, description of the reason is provided in reason. |
+| Ok | This license is returned. |
+| RulesBroken | The license is NOT returned because there are one or more rules broken.  |
+
+## Sample files
+
+### Return.js
+Sample file shows a return that has two licenseKeys that the customer wants to return. The supplier validates the return by its own rules and those provided by the reseller.
+Return reply (Return Response.js) shows that one license in Ok to return, but is not because the second row has two validation errors. One is the reseller rule is broken and the second is a supplier rule i broken.
+
 # Dates
 
 Should be formated according to ISO 8601 (YYYY-MM-DD) “2020-03-30”.