Voucher

Best practise

How to successfully harvest data using this endpoint:

Fetch locally stored lastReplicationTimestamp if applicaple
Call max endpoint and store MaxTimestamp.
Call updates endpoint with parameters: from = lastReplicationTimestamp, to = MaxTimestamp (and lastoffsetid = nextoffsetid from previous batch)
Call softdeletes endpoint with the same parameters as above. Before deleting locally, ensure that the deleted entity has the highest timestamp
Call harddeletes endpoint with the same parameters as above. Before deleting locally, ensure that the deleted entity has the highest timestamp
Save the stored value from step 2 (MaxTimestamp) as the new lastReplicationTimestamp

Max

This returns the max timestamp for a specific entity in order to know if there are relevant changes.

?> It is possible the reported max timestamp is irrelevant for the client/consumer (i.e. when using a filter with the related endpoints), in which case it would simply trigger an update routine with no changes.

URL : /:organizationid/:wsmid/api/v1/voucher/max

URL Parameters: organizationid=[string] is the ID of the chainbox.io organization.

wsmid=[string] is the APP ID of the WSM application.

Method: GET

Auth required: YES

Permissions required: Basic Auth credentials to the api can be delivered by contacting our support.

Success Response

Condition: If Organization & WSM app exists and the given credentials are correct.

Code: 200 OK

Content example

{
  "offset": "2021-12-01T08:20:16.421Z"
}

Error Responses

Condition: If basic auth header is not present in request or is incorrect.

Code: 401 UNAUTHORIZED

Updates

URL : /:organizationid/:wsmid/api/v1/voucher/:service/updates

URL Parameters: organizationid=[string] is the ID of the chainbox.io organization.

wsmid=[string] is the APP ID of the WSM application.

service=[string] is the name of the Service Endpoint registered in the WSM application settings. Supplying "default" as the service requires no endpoint configuration and will not apply a filter to the result.

Querystring parameters:

to=[date] returns items with a lastupdated value less than or equal to this date.

(optional) from=[date] returns items with a lastupdated value greater than this date. No default value - not supplying a value will omit this condition.

(optional) lastoffsetid=[string] returns items with a documentid greater than this value. This can be used to page through results as the items are sorted by documentid internally. No default value - not supplying a value will omit this condition.

(optional) limit=[int] number of items returned. Default = 1000.

Method: GET

Auth required: YES

Permissions required: Basic Auth credentials to the api can be delivered by contacting our support.

Success Response

Condition: If Organization & WSM app exists and the given credentials are correct.

Code: 200 OK

Content example

{
  "result": [
    {
      "createDate": "2021-06-21T10:30:33.603Z",
      "createdBy": "John Doe",
      "data": {
        "currency": "DKK",
        "exclude": [],
        "excludeGroups": [],
        "excludeProducts": [],
        "id": "ymippn4aj",
        "limitTo": [],
        "limitToGroups": [],
        "limitToProducts": [],
        "log": {},
        "lowerbound": 0,
        "name": "procenter",
        "relationType": "Product",
        "reusable": false,
        "status": 2,
        "type": 1,
        "validFrom": "2021-06-21T10:30:20.706Z",
        "validTo": "2021-06-23T10:30:20.706Z",
        "value": 20,
        "identifier": "0ec003ff-b503-4a92-80ab-62c533394cf2"
      },
      "id": "0ec003ff-b503-4a92-80ab-62c533394cf2",
      "lastUpdated": "2021-06-24T07:47:15.812Z",
      "type": "webshop-management-vouchers"
    }
  ],
  "nextoffsetid": "0ec003ff-b503-4a92-80ab-62c533394cf2"
}

Error Responses

Condition: If basic auth header is not present in request or is incorrect. Code: 401 UNAUTHORIZED

Condition: Referencing an invalid service parameter. Code: 404 NOT FOUND

Soft deletes

Soft deletes are documents from the same collection not matching the service filter. If there is no active filter (e.g. using the "default" service) - an empty result will be returned.

URL : /:organizationid/:wsmid/api/v1/voucher/:service/softdeletes

URL Parameters: organizationid=[string] is the ID of the chainbox.io organization.

wsmid=[string] is the APP ID of the WSM application.

service=[string] is the name of the Service Endpoint registered in the WSM application settings. Supplying "default" as the service requires no endpoint configuration and will not apply a filter to the result.

Querystring parameters:

to=[date] returns items with a lastupdated value less than or equal to this date.

(optional) from=[date] returns items with a lastupdated value greater than this date. No default value - not supplying a value will omit this condition.

(optional) lastoffsetid=[string] returns items with a documentid greater than this value. This can be used to page through results as the items are sorted by documentid internally. No default value - not supplying a value will omit this condition.

(optional) limit=[int] number of items returned. Default = 1000.

Method: GET

Auth required: YES

Permissions required: Basic Auth credentials to the api can be delivered by contacting our support.

Success Response

Condition: If Organization & WSM app exists and the given credentials are correct.

Code: 200 OK

Content example

{
  "result": [
    {
      "id": "0ec003ff-b503-4a92-80ab-62c533394cf2",
      "lastUpdated": "2021-07-09T07:42:50.445Z"
    }
  ],
  "nextoffsetid": "0ec003ff-b503-4a92-80ab-62c533394cf2"
}

Error Responses

Condition: If basic auth header is not present in request or is incorrect. Code: 401 UNAUTHORIZED

Condition: Referencing an invalid service parameter. Code: 404 NOT FOUND

Hard deletes

Hard deletes are documents no longer in the collection.

?> It is possible the returned items are irrelevant for the client/consumer (i.e. when using a filter with the related endpoints). Match with existing IDs when appropriate.

URL : /:organizationid/:wsmid/api/v1/voucher/harddeletes

URL Parameters: organizationid=[string] is the ID of the chainbox.io organization.

wsmid=[string] is the APP ID of the WSM application.

Querystring parameters:

to=[date] returns items with a lastupdated value less than or equal to this date.

(optional) from=[date] returns items with a lastupdated value greater than this date. No default value - not supplying a value will omit this condition.

(optional) lastoffsetid=[string] returns items with a documentid greater than this value. This can be used to page through results as the items are sorted by documentid internally. No default value - not supplying a value will omit this condition.

?> Note that documentid and item id do not match. Only supply values provided by the endpoint though nextoffsetid.

(optional) limit=[int] number of items returned. Default = 1000.

Method: GET

Auth required: YES

Permissions required: Basic Auth credentials to the api can be delivered by contacting our support.

Success Response

Condition: If Organization & WSM app exists and the given credentials are correct.

Code: 200 OK

Content example

{
  "result": [
    {
      "id": "0ec003ff-b503-4a92-80ab-62c533394cf2",
      "lastUpdated": "2021-12-06T09:40:08.499Z"
    }
  ],
  "nextoffsetid": "61adda78880433063295a467"
}

Error Responses

Condition: If basic auth header is not present in request or is incorrect.

Code: 401 UNAUTHORIZED

Get status

This returns the voucher status for a specific voucher.

?> Possible values include: Unused, Added, Used

URL : /:organizationid/:wsmid/api/v1/voucher/getstatus/:documentid

URL Parameters: organizationid=[string] is the ID of the chainbox.io organization.

wsmid=[string] is the APP ID of the WSM application.

documentid=[string] is the Document ID of the voucher.

Method: GET

Auth required: YES

Permissions required: Basic Auth credentials to the api can be delivered by contacting our support.

Success Response

Condition: If Organization & WSM app exists and the given credentials are correct.

Code: 200 OK

Content example

Used

Error Responses

Condition: If basic auth header is not present in request or is incorrect. Code: 401 UNAUTHORIZED

Condition: Invalid voucher refenrence. Code: 404 NOT FOUND

Update status

This updates the voucher status for a specific voucher.

?> Possible values include: Unused, Added, Used

URL : /:organizationid/:wsmid/api/v1/voucher/updatestatus/:documentid

URL Parameters: organizationid=[string] is the ID of the chainbox.io organization.

wsmid=[string] is the APP ID of the WSM application.

documentid=[string] is the Document ID of the voucher.

POST Body Parameters: VoucherStatus=[string (Unused|Added|Used)] is the new status for the voucher.

Method: POST

Auth required: YES

Permissions required: Basic Auth credentials to the api can be delivered by contacting our support.

Success Response

Condition: If Organization & WSM app exists and the given credentials are correct.

Code: 200 OK

Content example

No response data is returned.

Error Responses

Condition: If basic auth header is not present in request or is incorrect. Code: 401 UNAUTHORIZED

Condition: Invalid payload. Code: 400 BAD REQUEST