Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Return call and response #29

Open
wants to merge 8 commits into
base: master
Choose a base branch
from
Open

Return call and response #29

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
1462edc
New endpoints for returns
MichaelaVesterlund Jul 14, 2023
e1cd240
Revert "New endpoints for returns"
MichaelaVesterlund Jul 14, 2023
eda52ca
New endpoint for returns
MichaelaVesterlund Jul 14, 2023
b47ca99
Updated text
MichaelaVesterlund Jul 14, 2023
9b9097e
Description updated on return call. Rename of rule. Rename of property.
MichaelaVesterlund Sep 13, 2023
fef18ce
Description updated on return call. Rename of rule. Rename of property
MichaelaVesterlund Sep 13, 2023
8ab5104
Removed typo
MichaelaVesterlund Sep 15, 2023
8b6d4a5
Rows in both call and response. Updated response with more info on br…
MichaelaVesterlund Mar 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions Return Response.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"]
}]
}
23 changes: 23 additions & 0 deletions Return.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
}]

}
118 changes: 118 additions & 0 deletions readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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](#3-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.
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be #4


Samples files are available via GitHub together with the most up to date information.

# 1. Order
Expand Down Expand Up @@ -437,6 +439,122 @@ 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: [{
quantity: 2,
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| Return rules determined by the reseller and verified by the supplier |
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like the comment is a copy/paste error from the previous line

| rows.quantity | int | x | Return quantity. Either licensekeys or quantity has to be specified. |
| 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, 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 |
| --- | --- |
| unAssigned | Return allowed only on licenses that are not assigned |
| notUsed | Return allowed only if the license has not been used |
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Regading the rules:

If more than one rule is sent, does this mean that it is enough for a license to fulfill only one of the rules, or does it mean that all rules must be fulfilled for the license to be returnable (should the rules be combined with AND or OR)?

What does the specific rules actually mean? Is "notUsed" a license that has never been assigned to a user? Can we change the name of "unAssigned" to "notAssigned" if the meaning is that the license currently isn't assigned to a user?

Is there a need for more rules? Maybe we can discuss this at the next meeting, and add more later?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great questions! I think it should be AND? But that can be discussed, and also what kind of rules do we need? Would be good to get more feedback from other suppliers as well.


## 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",

licenses: [{
orderRowId: "64b879b1-1fdc-4a42-ae7c-b4f9b287a2cc",
articleNumber: "9789140123456",
status: "Ok",
reason: "",
licenseKey:"235572d0-a26d-4975-97f4-72e4734ff341",
brokenRules:[]dvs.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Typo

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

```

| Property | Type | Mandatory | Description |
| --- | --- | --- | --- |
| clientId | string | x | Webshop id, e.g. goteborgsregionen.se |
| serviceProviderId | string | x | Supplier id, t.ex. nok.se |
| licenses | array | x | One response per license |
| licenses.orderRowId | string | x | Row ID, used to match return replys with the response |
| licenses.articleNumber | string | x | Article number of the product being returned |
| licenses.status | string | x | error, ok, rulesBroken. See value list below |
| licenses.reason | string | | Used with status NotOk |
| licenses.licenseKey | string | | Licensekey |
| brokenRule.brokenRules | array | | Array with strings. Can be the same or a subset of the rules sent in the return call. See value list above |
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should be "licenses.brokenRules"


### 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 can be returned. |
| RulesBroken | The license is NOT returned because there are one or more rules broken. |
| Returned | This license is returned. |

## 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”.
Expand Down