Create an EventCreate a Disaggregation event

Create a Disaggregation Event

Create a Disaggregation Event. The request example includes all fields documented for this event, including optional fields.

curl -X POST "https://connect.wholechain.com/Integration/Events" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: example_string" \
  -d '{
  "Events": [
    {
      "$type": "disaggregation",
      "Location": {
        "Id": "warehouse_001",
        "Details": {
          "TradePartner": {
            "Id": "my_company",
            "Name": "My Company",
            "ConnectionType": "SELF",
            "Duns": "987654321"
          },
          "Name": "Main Warehouse",
          "Gln": "9506000140446",
          "Extension": "WarehouseExtension",
          "DunsPlus4": "1234",
          "ContactInformation": {
            "Name": "Warehouse Contact",
            "Phone": "+1234567891",
            "Email": "warehouse@example.com"
          },
          "Address": {
            "City": "Cape Town",
            "State": "Western Cape",
            "Country": "South Africa",
            "AddressLine1": "456 Warehouse Road",
            "AddressLine2": "Building 2",
            "PostalCode": "8002",
            "GeoCoordinates": {
              "Latitude": -33.925,
              "Longitude": 18.425
            }
          }
        }
      },
      "Container": {
        "Id": "container_001",
        "Type": "LogisticId"
      },
      "ProductInstances": [
        {
          "Quantity": 190.75,
          "LotSerial": "lot_001",
          "Product": {
            "Id": "product_001",
            "Details": {
              "ProductIdentifierType": "Lot",
              "Name": "Sample Product",
              "SimpleUnitOfMeasurement": "Kgm",
              "SharingPolicy": "Open",
              "UnitDescriptor": "Cases",
              "UnitQuantity": 10.5,
              "Gtin": "12345678912343",
              "Plu": "4001",
              "MasterData": [
                {
                  "name": "Gear Type",
                  "namespace": "custom",
                  "value": "GEAR TYPE_VALUE"
                }
              ]
            }
          }
        }
      ],
      "Id": "disaggregation_001",
      "PurchaseOrder": "PO-12345",
      "InvoiceNumber": "INV-12345",
      "EventTime": "2024-03-30T17:00:00",
      "EventTimeZone": "-05:00",
      "CustomProperties": [
        {
          "Name": "quality_grade",
          "Namespace": "custom",
          "Value": "A"
        }
      ],
      "CertificationList": [
        {
          "Type": "urn:gdst:certType:harvestCoC",
          "Standard": "MSC Chain of Custody",
          "Agency": "MSC",
          "Value": "YES",
          "Identification": "MSC-C-12345"
        }
      ]
    }
  ]
}'

{
  "message": "Events processed successfully",
  "result": [
    {
      "id": "01a0d877-7871-79a5-a8c8-a2f45673633d",
      "externalEventId": "disaggregation_001",
      "type": "Disaggregation",
      "status": "Created",
      "eventDate": "2024-03-30T17:00:00+00:00",
      "productInstances": [
        {
          "quantity": 190.75,
          "lotSerial": "lot_001",
          "status": "Created",
          "id": "01a0d877-7871-7426-b365-3a587ad4f893",
          "name": "Raw Goods",
          "urn": "urn:gdst:wholechain.com:product:lot:class:raindropsolutions.rawgoods-1.lot_001"
        }
      ],
      "containers": [
        {
          "id": "container_001",
          "status": "Created"
        }
      ],
      "directShipFallback": null,
      "externalShipmentFailure": null
    }
  ],
  "locations": [
    {
      "id": "01a0d877-76de-7e96-ac8c-962a914952bf",
      "status": "Created"
    }
  ],
  "products": [
    {
      "id": "01a0d877-7719-720e-8fd8-224e3fec0602",
      "status": "Created"
    }
  ],
  "errors": [],
  "validations": []
}
POST
/Integration/Events
POST
Base URLstring

Target server for requests. Edit to use your own host.

Content-Typestring
Required

The media type of the request body

Options: application/json
header
X-API-KEYstring
Required

API key used to authenticate the request.

Eventsarray
Required

Required. events.

Request Preview
Response
Response will appear here after sending the request


Responses


messagestring
Optional. message.
resultarray
Optional. result.
locationsarray
Optional. locations.
productsarray
Optional. products.
errorsobject[]
Optional. errors.
validationsobject[]
Optional. validations.


Introduction


A Disaggregation event represents products being separated from an existing aggregation.


It is the reverse of an Aggregation event.


The products themselves do not change. They are simply removed from the Container or logistical unit so that they can once again be treated as individual traceable Product Instances.


A Disaggregation event can only occur after an Aggregation event has already taken place.


The purpose of this endpoint is to create a Disaggregation event in Wholechain.


Products being separated from a container back into individual traceable units
Products being separated from a container back into individual traceable units




Creating a Disaggregation Event


To create a Disaggregation event, submit an event payload containing:


    

  • The event information
    • 

  • The Location where the disaggregation takes place
    • 

  • The Container being disaggregated
    • 



The Container must already exist as the result of a previous Aggregation event.


Use the Required column in the tables below to determine which fields must be provided.




Request Body Parameters


Event Object


Column NameData TypeDescriptionRequired
IdSTRINGUnique identifier for the Disaggregation event.Yes
PurchaseOrderSTRINGPurchase order associated with the event.No
InvoiceNumberSTRINGInvoice number associated with the event.No
EventTimeDATETIMELocal date and time when the event occurred, without a UTC offset, for example 2024-03-30T13:00:00. The time zone is taken from EventTimeZone. Any offset included in this value is ignored.Yes
EventTimeZoneSTRINGOptional. Time zone of the event as a UTC offset in ±HH:MM format, for example -05:00. If omitted, the account's default time zone (selected when the account was created) is used.No




Location Object


Every Disaggregation event must identify the Location where the Container is being disaggregated.


Column NameData TypeDescriptionRequired
Location.IdSTRINGUnique identifier for the Location where the disaggregation takes place.Yes


The Location.Id must reference an existing Location in Wholechain.


Example:


"Location": {
  "Id": "4567"
}





Container Object


The Container object identifies the existing aggregation that should be disaggregated.


Column NameData TypeDescriptionRequired
Container.IdSTRINGUnique identifier of the Container being disaggregated. If both an SSCC and Logistic ID exist, use the SSCC as the identifier.Yes


Example:


"Container": {
  "Id": "1111"
}



The supplied Container.Id must reference a Container that was previously created through an Aggregation event.


Wholechain uses this Container to determine which Product Instances are part of the aggregation.




How Disaggregation Works


A Disaggregation event reverses an existing aggregation.


For example:


    

  • 50 cartons of strawberries were previously aggregated onto a pallet.
    • 

  • The pallet arrives at a retail Location.
    • 

  • The pallet is disaggregated.
    • 

  • The 50 cartons become individually available again.
    • 



No new Products or lots are created as part of the Disaggregation event.


Wholechain uses the existing aggregation to determine which Product Instances should be released from the Container.




Example Disaggregation Event Payload


The example below shows a standard Disaggregation event.


{
  "Events": [
    {
      "$type": "disaggregation",
      "Location": {
        "Id": "4567"
      },
      "Container": {
        "Id": "1111"
      },
      "Id": "12",
      "PurchaseOrder": "PO-1990091",
      "InvoiceNumber": "INV-12314154",
      "EventTime": "2024-03-30T17:00:00",
      "EventTimeZone": "-05:00"
    }
  ]
}



Refer to the Required column in the tables above to determine which fields must be supplied.




How Wholechain Processes the Payload


When a Disaggregation event is submitted, Wholechain uses the information in the payload in the following order:


    

  1. Identify the Location using Location.Id.
    2. 

  2. Identify the existing aggregation using Container.Id.
    3. 

  3. Confirm that the Container is associated with a previous Aggregation event.
    4. 

  4. Identify the Product Instances currently contained within that aggregation.
    5. 

  5. Remove those Product Instances from the Container.
    6. 

  6. Return the Product Instances to an individually traceable state.
    7. 

  7. Create the Disaggregation event.
    8. 



The Product Instances themselves are not transformed or changed by this event.


The Disaggregation event only removes the grouping created by the previous Aggregation event.




Custom Properties and Certifications


A Disaggregation event can also contain Custom Properties and Certifications when additional traceability information needs to be recorded.


These fields are not included in the standard Disaggregation example above.


For information about how to include them in your payload, see:



Was this page helpful?