Skip to content

Internal Ship

Endpoint URL

https://connect.wholechain.com/Integration/JSON

Sandbox URL

https://connect-sandbox.wholechain.com/Integration/JSON

Method:

POST

Introduction

An Internal Ship event represents product movement internally within a company's various business locations, or partner facilities while the company maintains custody. Products maintain their physical properties, they simply move from one location to another.

How it works:

  • A Wholechain user selects the item(s) they wish to ship, and selects the ship date(s).
  • The user selects themselves in the Recipient field, as well as the location the goods are shipping to. This location would have already been set up in the user's business settings.
  • The user can select to automatically log the Receive event, and will be prompted to enter the date the items were received.
  • The user can perform this action through the API Local image

Practical Examples

  • A batch of coffee beans is shipped from a company's roasting facility to its packaging facility. Both facilities are owned and operated by the same company, ensuring the beans maintain their traceability within the internal supply chain.
  • A product moves from a cold storage facility in one location to a processing facility in another location, both of which are owned and managed by the same company.

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:

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:brunosfishimports.uswarehouse",
                "TradePartnerUrn": "urn:gdst:wholechain.com:party:brunosfishimports.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:brunosfishimports.0",
                "Name": "Bruno Fish Imports"
            },
            "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:brunosfishimports.uswarehouse",
                            TradePartnerUrn = "urn:gdst:wholechain.com:party:brunosfishimports.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:brunosfishimports.0",
                            Name = "Bruno Fish Imports"
                        },
                        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:brunosfishimports.uswarehouse",
        "TradePartnerUrn": "urn:gdst:wholechain.com:party:brunosfishimports.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:brunosfishimports.0",
        "Name": "Bruno Fish Imports"
    },
    "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": []
}