基于Acumatica REST API的客户与销售订单字段匹配及技术问询

I’ve worked on several projects involving CSV-to-Acumatica data imports via the REST API, so I know how tricky field mapping and endpoint quirks can be. Let’s break down your questions one by one:

1. How to get JSON structure-to-Endpoint mapping docs, and know when to use sub-objects? #

Acumatica actually provides built-in tools to map fields without guessing:

• Endpoint Metadata: Navigate to your Endpoint (Default/18.200.001 in your case), select the target entity (like Customer), and click the Metadata button. This shows the full JSON schema, including nested sub-objects (e.g., MainContact for customer contact details). You’ll see exactly which fields belong to parent vs. child entities.
• Metadata API Call: Send a GET request to GET /entity/Default/18.200.001/metadata/Customer (replace Customer with your target entity). The response will list every field’s path, data type, and whether it’s read/writeable.
• Rule of thumb for sub-objects: Use nested structures whenever the field belongs to a related entity (not the main entity you’re targeting). For example, MainContact is a sub-object because contact info is a separate linked record in Acumatica, not a direct attribute of the Customer entity.

2. Can we get the full JSON format of a record (like GET-SELECT ALL-EXPAND ALL)? #

Absolutely—this is one of the most useful tricks for debugging field mapping:

• UI Test Tool: In your Endpoint’s Test tab, select the GET operation for your entity, enter a record ID, and check the Expand all related entities box. Run the test, and you’ll get the full JSON structure with all nested sub-objects and fields.
• API Request with $expand: Use the $expand query parameter to pull in related entities. For example, to get a Customer with all linked Order Summary data, use:

  GET /entity/Default/18.200.001/Customer/{CustomerID}?$expand=OrderSummary
  

  This returns the full nested JSON, so you can see exactly where fields like Gift Message live in the structure.

3. Why can’t Gift Message and Public Comment update like Description? #

This is almost certainly an entity or field mapping issue:

• Wrong Entity Context: Gift Message and Public Comment belong to Sales Order’s Order Summary, not the Customer entity. If you’re trying to update them via the Customer Endpoint, that won’t work—you need to target the Sales Order Endpoint instead.
• Nested Structure Requirement: Even if you added these fields to the Customer Endpoint via extension, they’re likely part of a nested OrderSummary sub-object. Your update JSON needs to include that nesting, like:

  {
    "OrderSummary": {
      "GiftMessage": "Happy Holidays!",
      "PublicComment": "Please ship via overnight delivery"
    }
  }
  

• API Permissions & Visibility: Check if these fields are enabled for API access in Acumatica’s Customization Editor. Some custom or extended fields default to not being exposed via REST. Also, if they’re system fields, ensure your Endpoint has included the Order Summary related entity with write permissions.

4. Why can’t I expand Sales Order Payments without errors? #

There are a few common culprits here:

• Endpoint Related Entity Access: By default, some related entities (like Payments) aren’t exposed in the Endpoint. Go to your Sales Order Endpoint configuration, find the Related Entities section, add Payments, and grant read/write permissions as needed.
• API User Permissions: The user account your API uses might not have access to the Payment screen (AR302000) in Acumatica. Verify the user’s role has the necessary rights to view/edit payments.
• Version-Specific Bug: Your Acumatica version (18.200.001) is a bit older. Some related entity expansion issues were fixed in later releases. If possible, test with a newer version, or check Acumatica’s release notes for known fixes in your version.
• Incorrect $expand Syntax: Make sure your request uses the correct entity name for Payments. For example, it might be PaymentTransactions instead of Payments—use the Metadata tool to confirm the exact name.

Pro Tip #

When in doubt about a field’s exact JSON path, pull an existing record that has the field populated using the expanded GET request. Compare the returned JSON structure to your update payload—this will quickly show you if you’re missing a nested object or using the wrong field name.

内容的提问来源于stack exchange，提问作者MarkJoel60