here is a detailed walk-through for these functionalitie, with examples:



Here is a quick how-to on items uploading, product search, and bidding with our API. For the purpose of this demo, we assume these two users are registered in the platform (which is the case) :

Username : testuser1
Password : 456789
Public key : MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEBKmYzcU5rcQk85vynuwzgrzQjVsX6tIf6dHSGRm9aRIrdYfjANhD3Mmr7WtZOgol/SSInC/c88vs8Ywioxd1Aw==

Username : testuser2
Password : 456789
public key : MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAELLR99w0PTlbvTjiorSN/Q7MeR9kAxmRBXqJUiW204qNs8Njzbjlm+9D0//mjKfUnUhNBUMl2CvE726ewpi4cfg==


1) Item uploading

For a user to upload an item in the marketplace, he need to be admin of a marketplace shop. For him to become so, he can create a shop (and will automatically be admin of this shop), or be granted admin rights by a already existing shop admin. Here we assume he create a shop :

For a user to create a shop, he sould call the /ledger/{channel}/{chaincode}/{function} endpoint in POST mode, meaning he will trigger a chaincode function that will write into the ledger.

As decribed here : https://api.plastictwist.com/cc_docs/ , the "marketplace" chaincode on channel "ptwist" have a function "new_shop" :

Parameters :

   1. The shop name
   2. The ERC20 address to transfer money to when a purchase occures

Payload :
With a successful shop creation, the function returns the new shop ID.

The parameters are passed in the form of an array in the "params" parameter to the API, with pipes (|) as value separator.

Knowing all that, here is the curl command to create a shop name "My awesome shop" for testuser1 :

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-request-username: testuser1' --header 'X-request-password: 456789' --header 'params: My awesome Shop|MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEBKmYzcU5rcQk85vynuwzgrzQjVsX6tIf6dHSGRm9aRIrdYfjANhD3Mmr7WtZOgol/SSInC/c88vs8Ywioxd1Aw==' 'http://api.plastictwist.com/ledger/ptwist/marketplace/new_shop'

This request returns this json :

{
  "status": "200",
  "payload": "2aea532a1b39238024a047da52096ef048bfcca6c06d892c4964c5c7734867aa",
  "message": ""
}

The status is 200 so everything worked fine, the payload represents a shopID, that will be needed to then post items in this shop.

If the item uploading does not follow the shop creation, there is a way to retreive any user shop list with this call to "query_data" function, which allows to perform a mango query on the ledger, here it is, for information:

Mango query :

{
   "selector": {
      "DocType": "Shop",
      "Users": {
         "$elemMatch": {
            "$eq": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEBKmYzcU5rcQk85vynuwzgrzQjVsX6tIf6dHSGRm9aRIrdYfjANhD3Mmr7WtZOgol/SSInC/c88vs8Ywioxd1Aw=="
         }
      }
   }
}

Call to query data :

curl -X GET --header 'Accept: application/json' --header 'X-request-username: testuser1' --header 'X-request-password: 456789' --header 'params: {"selector":{"DocType":"Shop","Users":{"$elemMatch":{"$eq":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEBKmYzcU5rcQk85vynuwzgrzQjVsX6tIf6dHSGRm9aRIrdYfjANhD3Mmr7WtZOgol/SSInC/c88vs8Ywioxd1Aw=="}}}}' 'http://api.plastictwist.com/ledger/ptwist/marketplace/query_data'

Returns :

{
  "status": "200",
  "response": [
    {
      "Key": "2aea532a1b39238024a047da52096ef048bfcca6c06d892c4964c5c7734867aa",
      "Record": {
        "DocType": "Shop",
        "ERC20Address": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEBKmYzcU5rcQk85vynuwzgrzQjVsX6tIf6dHSGRm9aRIrdYfjANhD3Mmr7WtZOgol/SSInC/c88vs8Ywioxd1Aw==",
        "Items": null,
        "Name": "My awesome Shop",
        "Raw": null,
        "Users": [
          "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEBKmYzcU5rcQk85vynuwzgrzQjVsX6tIf6dHSGRm9aRIrdYfjANhD3Mmr7WtZOgol/SSInC/c88vs8Ywioxd1Aw=="
        ]
      }
    }
  ],
  "message": ""
}

So we can see the "Key" field corresponds to the shop id we created earlier, i will come back to the query_data function later for further explanations.


So now we have our shop id, which is : 2aea532a1b39238024a047da52096ef048bfcca6c06d892c4964c5c7734867aa

What we now need to do is to call the "shop_add_item" function, to create an item.

This function require those parameters:
Parameters :

    1 . The shop ID
    2 . The item json (ex: { "Bidable": false, "Pictures": [ "picA", "picB" ], "Shipping": [ { "To": "anywhere", "Fee": 12 }, { "To": "fr", "Fee": 3 } ], "Name": "My new item", "Detail": "This is a wonderful item, really !", "Price": 42, "Quantity": 314, "Duration": 604800, "Weight": 45, "Latitude": 48.9070592, "Longitude": 2.3371776 } )

Payload :
With a successful operation, the function returns the new item ID.

So our first parameter will be our shop id, then a json description of our item, which will be this one :

{
  "Bidable": true,
  "Pictures": [
    "https://assets.pinshape.com/uploads/image/file/139445/container_spiral-vase-3d-printing-139445.jpg"
  ],
  "Shipping": [
    {
      "To": "anywhere",
      "Fee": 12
    },
    {
      "To": "fr",
      "Fee": 3
    }
  ],
  "Name": "3d printed vase",
  "Detail": "Lorem ipsum dolores sin amet...",
  "Price": 2,
  "Quantity": 1,
  "Duration": 168,
  "Weight": 45,
  "Latitude": 48.9070592,
  "Longitude": 2.3371776
}

Meaning the item will be a biddable item, have said characteristics desribed by the json etc, the duration is specified in hours, 168 hours is corresponding to a week (7x24 hours)

Here is the call in curl :

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-request-username: testuser1' --header 'X-request-password: 456789' --header 'params: 2aea532a1b39238024a047da52096ef048bfcca6c06d892c4964c5c7734867aa|{"Bidable":true,"Pictures":["https://assets.pinshape.com/uploads/image/file/139445/container_spiral-vase-3d-printing-139445.jpg"],"Shipping":[{"To":"anywhere","Fee":12},{"To":"fr","Fee":3}],"Name":"3d printed vase","Detail":"Lorem ipsum dolores sin amet...","Price":2,"Quantity":1,"Duration":168,"Weight":45,"Latitude":48.9070592,"Longitude":2.3371776}' 'http://api.plastictwist.com/ledger/ptwist/marketplace/shop_add_item'

Response :

{
  "status": "200",
  "payload": "26b9627a57ab138a8aef5231b044f5e442cb544866468ca93e4160ede213d0f1",
  "message": ""
}


Status is 200, payload is the item id in the marketplace. It's done, our item is online !



2) Search

Now, lets say we are testuser2, and want to search among marketplace items, for a vase.

We will make use of the query_data function, that allows us to query the ledger using mango query, for information, here is the data model :

Shops:

    Name         string
    Users        []string
    Items        []string
    Raw          []string
    DocType      string //Will be "Shop"
    ERC20Address string

Items:

    Biddable     bool
    DocType      string //Will be "ShopItem"
    Pictures     []string
    Shipping     []ShippingFee
    Name         string
    Detail       string
    Price        uint64
    Quantity     uint64
    MinQuantity  uint64
    CreationDate uint64
    ExpireDate   uint64
    ShopId       string
    BidList      []string
    Winner       string
    Latitude     float64
    Longitude    float64
    Weight       int

Bids:

    ItemId     string
    Price      uint64
    DocType    string //Will be "Bid"
    Owner      string
    ShownPrice uint64
    Timestamp  uint64

Sales:

    User      string
    ItemId    string
    ShopId    string
    Price     uint64
    Quantity  uint64
    StateShop uint8
    StateUser uint8
    DocType   string //Will be "Sale"


And here is more infos about mango query operators and syntax :
https://docs.mongodb.com/manual/reference/operator/query/

So, with this information, we can constuct a query that returns the items with a name matching a particular regex, ".*vase.*" for example here.

Here is the mango query :

{
   "selector": {
      "DocType": "ShopItem",
      "Name": {
         "$regex": ".*vase.*"
      },
      "ExpireDate": {
         "$gt": 1554456813
      }
   }
}

Notice that you need to manually input a "ExpireDate" field check, ensuring it is greater than current timestamp, for the query to not return expired items.

Here is the curl command that performs our search :

curl -X GET --header 'Accept: application/json' --header 'X-request-username: testuser2' --header 'X-request-password: 456789' --header 'params: {"selector":{"DocType":"ShopItem","Name":{"$regex":".*vase.*"},"ExpireDate":{"$gt":1554456813}}}' 'http://api.plastictwist.com/ledger/ptwist/marketplace/query_data'

Response :


{
  "status": "200",
  "response": [
    {
      "Key": "26b9627a57ab138a8aef5231b044f5e442cb544866468ca93e4160ede213d0f1",
      "Record": {
        "BidList": null,
        "Biddable": true,
        "CreationDate": 1554456251,
        "Detail": "Lorem ipsum dolores sin amet...",
        "DocType": "ShopItem",
        "ExpireDate": 1555061051,
        "Latitude": 48.9070592,
        "Longitude": 2.3371776,
        "MinQuantity": 0,
        "Name": "3d printed vase",
        "Pictures": [
          "https://assets.pinshape.com/uploads/image/file/139445/container_spiral-vase-3d-printing-139445.jpg"
        ],
        "Price": 2,
        "Quantity": 1,
        "Shipping": [
          {
            "Fee": 12,
            "To": "anywhere"
          },
          {
            "Fee": 3,
            "To": "fr"
          }
        ],
        "ShopId": "2aea532a1b39238024a047da52096ef048bfcca6c06d892c4964c5c7734867aa",
        "Weight": 45,
        "Winner": ""
      }
    }
  ],
  "message": ""
}

Here is the list of items corresponding to our search, only one in this case, note the "Key" field is the item id

3 ) Bidding

Now for the bidding functionality, let's assume our testuser2 want to bid on this vase he found by searching, he have to call the "make_bid" function, described here :

Parameters :

    Bid submission json (ex: { "ItemId": "ER63H...", "Price": 42 } )

Payload :
With a successful bidding, the functions returns the bid ID.

The json sent as parameter contains ItemId, the identifier of the item our user want to bid on, and the Price he is willing to pay.

In our case, let's make him bid 10 :

{"ItemId" : "26b9627a57ab138a8aef5231b044f5e442cb544866468ca93e4160ede213d0f1", "Price" : 10 }

Curl call :

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-request-username: testuser2' --header 'X-request-password: 456789' --header 'params: {"ItemId" : "26b9627a57ab138a8aef5231b044f5e442cb544866468ca93e4160ede213d0f1", "Price" : 10 }' 'http://api.plastictwist.com/ledger/ptwist/marketplace/make_bid'

Response :

{
  "status": "200",
  "payload": "f4baa07efafc8e23308e7ddb991229c9188ea9aa1db7f663468da2355d3d4a54",
  "message": ""
}

The returned payload is the bid Id.

Note that now if we run again our search command, we now get this result :

{
  "status": "200",
  "response": [
    {
      "Key": "26b9627a57ab138a8aef5231b044f5e442cb544866468ca93e4160ede213d0f1",
      "Record": {
        "BidList": [
          "f4baa07efafc8e23308e7ddb991229c9188ea9aa1db7f663468da2355d3d4a54"
        ],
        "Biddable": true,
        "CreationDate": 1554456251,
        "Detail": "Lorem ipsum dolores sin amet...",
        "DocType": "ShopItem",
        "ExpireDate": 1555061051,
        "Latitude": 48.9070592,
        "Longitude": 2.3371776,
        "MinQuantity": 0,
        "Name": "3d printed vase",
        "Pictures": [
          "https://assets.pinshape.com/uploads/image/file/139445/container_spiral-vase-3d-printing-139445.jpg"
        ],
        "Price": 3,
        "Quantity": 1,
        "Shipping": [
          {
            "Fee": 12,
            "To": "anywhere"
          },
          {
            "Fee": 3,
            "To": "fr"
          }
        ],
        "ShopId": "2aea532a1b39238024a047da52096ef048bfcca6c06d892c4964c5c7734867aa",
        "Weight": 45,
        "Winner": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAELLR99w0PTlbvTjiorSN/Q7MeR9kAxmRBXqJUiW204qNs8Njzbjlm+9D0//mjKfUnUhNBUMl2CvE726ewpi4cfg=="
      }
    }
  ],
  "message": ""
}

The bid is present in Bidlist field, the winner is testuser2 public key, and the price has increased. (not to ten but previous price + 1, since the bindding mechanism works the same way as ebay works)