Inventory Issue Builder - Nioron07/Easy-Acumatica GitHub Wiki

This guide covers the InventoryIssueBuilder, which is your primary tool for creating the JSON payload needed to create InventoryIssue records with the InventoryService.

1. Importing the InventoryIssueBuilder

To get started, import the InventoryIssueBuilder from the models directory.

from easy_acumatica.models.inventory_issue_builder import InventoryIssueBuilder

2. Understanding the Builder's Purpose

When you send data to Acumatica's contract-based API, each field must be wrapped in a specific JSON structure, such as {"value": ...}. The InventoryIssueBuilder handles this formatting for you automatically, allowing you to construct a valid payload using a fluent, chainable interface.

3. InventoryIssueBuilder Methods

The following table summarizes the primary methods available in the InventoryIssueBuilder.

Method	Description	Parameters
`.set()`	Sets any top-level field on the inventory issue.	`field` (str), `value` (Any)
`.date()`	Shortcut for setting the `Date`.	`date` (str)
`.description()`	Shortcut for setting the `Description`.	`description` (str)
`.post_period()`	Shortcut for setting the `PostPeriod`.	`period` (str)
`.add_detail()`	Adds a detail line to the issue.	`**kwargs` (e.g., `inventory_id="...", quantity=10`)
`.to_body()`	Constructs the final JSON payload.	(None)

4. Building an Inventory Issue Payload

You can set top-level fields using the generic .set() method or one of the convenient shortcut methods.

Adding Detail Lines

The most important part of an inventory issue is its detail lines. The .add_detail() method allows you to add these lines by passing keyword arguments for each column in the line.

Example: Building a complete issue

# 1. Create a builder instance
issue_payload = (
    InventoryIssueBuilder()
    .date("2023-10-27T00:00:00")
    .description("Materials for internal project")
    .add_detail(
        InventoryID="RAW-MAT-01",
        Warehouse="MAIN",
        Location="R01S01",
        Quantity=10,
        UOM="EACH",
        ReasonCode="PROJECT"
    )
    .add_detail(
        InventoryID="FIN-GOOD-02",
        Warehouse="MAIN",
        Location="R02S03",
        Quantity=5,
        UOM="EACH",
        ReasonCode="PROJECT"
    )
)

5. Generating the Final JSON Body

Once you have set all the required fields and details, call the .to_body() method to generate the final dictionary. This dictionary is formatted correctly and is ready to be sent as the JSON body in your API request.

# 1. Build the issue
issue_payload = (
    InventoryIssueBuilder()
    .date("2023-10-27T00:00:00")
    .description("Materials for internal project")
    .add_detail(InventoryID="RAW-MAT-01", Warehouse="MAIN", Quantity=10)
)

# 2. Get the final dictionary
json_body = issue_payload.to_body()

# The json_body will look like this:
# {
#     "Date": {"value": "2023-10-27T00:00:00"},
#     "Description": {"value": "Materials for internal project"},
#     "Details": [
#         {
#             "InventoryID": {"value": "RAW-MAT-01"},
#             "Warehouse": {"value": "MAIN"},
#             "Quantity": {"value": 10}
#         }
#     ]
# }

6. Complete Example with InventoryService

Here is a complete example of how to use the InventoryIssueBuilder to create a new inventory issue.

from easy_acumatica.models.inventory_issue_builder import InventoryIssueBuilder

# 1. Build the inventory issue payload
issue_to_create = (
    InventoryIssueBuilder()
    .description("Issue for project #123")
    .add_detail(
        InventoryID="PROJ-ITEM",
        Warehouse="PROJECTS",
        Quantity=25,
        UOM="BOX"
    )
)

# 2. Use the payload with the InventoryService to create the record
try:
    new_issue = client.inventory.create_inventory_issue(
        "24.200.001",
        builder=issue_to_create
    )
    print(f"Successfully created inventory issue: {new_issue['ReferenceNbr']['value']}")
except Exception as e:
    print(f"Failed to create inventory issue: {e}")