Disaggregate
Endpoint URL
https://connect.wholechain.com/Integration/Events
Sandbox URL
https://connect-sandbox.wholechain.com/Integration/Events
Method:
POST
What is a Disaggregate Event?
A Disaggregate event is the reverse of an aggregation—where discrete, individually traceable products from an aggregation are separated. Disaggregation can only occur after aggregation. Nothing about the individual items is inherently changed; they are simply broken down to be treated as individual units again.
How It Works
- A Wholechain user selects the aggregation they wish to disaggregate.
- The products are separated back into the same discrete items they were prior to the aggregation.
- An aggregation must occur prior to a disaggregation event in the supply chain.
Examples
-
50 cartons of strawberries are disaggregated from a pallet at a retail store to be placed on the shelf for individual sale.
-
A shipment of 200 bags of coffee beans is disaggregated from a large container at a distribution center, allowing the individual bags to be sent to various coffee shops and retailers.
Two API Payload Options for the Disaggregate Event
When using the Disaggregate Event API, there are two distinct payload options available, depending on your needs:
1. Reference Existing Products, Trade Partners, and Locations
- This payload is designed for users who already have their products, trade partners, and locations pre-configured within their Wholechain account.
- It references these existing entities using their unique IDs.
2. Create Products, Locations, and Trade Partners On-the-Go
- This payload is designed for users who want to dynamically create new products, trade partners, or locations directly through the API without pre-configuring them in Wholechain.
- The API intelligently processes the payload to identify and create new entities if the provided IDs do not already exist in your account.
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 | Identifier | Required |
|---|---|---|---|---|
Location ID |
STRING | Unique identifier for the location. | Primary | Yes |
Product Instance Object
| Column Name | Data Type | Description | Identifier | Required |
|---|---|---|---|---|
Quantity |
DECIMAL | Quantity of the product in the instance. | Not Primary | Yes |
LotSerial |
STRING | Lot or serial number of the product instance. | Not Primary | Yes |
Product ID |
STRING | Unique identifier for the product. | Primary | Yes |
Container Object
| Column Name | Data Type | Description | Identifier | Required |
|---|---|---|---|---|
Id |
STRING | If both SSCC and Logistic ID exist, use SSCC as ID | Not Primary | Yes |
Event Object
| Column Name | Data Type | Description | Identifier | Required |
|---|---|---|---|---|
Id |
STRING | Unique identifier for the event. | Not Primary | Yes |
EventTime |
DATETIME | Timestamp of when the event occurred. | Not Primary | Yes |
EventTimeZone |
STRING | Timezone of the event timestamp. | Not Primary | Yes |
Example Requests
import requests
url = 'https://connect.wholechain.com/Integration/Events'
headers = {
'accept': '*/*',
'X-API-KEY': '0193d105-03f6-7829-8de1-d55c166a35f6',
'Content-Type': 'application/json'
}
data = {
"Events": [
{
"$type": "disaggregation",
"Location": {
"Id": "4567"
},
"Container": {
"Id": "1111"
},
"Id": "12",
"EventTime": "2024-03-30T17:00:00+00:00",
"EventTimeZone": "-05:00"
}
]
}
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;
using Newtonsoft.Json;
class Program
{
static async Task Main(string[] args)
{
var url = "https://connect.wholechain.com/Integration/Events";
var apiKey = "0193d105-03f6-7829-8de1-d55c166a35f6";
var data = new
{
Events = new[]
{
new
{
$type = "disaggregation",
Location = new
{
Id = "4567"
},
Container = new
{
Id = "1111"
},
Id = "12",
EventTime = "2024-03-30T17:00:00+00:00",
EventTimeZone = "-05:00"
}
}
};
using (var client = new HttpClient())
{
client.DefaultRequestHeaders.Add("accept", "*/*");
client.DefaultRequestHeaders.Add("X-API-KEY", apiKey);
var json = JsonConvert.SerializeObject(data);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync(url, content);
Console.WriteLine($"Status Code: {response.StatusCode}");
var responseContent = await response.Content.ReadAsStringAsync();
Console.WriteLine(responseContent);
}
}
}
curl -X POST https://connect.wholechain.com/Integration/Events \
-H "accept: */*" \
-H "X-API-KEY: 0193d105-03f6-7829-8de1-d55c166a35f6" \
-H "Content-Type: application/json" \
-d '{
"Events": [
{
"$type": "disaggregation",
"Location": {
"Id": "4567"
},
"Container": {
"Id": "1111"
},
"Id": "12",
"PurchaseOrder": "1990091",
"EventTime": "2024-03-30T17:00:00+00:00",
"EventTimeZone": "-05:00"
}
]
}'
Creating Locations, Trade Partners, and Products On-the-Go
In many cases, users may need the ability to dynamically create new locations, trade partners, or products directly within the API instead of pre-configuring them within the Wholechain platform. This is particularly useful when dealing with constantly changing locations, new trade partners, or orders that cannot feasibly be manually added to both an ERP system and Wholechain.
To address this need, we’ve introduced the "Details" object within specific sections of the API payload. This allows the API to intelligently handle new or existing entities, ensuring a seamless and flexible experience.
How It Works
Details Section
The "Details" section is used to provide additional metadata for locations, trade partners, or products. The behavior of the API depends on whether the IDs in the payload already exist in your Wholechain account. Here’s how the process works:
1. ID Matching Logic:
- If the ID in the payload already exists in your Wholechain account, the API will skip over the "Details" section and use the pre-existing information from your Wholechain system.
- If the ID is new (i.e., it does not exist in your Wholechain account), the API will use the information in the "Details" section to create a new location, trade partner, or product.
2. Mix-and-Match Capabilities:
- You can mix new and existing entities within the same API request. For example:
- Use a new location ID with details for creation.
- Reference an existing trade partner ID without additional details.
- Reference an existing product ID while creating a new location or trade partner.
3. Required Fields for New Entities:
- When creating a new entity (location, trade partner, or product), provide an ID that does not currently exist in your Wholechain account. Include additional metadata in the "Details" section (e.g., name, address, GLN, and other relevant fields).
Example Payload Behavior
ProductInstances
- If the
Product.Idexists in your Wholechain account: - The API skips the product details and references the existing product information.
- If the
Product.Idis new: - The API creates a new product based on the details provided in the payload.
Key Considerations
- Ensure that IDs for new entities (locations, trade partners, products) are unique and do not conflict with existing IDs in your Wholechain account.
- The "Details" section provides flexibility to dynamically create new entities while still allowing references to existing ones.
- If a field is skipped (e.g., "Details" for an existing ID), no changes will be made to the existing entity in Wholechain.
Location Details Object
| Column Name | Data Type | Description | Identifier | Required |
|---|---|---|---|---|
TradePartner |
OBJECT | Details of the trade partner associated with the location. | Not Primary | Yes if creating new |
TradePartner.Id |
STRING | Unique identifier for the trade partner. | Primary | Yes if creating new |
TradePartner.Name |
STRING | Name of the trade partner. | Not Primary | Yes if creating new |
TradePartner.ConnectionType |
STRING | Type of connection (e.g., SUPPLIER). | Not Primary | Yes if creating new |
TradePartner.Duns |
STRING | DUNS (Data Universal Numbering System) number of the partner. | Not Primary | Yes if creating new |
Name |
STRING | Name of the location. | Not Primary | Yes if creating new |
Gln |
STRING | Global Location Number of the location. | Not Primary | No |
Extension |
STRING | Additional location information. | Not Primary | No |
ContactInformation |
OBJECT | Contact information for the location. | Not Primary | Yes if creating new |
ContactInformation.Name |
STRING | Name of the contact person at the location. | Not Primary | Yes if creating new |
ContactInformation.Phone |
STRING | Phone number of the contact person. | Not Primary | Yes if creating new |
ContactInformation.Email |
STRING | Email address of the contact person. | Not Primary | Yes if creating new |
Address |
OBJECT | Address details of the location. | Not Primary | Yes if creating new |
Address.City |
STRING | City where the location is situated. | Not Primary | Yes if creating new |
Address.State |
STRING | State where the location is situated. | Not Primary | Yes if creating new |
Address.Country |
STRING | Country of the location. | Not Primary | Yes if creating new |
Address.AddressLine1 |
STRING | Primary address line of the location. | Not Primary | Yes if creating new |
Address.AddressLine2 |
STRING | Secondary address line of the location. | Not Primary | No |
Address.PostalCode |
STRING | Postal code of the location. | Not Primary | Yes if creating new |
Address.GeoCoordinates |
OBJECT | Geographical coordinates of the location. | Not Primary | No |
GeoCoordinates.Latitude |
DECIMAL | Latitude of the location. | Not Primary | No |
GeoCoordinates.Longitude |
DECIMAL | Longitude of the location. | Not Primary | No |
Example Minimum Payload
data = {
"Events": [
{
"$type": "disaggregation",
"Location": {
"Id": "4567",
"Details": {
"TradePartner": {
"Id": "TpId123",
"Name": "Me",
"ConnectionType": "SELF"
},
"Name": "Processing",
"Address": {
"Country": "Country Name",
"AddressLine1": "123 Main St"
}
}
},
"Container": {
"Id": "1111"
},
"Id": "12",
"EventTime": "2024-03-30T17:00:00+00:00",
"EventTimeZone": "-05:00"
}
]
}
Additional Fields
In addition to the minimum required data payloads, you may include a range of optional fields, shown in the full payload example below. Refernce to them is made in the tables above where required = "No".
We also support several specialized objects:
- Custom Properties Object – Allows you to attach custom properties to a specific event. See the reference table below for details.
- Certificate Object – Enables you to include certification details related to an event. See the reference table below.
- TLC Object (for FSMA compliance) – Used only when changing the vendor lot code upon receiving a product. In that case, include the vendor lot in the TLC object and also record the TLC lot code.
All of these fields are optional, but they provide flexibility to capture additional, event-specific information when needed.
Custom Properties Object
| Column Name | Data Type | Description | Identifier | Required |
|---|---|---|---|---|
Name |
STRING | The name of the custom property. | Not Primary | Yes |
Namespace |
STRING | The namespace associated with the property. | Not Primary | No |
Value |
STRING | The value assigned to the custom property. | Not Primary | Yes |
PropertyLocation |
STRING | Location where the property is applied, such as ILMD. | Not Primary | No |
Certification List Object
| Column Name | Data Type | Description | Identifier | Required |
|---|---|---|---|---|
Type |
STRING | The type of certification (e.g., harvest CoC). | Not Primary | No |
Standard |
STRING | The certification standard being referenced. | Not Primary | No |
Agency |
STRING | The agency issuing the certification. | Not Primary | No |
Value |
STRING | The value of the certification (e.g., Yes/No). | Not Primary | No |
Identification |
STRING | Identifier for the certification, if applicable. | Not Primary | No |
Important Information About TLC Source
TLC Source offers two ways to identify a location in your data:
-
Using a TLC Source Reference: Provide a reference, such as a GLN number, to identify a location.
-
Using TLC Location Details: Provide the full location address information (e.g., country, street address, city, etc.) to specify the location.
Below are two example payload formats, each demonstrating one of these options, along with tables for reference.
TLC Object (Using Reference Details)
| Field Name | Data Type | Description | Primary Key | Required |
|---|---|---|---|---|
TlcSource |
OBJECT | Source information for the traceability lot code (TLC). | Not Primary | Yes |
Type |
STRING | Default to "Identifier" | Primary | Yes |
Reference |
STRING | What is the identifier (eg, DUNS, GLN, MSC Etc) | Primary | Yes |
Identifier |
STRING | Actual value of the identification | Primary | Yes |
| Field Name | Data Type | Description | Primary Key | Required |
|---|---|---|---|---|
TlcSource |
OBJECT | Source information for the traceability lot code (TLC). | Not Primary | Yes |
TlcSource.LocationName |
STRING | Name of the TLC location. | Not Primary | Yes |
TlcSource.CompanyName |
STRING | Name of the company associated with the TLC. | Not Primary | Yes |
TlcSource.City |
STRING | City of the source. | Not Primary | No |
TlcSource.State |
STRING | State of the source. | Not Primary | No |
TlcSource.Country |
STRING | Country of the source. | Not Primary | Yes |
TlcSource.Line1 |
STRING | Primary address line of the source. | Not Primary | Yes |
TlcSource.Line2 |
STRING | Secondary address line of the source. | Not Primary | No |
TlcSource.PostalCode |
STRING | Postal code of the source. | Not Primary | No |
TlcSource.Phone |
STRING | Contact phone number for the source. | Not Primary | Yes |
TlcSource.Type |
STRING | Type of TLC source (e.g., MasterData). | Not Primary | Yes |
TlcSource.GeoCoordinates |
OBJECT | Geographical coordinates of the source. | Not Primary | NO |
GeoCoordinates.Latitude |
DECIMAL | Latitude of the source. | Not Primary | No |
GeoCoordinates.Longitude |
DECIMAL | Longitude of the source. | Not Primary | No |
data = {
"Events": [
{
"$type": "disaggregation",
"Location": {
"Id": "4567",
"Details": {
"TradePartner": {
"Id": "TpId123",
"Name": "Me",
"ConnectionType": "SELF",
"Duns": "123456789"
},
"Name": "Processing",
"ContactInformation": {
"Name": "Contact Name",
"Phone": "+1234567890",
"Email": "contact@example.com"
},
"Address": {
"City": "City Name",
"State": "State Name",
"Country": "Country Name",
"AddressLine1": "123 Main St",
"AddressLine2": "Apt 4B",
"PostalCode": "12345",
"GeoCoordinates": {
"Latitude": 12.345678,
"Longitude": 98.765432
}
}
}
},
"ProductInstances": [
{
"Quantity": 120.00,
"LotSerial": "LOT-001-A",
"Product": {
"Id": "prod_001",
"Details": {
"Name": "RawGoods",
"SimpleUnitOfMeasurement": "Lbs",
"SharingPolicy": "Restricted",
"ProductIdentifierType": "Lot"
}
},
"TraceabilityLotCode": "TLC-LOC-0001",
"TlcSource": {
"LocationName": "Upstream Processing Site",
"CompanyName": "Upstream Co.",
"City": "Up City",
"State": "Up State",
"Country": "Up Country",
"Line1": "456 Supplier Rd",
"Line2": "Unit 12",
"PostalCode": "67890",
"Phone": "+19876543210",
"Type": "MasterData",
"GeoCoordinates": {
"Latitude": 34.052235,
"Longitude": -118.243683
}
}
},
{
"Quantity": 70.75,
"LotSerial": "LOT-001-B",
"Product": {
"Id": "prod_002",
"Details": {
"Name": "RawGoods",
"SimpleUnitOfMeasurement": "Lbs",
"SharingPolicy": "Restricted",
"ProductIdentifierType": "Lot"
}
},
"TraceabilityLotCode": "TLC-LOC-0002",
"TlcSource": {
"Type": "Identifier",
"Reference": "Eg: BAP",
"Identifier": "BAP01283"
}
}
],
"Container": {
"Id": "1111",
"Type": "LogisticId"
},
"Id": "12",
"PurchaseOrder": "PO-1990091",
"InvoiceNumber": "INV-12314154",
"BizStep": "urn:epcglobal:cbv:bizstep:disaggregation",
"Disposition": "urn:epcglobal:cbv:disp:active",
"EventTime": "2024-03-30T17:00:00+00:00",
"EventTimeZone": "-05:00",
"CustomProperties": [
{
"Name": "expiry_date",
"Namespace": "",
"Value": "2024-09-30",
"PropertyLocation": "ILMD"
}
],
"CertificationList": [
{
"Type": "urn:gdst:certType:harvestCoC",
"Standard": "MSC Chain of Custody",
"Agency": "MSC",
"Value": "YES",
"Identification": "MSC-COC-000123"
}
]
}
]
}
data = {
"Events": [
{
"$type": "disaggregation",
"Location": {
"Id": "4567",
"Details": {
"TradePartner": {
"Id": "TpId123",
"Name": "Me",
"ConnectionType": "SELF",
"Duns": "123456789"
},
"Name": "Processing",
"ContactInformation": {
"Name": "Contact Name",
"Phone": "+1234567890",
"Email": "contact@example.com"
},
"Address": {
"City": "City Name",
"State": "State Name",
"Country": "Country Name",
"AddressLine1": "123 Main St",
"AddressLine2": "Apt 4B",
"PostalCode": "12345",
"GeoCoordinates": {
"Latitude": 12.345678,
"Longitude": 98.765432
}
}
}
},
"ProductInstances": [
{
"Quantity": 120.00,
"LotSerial": "LOT-001-A",
"Product": {
"Id": "prod_001",
"Details": {
"Name": "RawGoods",
"SimpleUnitOfMeasurement": "Lbs",
"SharingPolicy": "Restricted",
"ProductIdentifierType": "Lot"
}
},
"TraceabilityLotCode": "TLC-LOC-0001",
"TlcSource": {
"LocationName": "Upstream Processing Site",
"CompanyName": "Upstream Co.",
"City": "Up City",
"State": "Up State",
"Country": "Up Country",
"Line1": "456 Supplier Rd",
"Line2": "Unit 12",
"PostalCode": "67890",
"Phone": "+19876543210",
"Type": "MasterData",
"GeoCoordinates": {
"Latitude": 34.052235,
"Longitude": -118.243683
}
}
},
{
"Quantity": 70.75,
"LotSerial": "LOT-001-B",
"Product": {
"Id": "prod_002",
"Details": {
"Name": "RawGoods",
"SimpleUnitOfMeasurement": "Lbs",
"SharingPolicy": "Restricted",
"ProductIdentifierType": "Lot"
}
},
"TraceabilityLotCode": "TLC-LOC-0002",
"TlcSource": {
"LocationName": "Harbor Cold Storage",
"CompanyName": "Harbor Foods Ltd.",
"City": "Harbor City",
"State": "Harbor State",
"Country": "Harbor Country",
"Line1": "789 Harbor Ave",
"Line2": "Dock 3",
"PostalCode": "45678",
"Phone": "+12125550123",
"Type": "MasterData",
"GeoCoordinates": {
"Latitude": 40.712776,
"Longitude": -74.005974
}
}
}
],
"Container": {
"Id": "1111",
"Type": "LogisticId"
},
"Id": "12",
"PurchaseOrder": "PO-1990091",
"InvoiceNumber": "INV-12314154",
"BizStep": "urn:epcglobal:cbv:bizstep:disaggregation",
"Disposition": "urn:epcglobal:cbv:disp:active",
"EventTime": "2024-03-30T17:00:00+00:00",
"EventTimeZone": "-05:00",
"CustomProperties": [
{
"Name": "expiry_date",
"Namespace": "",
"Value": "2024-09-30",
"PropertyLocation": "ILMD"
}
],
"CertificationList": [
{
"Type": "urn:gdst:certType:harvestCoC",
"Standard": "MSC Chain of Custody",
"Agency": "MSC",
"Value": "YES",
"Identification": "MSC-COC-000123"
}
]
}
]
}