Foodledger Blockchain API

Foodledger Blockchain API

The FoodLedger public blockchain API provides an easy to use interface for any system to post traceability data to the Blockchain. The API provides a REST API interface for posting and reading data from the blockchain that matches the processes in the Food Processing and Distribution industries. The food ledger API makes it easy for software products to comply with Produce Traceability Initiative (PTI) Phase I and Phase II traceability.

API Endpoints

API Endpoints

There are several API endpoints used to interface with the Blockchain. Basic API endpoints are designed for full integration with the blockchain where the user maintains blockchain identifiers within their application. Advanced API endpoints allow systems to interface with the Blockchain without any knowledge of Blockchain internal structures.

  Basic Functions  
/transfer Transfer an product from one blockchain address to another. Send Blockchain Address
Recieve Blockchain Address
GTIN
Lot or Serial #
/transform Transform an asset from to a new asset from ingredients. Also used to create a new asset without inputs or add new inputs to an existing asset. Blockchain Address
GTIN
Lot or Serial #
Optional Data
List of Ingredients (GTIN/Lot)
/trace Trace an asset forward or backwards and return a JSON array. Blockchain Address
GTIN
Lot or Serial #
Direction (0 both, 1 forward, 2 backward)
/scan Scan and receive all asset changes for a list of addresses from a starting block. This function is used when products are transferred across different systems using the blockchain. List of Blockchain Addresses
Starting Height
  Advanced Functions  
/receive Receive a shipment of products or ingredients. Receiver Physical or Blockchain Address
Sender Physical Address
Transport Information (GSIN/PRO Number)
List of Items Received (GTIN/Lot Combinations)
/produce Create a product from a list of ingredients or add ingredients to an existing batch. Creator Physical or Blockchain Address
GTIN of the Batch/Product
Lot/Batch Number of the Batch/Product
List of Ingredients (GTIN/Lot Combinations)
/package Package a batch of product to new packaging or repackage existing products. Packager Physical or Blockchain Address
GTIN of the Packaged Product
Lot or Serial # of the Packaged Product
List of one or more Input Batches or Products
/ship Ship one or more products. Sender Physical or Blockchain Address
Receiver Physical Address
Transport Information (GSIN/PRO Number)
List of Items Shipped (GTIN/Lot Combinations)

Foodledger API Documentation

Foodledger 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.

Overview

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.

Blockchain Addresses

Blockchain Addresses

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.

Authentication

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.

Transfer Functions

Transfer Functions

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.

Transformation Functions

Transformation Functions

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.