External Ship
Endpoint URL
https://connect.wholechain.com/Integration/JSON
Sandbox URL
https://connect-sandbox.wholechain.com/Integration/JSON
Method:
POST
Introduction
External Ship events represent when product is shipped from one Company to another. Logging a Ship event moves product item(s) from a company's current inventory to its shipped inventory tab with the status "pending", until the recipient company either receives or rejects the item(s) in their account.
How it works:
- Option 1: a Wholechain user selects an item from their current inventory, and selects the recipient company + location as well as dispatch date.
- Option 2: a Wholechain user creates a Batch Ship event from the Shipping / Receiving page, where they can send multiple products and items at once.
- Option 3: The user can perform this action through the API
Practical Examples
- A shrimp processor ships 3 pallets of shrimp to a distributor’s warehouse.
- A winery ships 500 bottles of wine to a retailer's distribution center.
Authentication
To use this API, you must include the API key in the request header. The API key is assigned to your account and ensures secure communication with the Wholechain platform.
Request Headers
Header | Description | Example Value |
---|---|---|
X-API-KEY |
Your API key | YOUR_API_KEY_HERE |
Content-Type |
Content type of the request | application/json |
accept |
Response content type | */* |
Request Body Parameters:
The following table outlines the required input variables for the ship
event.
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 Request
import requests
url = 'https://connect.wholechain.com/Integration/JSON'
headers = {
'accept': '*/*',
'X-API-KEY': 'e163a6b0-5e65-4b4c-8384-2c9867819569',
'Content-Type': 'application/json'
}
data = {
"Events": [
{
"$type": "ship",
"OriginLocation": {
"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
}
}
},
"DestinationLocation": {
"Urn": "urn:gdst:wholechain.com:location:loc:integrationreceiver.receiverlocation",
"TradePartnerUrn": "urn:gdst:wholechain.com:party:integrationreceiver.0",
"Name": "Receiver Location",
"Address": {
"GeoCoordinates": {
"Latitude": 1,
"Longitude": 1
}
}
},
"OriginTradePartner": {
"Urn": "urn:gdst:wholechain.com:party:brunosfishimports.0",
"TradePartnerId": None,
"Name": "Bruno's Fish Imports",
"Pgln": "",
"ConnectionType": "SELF"
},
"DestinationTradePartner": {
"Urn": "urn:gdst:wholechain.com:party:integrationreceiver.0",
"Name": "Integration Receiver"
},
"ProductInstances": [
{
"Quantity": 25,
"LotSerial": "12345",
"Urn": "urn:gdst:wholechain.com:product:lot:class:brunosfishimports.hake.12345",
"UOM": "Lbs",
"Gtin": "",
"ParentProduct": {
"Urn": "urn:gdst:wholechain.com:product:class:brunosfishimports.hake",
"Name": "Hake",
"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": "0002",
"PurchaseOrder": "1990091",
"InvoiceNumber": "12314154",
"BizStep": "urn:epcglobal:cbv:bizstep:shipping",
"Disposition": "urn:epcglobal:cbv:disp:in_transit",
"EventTime": "2024-03-30T13:00:00+00:00",
"EventTimeZone": "-05:00",
"RecordTime": "2024-08-11T19:32:26.4137461+00:00",
"TradePartner": {
"Urn": "urn:gdst:wholechain.com:party:brunosfishimports.0",
"TradePartnerId": None,
"Name": "Bruno's Fish Imports",
"Pgln": "",
"ConnectionType": "SELF"
},
"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.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
class Program
{
static async Task Main(string[] args)
{
// Define the URL and headers
string url = "https://connect.wholechain.com/Integration/JSON";
string apiKey = "e163a6b0-5e65-4b4c-8384-2c9867819569";
// Create the HTTP client and set the request headers
using (HttpClient client = new HttpClient())
{
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("*/*"));
client.DefaultRequestHeaders.Add("X-API-KEY", apiKey);
client.DefaultRequestHeaders.Add("Content-Type", "application/json");
// Define the JSON data payload
var data = new
{
Events = new[]
{
new
{
_type = "ship",
OriginLocation = new
{
Urn = "urn:gdst:wholechain.com:location:loc:brunosfishimports.mainwarehouse",
TradePartnerUrn = "urn:gdst:wholechain.com:party:brunosfishimports.0",
Name = "Main Warehouse",
Gln = "",
Address = new
{
City = "Curitiba",
State = "Parana",
Country = "Brazil",
AddressLine1 = "Av Presidente Wenceslau Braz, 1893",
AddressLine2 = "T2AP65",
PostalCode = "81010001",
GeoCoordinates = new
{
Latitude = -25.441105,
Longitude = -49.276855
}
}
},
DestinationLocation = new
{
Urn = "urn:gdst:wholechain.com:location:loc:integrationreceiver.receiverlocation",
TradePartnerUrn = "urn:gdst:wholechain.com:party:integrationreceiver.0",
Name = "Receiver Location",
Address = new
{
GeoCoordinates = new
{
Latitude = 1,
Longitude = 1
}
}
},
OriginTradePartner = new
{
Urn = "urn:gdst:wholechain.com:party:brunosfishimports.0",
TradePartnerId = (string)null,
Name = "Bruno's Fish Imports",
Pgln = "",
ConnectionType = "SELF"
},
DestinationTradePartner = new
{
Urn = "urn:gdst:wholechain.com:party:integrationreceiver.0",
Name = "Integration Receiver"
},
ProductInstances = new[]
{
new
{
Quantity = 25,
LotSerial = "12345",
Urn = "urn:gdst:wholechain.com:product:lot:class:brunosfishimports.hake.12345",
UOM = "Lbs",
Gtin = "",
ParentProduct = new
{
Urn = "urn:gdst:wholechain.com:product:class:brunosfishimports.hake",
Name = "Hake",
SimpleUnitOfMeasurement = "Lbs",
SharingPolicy = "Open",
ProductIdentifierType = "Lot",
ProductMasterData = new[]
{
new { Name = "Species For Fishery Statistics Purposes Name", Namespace = "cbvmda", Value = "Salmo salar", ElementId = "speciesForFisheryStatisticsPurposesName" },
new { Name = "Trade Item Condition Code", Namespace = "cbvmda", Value = "RESPONSIBLY FARMED", ElementId = "tradeItemConditionCode" }
}
},
TradePartnerName = "Bruno's Fish Imports"
}
},
ExternalEventId = "0002",
PurchaseOrder = "1990091",
InvoiceNumber = "12314154",
BizStep = "urn:epcglobal:cbv:bizstep:shipping",
Disposition = "urn:epcglobal:cbv:disp:in_transit",
EventTime = "2024-03-30T13:00:00+00:00",
EventTimeZone = "-05:00",
RecordTime = "2024-08-11T19:32:26.4137461+00:00",
TradePartner = new
{
Urn = "urn:gdst:wholechain.com:party:brunosfishimports.0",
TradePartnerId = (string)null,
Name = "Bruno's Fish Imports",
Pgln = "",
ConnectionType = "SELF"
},
CustomProperties = new[]
{
new { Name = "expiry_date", Namespace = "", Value = "2024-03-30", PropertyLocation = "ILMD" }
},
CertificationList = new[]
{
new { CertificationType = "urn:gdst:certType:harvestCoC", CertificationStandard = "MSC Chain of Custody", CertificationAgency = "MSC", CertificationValue = "NO", CertificationIdentification = "NA" },
new { CertificationType = "urn:gdst:certType:fishingAuth", CertificationStandard = "Los Angeles Fishing Authorization", CertificationAgency = "Los Angeles Fishing Authorization", CertificationValue = "", CertificationIdentification = "" },
new { CertificationType = "urn:gdst:certType:humanPolicy", CertificationStandard = "WHO Human Decency Policy", CertificationAgency = "WHO", CertificationValue = "", CertificationIdentification = "" }
}
}
}
};
// Convert the data object to JSON
var jsonData = JsonConvert.SerializeObject(data);
// Make the POST request
HttpResponseMessage response = await client.PostAsync(url, new StringContent(jsonData, Encoding.UTF8, "application/json"));
// Print the response status code and body
Console.WriteLine($"Response Status Code: {response.StatusCode}");
Console.WriteLine($"Response Body: {await response.Content.ReadAsStringAsync()}");
}
}
}
curl -X POST 'https://connect.wholechain.com/Integration/JSON' \
-H 'accept: */*' \
-H 'X-API-KEY: e163a6b0-5e65-4b4c-8384-2c9867819569' \
-H 'Content-Type: application/json' \
-d '{
"Events": [
{
"$type": "ship",
"OriginLocation": {
"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
}
}
},
"DestinationLocation": {
"Urn": "urn:gdst:wholechain.com:location:loc:integrationreceiver.receiverlocation",
"TradePartnerUrn": "urn:gdst:wholechain.com:party:integrationreceiver.0",
"Name": "Receiver Location",
"Address": {
"GeoCoordinates": {
"Latitude": 1,
"Longitude": 1
}
}
},
"OriginTradePartner": {
"Urn": "urn:gdst:wholechain.com:party:brunosfishimports.0",
"TradePartnerId": null,
"Name": "Bruno'\''s Fish Imports",
"Pgln": "",
"ConnectionType": "SELF"
},
"DestinationTradePartner": {
"Urn": "urn:gdst:wholechain.com:party:integrationreceiver.0",
"Name": "Integration Receiver"
},
"ProductInstances": [
{
"Quantity": 25,
"LotSerial": "12345",
"Urn": "urn:gdst:wholechain.com:product:lot:class:brunosfishimports.hake.12345",
"UOM": "Lbs",
"Gtin": "",
"ParentProduct": {
"Urn": "urn:gdst:wholechain.com:product:class:brunosfishimports.hake",
"Name": "Hake",
"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": "0002",
"PurchaseOrder": "1990091",
"InvoiceNumber": "12314154",
"BizStep": "urn:epcglobal:cbv:bizstep:shipping",
"Disposition": "urn:epcglobal:cbv:disp:in_transit",
"EventTime": "2024-03-30T13:00:00+00:00",
"EventTimeZone": "-05:00",
"RecordTime": "2024-08-11T19:32:26.4137461+00:00",
"TradePartner": {
"Urn": "urn:gdst:wholechain.com:party:brunosfishimports.0",
"TradePartnerId": null,
"Name": "Bruno'\''s Fish Imports",
"Pgln": "",
"ConnectionType": "SELF"
},
"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
{
"status": 200,
"message": "Success",
"result": {
"products": [
{
"gtin": null,
"status": "Skipped",
"id": "3385e8ea-7c12-4a94-9524-3f68d1667b67",
"name": "Hake",
"urn": "urn:gdst:wholechain.com:product:class:brunosfishimports.hake"
}
],
"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"
},
{
"gln": null,
"geoCoordinates": {
"latitude": 39.3614358,
"longitude": -74.4179374
},
"status": "Skipped",
"id": "7c571ef9-f0e1-4833-a404-6621aee90245",
"name": "US Warehouse",
"urn": "urn:gdst:wholechain.com:location:loc:brunosfishimports.uswarehouse"
}
],
"tradePartners": [
{
"pgln": null,
"status": "Skipped",
"id": "324de292-976d-4ff8-8215-945b63e7d5d5",
"name": "Bruno's Fish Imports",
"urn": "urn:gdst:wholechain.com:party:brunosfishimports.0"
},
{
"pgln": "",
"status": "Skipped",
"id": "80c2986d-97a5-4842-a3da-befadeaf19ee",
"name": "Integration Receiver",
"urn": "urn:gdst:wholechain.com:party:integrationreceiver.0"
}
],
"events": [
{
"type": "Ship",
"eventDate": "2024-03-30T13:00:00+00:00",
"productInstances": [
{
"quantity": 25,
"lotSerial": "12345",
"status": "Created",
"id": "515540b3-f40a-41a0-b319-a01cd82ce198",
"name": "Hake",
"urn": "urn:gdst:wholechain.com:product:lot:class:brunosfishimports.hake.12345"
}
],
"status": "Created",
"id": "6d029c02-1270-495a-ba68-2bc598003aa2",
"name": "Ship",
"urn": "urn:uuid:6d029c02-1270-495a-ba68-2bc598003aa2"
}
]
},
"errors": []
}