AcumatiCares
In my post today, I would like to explore the use of Acumatica’s REST-based API to create a shipment allocations, along with creating the packages and their related line-item details.
More specifically, I plan to focus on three discreet tasks:
- Assign shipment allocations to individual shipment lines;
- Create packages for shipment; and
- Assign the package contents to certain packages
We will begin with an open shipment that expects shipment line allocations. Let’s see what the Default endpoint has available to accomplish the tasks.
Upon first review of the Default endpoint, we see specific entities which helps with the first two tasks:
- Details / Allocations
- Packages
Unfortunately, the Default endpoint does not expose the entity for Package contents as you can see below.
Since the Default endpoint does not expose this entity, we must extend it. Let’s accomplish that task right away.
Use the option to extend the Default endpoint. Or create your own custom endpoint if you wish.
In our case, we will extend the Default entity. Drill down to the Shipment entity. Using the Packages detail entity as the base, create a new child detail entity which will allow us to include an array of type Packages.
Be sure to assign the entity fields.
Use the Validate Entity option to ensure no issues with your new endpoint extension.
Now we have an endpoint which will accomplish all our tasks.
Now we are ready for the first task: assign the allocations to the shipment line. Here is an example, how to create allocations for a shipment. It creates two allocations for a shipment item. We use the Shipment entity, and submit a payload that contains the Details array, as well as the Allocation array. Be sure to include the shipment number in your JSON payload:
Execute the API call and notice the results in the shipment entry screen. When we take a look at the allocation for the shipment item, we see the allocation results for the shipment line.
So far so good. Next, we will create the shipment packages. Below is an example how to create two shipment packages for the shipment record. Notice that we will create a new PUT request for the Shipment resource. Also includes in the URI are two parameters, indicating the shipment number and to expand the packages entity. We need the results of the packages entity, in order to specify particular packages that will receive the package details. Finally, we include the Package details in our payload. Below is our next PUT.
Process with the API call and notice the results in the shipment entry screen. Our two packages are created.
Notice the Body returned from the PUT method. There are key pieces of information in the Packages array, and you will them need in a moment.
Upon review of the Acumatica help portal, we see the description of the ID entity:
The entity ID is a GUID that is assigned to each entity you work with during an Acumatica ERP session. You can obtain the value of the entity ID from the ID property of an entity returned from Acumatica ERP. The records of top-level entities that you retrieve through the contract-based API have persistent IDs, which are the values in the NoteID column of the corresponding database tables. That is, you can use the value from the ID property of a top-level entity returned from Acumatica ERP throughout different sessions with Acumatica ERP. However, if a record does not have a note ID (which could be the case for detail entities, entities that correspond to generic inquiries, or custom entities), this record is assigned the entity ID that is new for each new session. That is, after a new login to Acumatica ERP, you cannot use the entity ID that you received in the previous session to work with the entity.
In this case, the ID entity helps us define the individual packages which were created. We will use those ID values in a moment.
Next we are ready to add an allocation item to a particular package, yes? There is one important detail missing. Each shipment package content record requires the forehand knowledge of the shipment line split number. That field makes up the primary key for each record in the package contents grid.
Unless you know the split line numbers by heart, you must query for them. REST-based API to the rescue!!
Let’s create a simple GET request and include the expand parameter. We must view the details of all allocation records, in the shipment.
GET / entity/ExtendedDefault/18.200.001/Shipment/0000032?$expand=Details/Allocations HTTP/1.1
Host: YourERPInstance
Content-Type: application/json
Return body (partial)
Notice there are two pieces of information in our body that we need for our final API request.
ID – this uniquely represents the shipment number.
SplitLineNbr – this represents the allocation line number, for a particular shipment line.
With this information, we can identity all allocations. This allows us to create a package detail record and assign the allocation to a particular package. We will build the final PUT request and assign the allocations to a package. Let’s take a look at the next example
In the payload, be sure to assign the shipment ID entity, package entity, as well as a Packages array. In your packages array, you pass the shipment allocation line numbers, represented as ShipmentSplitLineNbr entity.
The allocations are added to the package:
Summary
Today we looked at how to using Acumatica’s REST-based API in order to create a shipment allocations. Also we showed how you are able to create the packages and package details. Our main goal was how we were to accomplish the following three tasks:
- Assign shipment allocations to individual shipment lines;
- Create packages for the shipment; and
- Assign the package contents to certain packages
By adding the shipment package contents entity to your REST API endpoint, you will be able to expose the necessary elements in order to create the shipment package details. The Acumatica Contract-based API allows us to connect with the endpoint allocate the shipment lines. Further, provides you the power to create the shipment packages. With additional API calls, you can query the unique identifier ID values for the shipment allocation details. With those values, you are able to assign the serial numbers to the shipment packages.
I hope this post is helpful and provided you the basis for how you can assign shipment allocations to specific packages.
