Receive a Product or Shipment

Use this endpoint to receive a product or shipment from a vendor or other location. This API can be used both when the vendor has posted the transfer to the blockchain or they have not. The "ship to" location used in the physical blockchain address attached to the API key.

When receiving a full shipment the shipment must exist on the traceability blockchain and you must have the shipment id identifying the shipment.

Outcome

The result of the API is to create an asset at the receiving location referenced by the GTIN and LOT of the item received. The primary input to the asset is the asset owned by the shipping location referenced by the same GTIN and LOT. If a shipment id is provided, an input to the received asset is a shipment asset referenced by the unique shipment id. A third input is created from a GTIN data asset that allows assets to be tracked for all LOTs in a GTIN.

Endpoint

https://tracapi.com/api.v2/receive/

Fields/Parameters

Fields/Parameter Value
auth_key Your api key "blockchain address:secret key" assigned for the location receiving the product Required
addressThe street address of the location shipping the product. Required
suiteThe suite number of the shipper if the location is a multi-tenant location. Optional
cityThe city the shipper is located. Required
stateThe state where the shipper is located. Required
zipThe zip or postal code where the shipper is located. Required
glnThe GS1 Global Location Number if provided by shipper. Optional
gtin The globally unique item number of the product. Usually GTIN or UPC code. Required
lot Lot number, batch number, or serial number of the product. Required
data (JSON Object) Optional data related to the item, purchase order, shipment that will be returned in a trace if included. Data must be formatted as a JSON object. Optional
shipment_id The unique identifier of the shipment. Usually PRO number or GSIN. Optional but necessary for tracing products by shipment. Optional
shipment_data (JSON Object) Optional data related to the transport of the product that can be returned in a trace. Data must be formatted as a JSON object. Optional
documents (JSON Array) A list of existing documents to be linked to the transaction. Optional

Test it

Sample Code - PHP/Curl

<?php

$auth_key=$_POST['auth_key'];
$address=$_POST['address'];
$suite=$_POST['suite'];
$city=$_POST['city'];
$state=$_POST['state'];
$zip=$_POST['zip'];
$gln=$_POST['gln'];
$gtin=$_POST['gtin'];
$lot=$_POST['lot'];
$data=$_POST['data'];
$shipment_id=$_POST['shipment_id'];
$shipment_data=$_POST['shipment_data'];

//URL of the endpoint.
$url = 'https://tracapi.com/api.v2/receive/';

//Create an array of POST data to be sent to the endpoint.
$fields = array(
'auth_key' => $auth_key,
'address' => $address,
'suite' => $suite,
'city' => $city,
'state' => $state,
'zip' => $zip,
'gln' => $gln,
'lot' => $lot,
'data' => $data,
'shipment_id' => $shipment_id,
'documents' => $documents,
'shipment_data' => $shipment_data);

//url-ify the data for the POST
foreach($fields as $key=>$value) { $fields_string .= $key.'='.$value.'&'; }
rtrim($fields_string, '&');

//open connection
$ch = curl_init();

//set the url, number of POST vars, POST data
curl_setopt($ch,CURLOPT_URL, $url);
curl_setopt($ch,CURLOPT_POST, count($fields));
curl_setopt($ch,CURLOPT_POSTFIELDS, $fields_string);
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);

//execute post
$result = curl_exec($ch);

//echo the result
echo $result;

//close connection
curl_close($ch);
?>