Blockchain Asset Transfer Functions

Within the blockchain, all product inventory is considered Blockchain assets. Every GTIN/Lot # combination at any location is a seperate blockchain asset linked back to the transfers or ingredients that created it. The blockchain asset functions allow users to transfer (ship) an asset from one location to another. If your goal is to manufacture, package, or transform a product use the Transform API endpoint. (/v2/transform).

How it Works

The transfer of an asset from one location to another creates a new asset owned by the receiving blockchain address linked back to the asset owned by the shipper's blockchain address. Since each blockchain transaction has inputs and outputs, the input to the asset received by the owner is output of the asset that was shipped. Since a quantity of an asset can be divided and shipped to multiple locations, the originating asset is not removed from the shipper.

In the blockchain, the current state of an asset is the data contained in the last transaction that affected it. Each time an operation affects an asset, a blockchain transaction is created that updates inputs, outputs, and data storing it in the new transaction.

Request / Response Formats

All Blockchain APIs support an optional return format parameter format=json. Note that json is the default response format. but xml is also available. Some endpoints also support a simple txt format.

All Blockchain APIs support jsonp which is the json format with a callback specified, such as:

format=json&callback=*callback_method*
  • All API requests should be against the domain api.traceabilityblockchain.io or api-ssl.traceabilityblockchain.io (see examples).

  • HTTP Response Status Code is 200 on all valid response in json and xml formats. In json and xml responses, the status_code and status_txt values indicate whether a request is well formed and valid.

  • For txt format calls, the HTTP Response Status Codes are used to indicate a problem with the request, rate limiting, or other errors. The response body will be equivalent to status_txt in json and xml calls for all non 200 response codes.

  • The status_code is 200 for a successful request, 403 when rate limited, 503 for temporary unavailability, 404 to indicate not-found responses, and 400 for all other invalid requests or responses.

  • status_txt will be a value that describes the nature of any error encountered. Common values are RATE_LIMIT_EXCEEDED, MISSING_ARG_%s to denote a missing URL parameter, and INVALID_%s to denote an invalid value in a request parameter (where %s is substituted with the name of the request parameter).

  • If the status_code is not 200, only status_code and status_txt are guaranteed to be present and valid.

Example Outputs:

  • json { "status_code": 200, "status_txt": "OK", "data" : ... }
  • json { "status_code": 400, "status_txt": "MISSING_ARG_LOGIN", "data" : null }
  • json { "status_code": 403, "status_txt": "RATE_LIMIT_EXCEEDED", "data" : null }
  • json { "status_code": 500, "status_txt": "UNKNOWN ERROR", "data" : null }
  • json { "status_code": 503, "status_txt": "TEMPORARILY_UNAVAILABLE", "data" : null }
  • jsonp callback_method({ "status_code": 200, "status_txt": "OK", "data" : ... })
  • xml

    <?xml version="1.0" encoding="UTF-8"?>
    <response>
         <status_code>200</status_code>
         <status_txt>OK</status_txt>
         <data>
             ...
         </data>
    </response>