V2 API Documentation
The Traceability Blockchain exposes its blockchain network for software developers via an Application Programming Interface (API), so developers can interact in a programmatic way with the Traceability Blockchain. This document is the official reference for that functionality.
The Traceability Blockchain API allows operations that are familiar to most application programmers supporting supply chain operations to a blockchain structure suitable for traceability. Most operations related to traceability within the supply chain can be classified into one of two categories. Transfer Functions are used to change the location or ownership of an asset from one address to another without changing the form of the product. Tranformation Functions are used to change the product from one form to another. Tranformation includes all operations where the resulting product receives a new GTIN, UPC, or LOT Number. This can include repackaging a product or manufacturing a product from one or more ingredients. Transformation functions related to a product may occur all at once or be spread out over a period of time.
The API also provides endpoints to trace products, query traceability data, perform maintenance, an provide system and user metrics.
Each physical location where a product may be shipped or stored must be identified by a blockchain address. The address is a unqiue 32 byte hexadecimal number that is generated based on the identifier's physical location on earth. If multiple businesses share a physical location, the blockchain address can be generated by including the business' GS1 Global Location Number (GLN).
When shipping a product to a location where the blockchain address is unknown the API calculates the address automatically so long as a valid physical address is passed to the API endpoint.
API Authentication is uses using a client key and secret key pair which is directly related to the blockchain address. Users managing multiple locations must maintain a client key and secret key for each location they manage.
API users must register with the system in order to receive their client and secret key pair for their blockchain address.
A transfer function is used to change ownership of an asset or move its location from one blockchain address to another. One or more assets may be transferred using a single call to the API endpoint. The transfer of a product from one location to another DOES NOT assume all of the product in the GTIN/LOT combination has been transfered. This allows products to be easily tracked across multiple shipment destinations.
A transformation function is used to transform a product from one or more input products to new resulting product. The ownership or location of the item does not change when transformation functions are executed. When product is used as an input to another product, the new product will be returned for and product tracking that includes the input product.