Commission
Endpoint URL
https://connect.wholechain.com/Integration/JSON
Sandbox URL
https://connect-sandbox.wholechain.com/Integration/JSON
Method:
POST
Introduction
A Commission event represents a product coming into existence in its documented supply chain. It typically occurs at the farthest upstream point of the traceability journey - either the point of harvest, or the first time that a product is being documented as itself.
How it works:
- A Wholechain user can initiate a Commission event directly from the product’s current inventory page or via the Wholechain API, with the flexibility to incorporate custom data as needed.
- The record of the commissioned product is stored in the Wholechain database and written to the blockchain, establishing the origin point of the product within the supply chain.
Practical Examples
- A shipment of apples is decommissioned after a portion of the crates is found to be damaged during transit and is deemed unfit for sale.
- A product is purchased by a customer at a retail store.
Use Case
This API is typically used when a new product is commissioned (i.e., registered) in the supply chain system, capturing its initial creation and linking it to the appropriate metadata. The commissioning event is crucial for traceability because it defines the entry of the product into the supply chain system with all required certifications and compliance standards.
Authentication
The API uses an API key (X-API-KEY) to authenticate requests. Each user has a unique API key that controls access to event details tied to their company. To understand where this can be found, please visit the Authentication page.
Request Headers:
| Header | Description | Example Value |
|---|---|---|
X-API-KEY |
Your API key | 08a3b47b-fc51-4eed-ae7e-a96fe4f49c64 |
Content-Type |
Content type of the request | application/json |
accept |
Response content type | */* |
Request Body Parameters:
This document outlines the database schema for storing JSON event data. Each table corresponds to a distinct data object in the JSON structure.
Location Object
| Column Name | Data Type | Description |
|---|---|---|
Urn |
STRING | Unique identifier for the location. |
TradePartnerUrn |
STRING | Trade Partner URN associated with the location. |
Name |
STRING | Name of the location. |
Gln |
STRING | Global Location Number (GLN), if available. |
City |
STRING | City where the location is based. |
State |
STRING | State or province. |
Country |
STRING | Country. |
AddressLine1 |
STRING | First line of the address. |
AddressLine2 |
STRING | Second line of the address (optional). |
PostalCode |
STRING | Postal or ZIP code. |
Latitude |
FLOAT | Geographic latitude of the location. |
Longitude |
FLOAT | Geographic longitude of the location. |
TradePartner Object
| Column Name | Data Type | Description |
|---|---|---|
Urn |
STRING | Unique identifier for the trade partner. |
TradePartnerId |
STRING | Unique ID for the trade partner (optional). |
Name |
STRING | Name of the trade partner. |
Pgln |
STRING | Party GLN (Global Location Number). |
ConnectionType |
STRING | Type of connection (e.g., SELF). |
ProductInstances Object
| Column Name | Data Type | Description |
|---|---|---|
Quantity |
FLOAT | Quantity of the product in this instance. |
LotSerial |
STRING | Lot or serial number of the product. |
Urn |
STRING | Unique identifier for the product instance. |
UOM |
STRING | Unit of measurement (e.g., Lbs). |
Gtin |
STRING | Global Trade Item Number (optional). |
ParentProductUrn |
STRING | URN of the parent product. |
ParentProductName |
STRING | Name of the parent product. |
SimpleUOM |
STRING | Simplified unit of measurement. |
SharingPolicy |
STRING | Product sharing policy (e.g., Open). |
ProductIdentifierType |
STRING | Identifier type (e.g., Lot). |
ProductMasterData Object
| Column Name | Data Type | Description |
|---|---|---|
ParentProductUrn |
STRING | URN of the parent product this data is associated with. |
Name |
STRING | Name of the product attribute. |
Namespace |
STRING | Namespace of the attribute (e.g., cbvmda). |
Value |
STRING | Value of the product attribute. |
ElementId |
STRING | Element ID for the attribute. |
Event Object
| Column Name | Data Type | Description |
|---|---|---|
ExternalEventId |
STRING | This must be different for every API call |
PurchaseOrder |
STRING | Purchase order number. |
InvoiceNumber |
STRING | Invoice number associated with the event. |
BizStep |
STRING | Business step identifier. |
Disposition |
STRING | Disposition of the product in the event. |
EventTime |
DATETIME | Timestamp for when the event occurred. |
EventTimeZone |
STRING | Time zone offset for the event. |
RecordTime |
DATETIME | Timestamp for when the event was recorded. |
CustomProperties Object
| Column Name | Data Type | Description |
|---|---|---|
EventId |
STRING | ID of the event this property is associated with. |
Name |
STRING | Name of the custom property. |
Namespace |
STRING | Namespace of the property. |
Value |
STRING | Value of the custom property. |
PropertyLocation |
STRING | Location of the property (e.g., ILMD). |
CertificationList Object
| Column Name | Data Type | Description |
|---|---|---|
EventId |
STRING | ID of the event this certification is linked to. |
CertificationType |
STRING | Type of certification (e.g., harvestCoC). |
CertificationStandard |
STRING | Certification standard (e.g., MSC Chain of Custody). |
CertificationAgency |
STRING | Agency providing the certification. |
CertificationValue |
STRING | Certification value. |
CertificationIdentification |
STRING | Certification identification number or code. |
| ## Example Requests |
import requests
url = 'https://connect.wholechain.com/Integration/JSON'
headers = {
'accept': '*/*',
'X-API-KEY': '08a3b47b-fc51-4eed-ae7e-a96fe4f49c64',
'Content-Type': 'application/json'
}
data = {
"Events": [
{
"$type": "commission",
"Location": {
"Urn": "urn:gdst:wholechain.com:location:loc:brunosfishimports.mainwarehouse",
"TradePartnerUrn": "urn:gdst:wholechain.com:party:brunosfishimports.0",
"Name": "Main Warehouse",
"Gln": "",
"Address": {
"City": "Curitiba",
"State": "Parana",
"Country": "Brazil",
"AddressLine1": "Av Presidente Wenceslau Braz, 1893",
"AddressLine2": "T2AP65",
"PostalCode": "81010001",
"GeoCoordinates": {
"Latitude": -25.441105,
"Longitude": -49.276855
}
}
},
"TradePartner": {
"Urn": "urn:gdst:wholechain.com:party:brunosfishimports.0",
"TradePartnerId": None,
"Name": "Bruno's Fish Imports",
"Pgln": "",
"ConnectionType": "SELF"
},
"ProductInstances": [
{
"Quantity": 190.75,
"LotSerial": "8765",
"Urn": "urn:gdst:wholechain.com:product:lot:class:brunosfishimports.salmoncut.8765",
"UOM": "Lbs",
"Gtin": "",
"ParentProduct": {
"Urn": "urn:gdst:wholechain.com:product:class:brunosfishimports.salmoncut",
"Name": "Salmon Cut",
"SimpleUnitOfMeasurement": "Lbs",
"SharingPolicy": "Open",
"ProductIdentifierType": "Lot",
"ProductMasterData": [
{
"Name": "Species For Fishery Statistics Purposes Name",
"Namespace": "cbvmda",
"Value": "Salmo salar",
"ElementId": "speciesForFisheryStatisticsPurposesName"
},
{
"Name": "Trade Item Condition Code",
"Namespace": "cbvmda",
"Value": "RESPONSIBLY FARMED",
"ElementId": "tradeItemConditionCode"
}
]
},
"TradePartnerName": "Bruno's Fish Imports"
}
],
"ExternalEventId": "0001",
"PurchaseOrder": "1990091",
"InvoiceNumber": "12314154",
"BizStep": "urn:epcglobal:cbv:bizstep:commissioning",
"Disposition": "urn:epcglobal:cbv:disp:active",
"EventTime": "2024-03-30T13:00:00+00:00",
"EventTimeZone": "-05:00",
"RecordTime": "2024-08-11T19:32:26.4137461+00:00",
"CustomProperties": [
{
"Name": "expiry_date",
"Namespace": "",
"Value": "2024-03-30",
"PropertyLocation": "ILMD"
}
],
"CertificationList": [
{
"CertificationType": "urn:gdst:certType:harvestCoC",
"CertificationStandard": "MSC Chain of Custody",
"CertificationAgency": "MSC",
"CertificationValue": "NO",
"CertificationIdentification": "NA"
},
{
"CertificationType": "urn:gdst:certType:fishingAuth",
"CertificationStandard": "Los Angeles Fishing Authorization",
"CertificationAgency": "Los Angeles Fishing Authorization",
"CertificationValue": "",
"CertificationIdentification": ""
},
{
"CertificationType": "urn:gdst:certType:humanPolicy",
"CertificationStandard": "WHO Human Decency Policy",
"CertificationAgency": "WHO",
"CertificationValue": "",
"CertificationIdentification": ""
}
]
}
]
}
response = requests.post(url, headers=headers, json=data)
print(response.status_code)
print(response.json())
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
namespace WholechainAPI
{
class Program
{
static async Task Main(string[] args)
{
var url = "https://connect.wholechain.com/Integration/JSON";
// Define the JSON payload
var jsonData = @"{
""Events"": [
{
""$type"": ""commission"",
""Location"": {
""Urn"": ""urn:gdst:wholechain.com:location:loc:brunosfishimports.mainwarehouse"",
""TradePartnerUrn"": ""urn:gdst:wholechain.com:party:brunosfishimports.0"",
""Name"": ""Main Warehouse"",
""Gln"": """",
""Address"": {
""City"": ""Curitiba"",
""State"": ""Parana"",
""Country"": ""Brazil"",
""AddressLine1"": ""Av Presidente Wenceslau Braz, 1893"",
""AddressLine2"": ""T2AP65"",
""PostalCode"": ""81010001"",
""GeoCoordinates"": {
""Latitude"": -25.441105,
""Longitude"": -49.276855
}
}
},
""TradePartner"": {
""Urn"": ""urn:gdst:wholechain.com:party:brunosfishimports.0"",
""TradePartnerId"": null,
""Name"": ""Bruno's Fish Imports"",
""Pgln"": """",
""ConnectionType"": ""SELF""
},
""ProductInstances"": [
{
""Quantity"": 190.75,
""LotSerial"": ""8765"",
""Urn"": ""urn:gdst:wholechain.com:product:lot:class:brunosfishimports.salmoncut.8765"",
""UOM"": ""Lbs"",
""Gtin"": """",
""ParentProduct"": {
""Urn"": ""urn:gdst:wholechain.com:product:class:brunosfishimports.salmoncut"",
""Name"": ""Salmon Cut"",
""SimpleUnitOfMeasurement"": ""Lbs"",
""SharingPolicy"": ""Open"",
""ProductIdentifierType"": ""Lot"",
""ProductMasterData"": [
{
""Name"": ""Species For Fishery Statistics Purposes Name"",
""Namespace"": ""cbvmda"",
""Value"": ""Salmo salar"",
""ElementId"": ""speciesForFisheryStatisticsPurposesName""
},
{
""Name"": ""Trade Item Condition Code"",
""Namespace"": ""cbvmda"",
""Value"": ""RESPONSIBLY FARMED"",
""ElementId"": ""tradeItemConditionCode""
}
]
},
""TradePartnerName"": ""Bruno's Fish Imports""
}
],
""ExternalEventId"": ""0001"",
""PurchaseOrder"": ""1990091"",
""InvoiceNumber"": ""12314154"",
""BizStep"": ""urn:epcglobal:cbv:bizstep:commissioning"",
""Disposition"": ""urn:epcglobal:cbv:disp:active"",
""EventTime"": ""2024-03-30T13:00:00+00:00"",
""EventTimeZone"": ""-05:00"",
""RecordTime"": ""2024-08-11T19:32:26.4137461+00:00"",
""CustomProperties"": [
{
""Name"": ""expiry_date"",
""Namespace"": """",
""Value"": ""2024-03-30"",
""PropertyLocation"": ""ILMD""
}
],
""CertificationList"": [
{
""CertificationType"": ""urn:gdst:certType:harvestCoC"",
""CertificationStandard"": ""MSC Chain of Custody"",
""CertificationAgency"": ""MSC"",
""CertificationValue"": ""NO"",
""CertificationIdentification"": ""NA""
},
{
""CertificationType"": ""urn:gdst:certType:fishingAuth"",
""CertificationStandard"": ""Los Angeles Fishing Authorization"",
""CertificationAgency"": ""Los Angeles Fishing Authorization"",
""CertificationValue"": """",
""CertificationIdentification"": """"
},
{
""CertificationType"": ""urn:gdst:certType:humanPolicy"",
""CertificationStandard"": ""WHO Human Decency Policy"",
""CertificationAgency"": ""WHO"",
""CertificationValue"": """",
""CertificationIdentification"": """"
}
]
}
]
}";
using (var client = new HttpClient())
{
// Set request headers
client.DefaultRequestHeaders.Accept.Clear();
client.DefaultRequestHeaders.Add("accept", "*/*");
client.DefaultRequestHeaders.Add("X-API-KEY", "08a3b47b-fc51-4eed-ae7e-a96fe4f49c64");
// Create the content for the request
var content = new StringContent(jsonData, Encoding.UTF8, "application/json");
// Make the POST request
HttpResponseMessage response = await client.PostAsync(url, content);
// Print the status code
Console.WriteLine("Status Code: " + response.StatusCode);
// Print the response content
if (response.IsSuccessStatusCode)
{
string responseBody = await response.Content.ReadAsStringAsync();
Console.WriteLine("Response: " + responseBody);
}
else
{
Console.WriteLine("Request failed with status code: " + response.StatusCode);
}
}
}
}
}
curl -X POST 'https://connect.wholechain.com/Integration/JSON' \
-H 'accept: */*' \
-H 'X-API-KEY: 08a3b47b-fc51-4eed-ae7e-a96fe4f49c64' \
-H 'Content-Type: application/json' \
-d '{
"Events": [
{
"$type": "commission",
"Location": {
"Urn": "urn:gdst:wholechain.com:location:loc:brunosfishimports.mainwarehouse",
"TradePartnerUrn": "urn:gdst:wholechain.com:party:brunosfishimports.0",
"Name": "Main Warehouse",
"Gln": "",
"Address": {
"City": "Curitiba",
"State": "Parana",
"Country": "Brazil",
"AddressLine1": "Av Presidente Wenceslau Braz, 1893",
"AddressLine2": "T2AP65",
"PostalCode": "81010001",
"GeoCoordinates": {
"Latitude": -25.441105,
"Longitude": -49.276855
}
}
},
"TradePartner": {
"Urn": "urn:gdst:wholechain.com:party:brunosfishimports.0",
"TradePartnerId": null,
"Name": "Bruno'\''s Fish Imports",
"Pgln": "",
"ConnectionType": "SELF"
},
"ProductInstances": [
{
"Quantity": 190.75,
"LotSerial": "8765",
"Urn": "urn:gdst:wholechain.com:product:lot:class:brunosfishimports.salmoncut.8765",
"UOM": "Lbs",
"Gtin": "",
"ParentProduct": {
"Urn": "urn:gdst:wholechain.com:product:class:brunosfishimports.salmoncut",
"Name": "Salmon Cut",
"SimpleUnitOfMeasurement": "Lbs",
"SharingPolicy": "Open",
"ProductIdentifierType": "Lot",
"ProductMasterData": [
{
"Name": "Species For Fishery Statistics Purposes Name",
"Namespace": "cbvmda",
"Value": "Salmo salar",
"ElementId": "speciesForFisheryStatisticsPurposesName"
},
{
"Name": "Trade Item Condition Code",
"Namespace": "cbvmda",
"Value": "RESPONSIBLY FARMED",
"ElementId": "tradeItemConditionCode"
}
]
},
"TradePartnerName": "Bruno'\''s Fish Imports"
}
],
"ExternalEventId": "0001",
"PurchaseOrder": "1990091",
"InvoiceNumber": "12314154",
"BizStep": "urn:epcglobal:cbv:bizstep:commissioning",
"Disposition": "urn:epcglobal:cbv:disp:active",
"EventTime": "2024-03-30T13:00:00+00:00",
"EventTimeZone": "-05:00",
"RecordTime": "2024-08-11T19:32:26.4137461+00:00",
"CustomProperties": [
{
"Name": "expiry_date",
"Namespace": "",
"Value": "2024-03-30",
"PropertyLocation": "ILMD"
}
],
"CertificationList": [
{
"CertificationType": "urn:gdst:certType:harvestCoC",
"CertificationStandard": "MSC Chain of Custody",
"CertificationAgency": "MSC",
"CertificationValue": "NO",
"CertificationIdentification": "NA"
},
{
"CertificationType": "urn:gdst:certType:fishingAuth",
"CertificationStandard": "Los Angeles Fishing Authorization",
"CertificationAgency": "Los Angeles Fishing Authorization",
"CertificationValue": "",
"CertificationIdentification": ""
},
{
"CertificationType": "urn:gdst:certType:humanPolicy",
"CertificationStandard": "WHO Human Decency Policy",
"CertificationAgency": "WHO",
"CertificationValue": "",
"CertificationIdentification": ""
}
]
}
]
}'
Response
The following response is returned when a request is successfully processed. The HTTP status code 200 indicates that the operation completed without major errors, and the response body includes information about the different entities that were processed.
Response Body
{
"message": "Success",
"result": {
"products": [
{
"gtin": null,
"status": "Skipped",
"id": "72deeb0e-c080-45c2-a1be-64e81c58ba26",
"name": "Salmon Cut",
"urn": "urn:gdst:wholechain.com:product:class:brunosfishimports.salmoncut"
}
],
"locations": [
{
"gln": null,
"geoCoordinates": {
"latitude": 13.7283667,
"longitude": 100.5145846
},
"status": "Skipped",
"id": "dabbeeae-8d4a-411c-815f-91477f50924f",
"name": "Main Warehouse",
"urn": "urn:gdst:wholechain.com:location:loc:brunosfishimports.mainwarehouse"
}
],
"tradePartners": [
{
"pgln": null,
"status": "Skipped",
"id": "324de292-976d-4ff8-8215-945b63e7d5d5",
"name": "Bruno's Fish Imports",
"urn": "urn:gdst:wholechain.com:party:brunosfishimports.0"
}
],
"events": [
{
"type": "Commission",
"eventDate": "2024-03-30T13:00:00+00:00",
"productInstances": [
{
"quantity": 190.75,
"lotSerial": "8765",
"status": "Created",
"id": "94e6b2ae-d787-4e69-9dd4-f16c80c1fc36",
"name": "Salmon Cut",
"urn": "urn:gdst:wholechain.com:product:lot:class:brunosfishimports.salmoncut.8765"
}
],
"status": "Created",
"id": "bceb7358-3daa-42b6-bbd4-7f5bc3977b0f",
"name": "Commission",
"urn": "urn:uuid:bceb7358-3daa-42b6-bbd4-7f5bc3977b0f"
}
]
},
"errors": []
}