# acumatica-assistant

Adopt this skill: https://proskills.md/skills/other/fdtaljaard-claude-skills-skills-acumatica-assistant

Page: https://proskills.md/skills/other/fdtaljaard-claude-skills-skills-acumatica-assistant
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/acumatica-assistant/SKILL.md
size: 23806
sha: 96e80ef7744ef273558fd370eba48bf2f5631881
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/SKILL.md

````text
---
name: acumatica-assistant
description: "Acumatica ERP assistant for consultants and integrators. Use for anything Acumatica, even if the user only says \"Acumatica\", an endpoint path (/entity/Default/24.200.001, /api/odata/dac), an entity or DAC name (SalesOrder, SOOrder), a form ID (SO301000), Contract Version 4/5, OData, Excel or Power BI feeds, push notifications or connected apps. Capabilities - (1) REST integration development: generate and review requests and code against the contract-based REST API from a bundled extraction of the Integration Development Guide (2026 R2): sign-in and OAuth, endpoint and contract versions, JSON shape, $filter/$expand/$select, CRUD, actions, inquiries, custom fields, license limits, push notifications, webhooks, 187 documented examples, exact names from a Default/25.200.001 contract snapshot. (2) OData data access: DAC-based and inquiry-based OData v4 reads from the Reporting Tools Guide (2026 R2) plus a 2026 R2 DAC $metadata snapshot for exact DAC, field and navigation names. Trigger on any Acumatica question."
compatibility: "Runtime needs file read + grep over the bundled references. Refreshing references needs web access to beacon.acumatica.com, a clean Acumatica instance for swagger.json and the OData $metadata, and Python 3.10+ (scripts/); none of that is needed to answer questions."
metadata:
  author: Francois Taljaard
  version: "2026.10.3"
  domain: Acumatica ERP
---

# Acumatica Assistant

> **Version disclaimer:** the bundled references are extracted from the **2026 R2** editions of Acumatica's
> Integration Development Guide and Reporting Tools Guide (both edition 2026-09-30). The REST examples use the
> `Default/26.200.001` endpoint and **Contract Version 5**; the OData examples use the
> `/t/<TenantName>/api/odata/{dac,gi}` URLs. A client on an earlier release has older `Default` endpoints with
> **Contract Version 4** syntax and may use the pre-2026 `/OData` (OData 3.0) and `/ODatav4` paths, and every
> instance has its own custom endpoints, customizations, inquiries and user-defined fields. State which release,
> endpoint or interface and contract version you assumed in every answer, and tell the user to confirm entity, DAC,
> field and action names on their instance (`swagger.json`, the Web Service Endpoints (SM207060) form, or
> `/api/odata/dac/$metadata`). The bundled contract snapshot (`references/endpoints/`) is exact for
> **`Default/25.200.001`** (2025 R2, Contract Version 4) only, and the DAC metadata snapshot
> (`references/odata/metadata/`) is a **clean 2026 R2** instance; elsewhere their names are a starting point to
> confirm, not a fact.

Reference-backed assistant for Acumatica ERP consultants and integrators. The rule that makes it trustworthy:
**every material claim comes from a bundled reference and is cited** — never from memory alone. URL shapes,
parameter syntax, header names, status-code meanings, OAuth scopes and DAC or field names are exactly the things a
model guesses plausibly and wrongly.

## 1. Route the request

| Request looks like | Go to |
|---|---|
| write, **review** or fix code or requests against the Acumatica **REST API**: sign in, OAuth / connected applications, read or query records, create or update a sales order / customer / item, run an action (release, confirm shipment), poll a long-running operation, processing forms, generic inquiry data, reports, attachments, custom or user-defined fields, `$filter` / `$expand` / `$select`, "why does my PUT not save", 422 / 429 / 412 errors, endpoint or contract versions, "which endpoint version for 2024 R2", license API limits | § 3 REST integration development |
| "stop polling, get notified of changes", push notifications, SignalR hub, "send data from HubSpot/Zapier into Acumatica", webhooks | § 3, using `references/rest/push-and-webhooks.md` |
| "is there an example of X in the docs", "how does Acumatica document creating a shipment" | § 3 step 3, `references/rest/examples-catalogue.md` |
| an exact REST name: "which entity is screen SO301000", "what fields does SalesOrder have", "is it `CustomerID` or `Customer`", "what can I `$expand` on Shipment", "which action releases a payment and what parameters does it take" | § 3 step 4, `references/endpoints/INDEX.md` |
| **read** Acumatica data for BI, reporting or sync through **OData**: `/api/odata/dac`, `/api/odata/gi`, `/OData`, `/ODatav4`, `$metadata`, Excel or Power BI "From OData Feed", expose a generic inquiry via OData, `_WithParameters`, `$filter` / `$expand` on DACs, deleted or archived records (`PX-ApiDeleted`, `px.GetDeletedRecords()`), CORS for OData, OData licence or roles, "review my Power Query / OData URL", "OData or REST for this?" | § 4 OData data access |
| an exact **DAC, field or navigation-property name**: "fields of SOOrder", "what type is InventoryItem.ItemStatus", "which DACs have LastModifiedDateTime", "how do I join SOOrder to the customer", "what is the OData entity set for Stock Items" | § 4 step 3, `references/odata/metadata/` |

Anything else (screen-based SOAP API, customization / graph / DAC development, SQL against the database, versions
and upgrades, how-to procedures in the UI) is a planned capability, see `MAINTENANCE.md`. Say so, answer what you can
with the caveat that it is not reference-backed, and note that the skill could be extended.

## 2. Ground rules

- **Verify, then cite.** Every URL pattern, parameter, header, status code, scope, role and rule you state must come
  from a file under `references/rest/` or `references/odata/`; say which file (and the guide topic it names). If the
  references do not cover something, say so rather than filling the gap from memory.
- **Never invent an entity, DAC, field, navigation-property or action name.** REST names come from the contract
  snapshot of `Default/25.200.001` (`references/endpoints/`, exact for that endpoint) or from the guide's own
  examples (`examples-catalogue.md`, `Default/26.200.001`). Name only entities, fields and actions found there, say
  which source and endpoint version each came from, and tell the user to confirm them on their endpoint's
  `swagger.json` or `$adHocSchema` (see `rest-api-guide.md` § 2) whenever their endpoint is not the one the name
  was read from. OData names come from the 2026 R2 DAC metadata snapshot (`references/odata/metadata/`): say
  "verified in the 2026 R2 snapshot" and ask for confirmation on the client's `$metadata`; inquiry column names are
  tenant-specific, so derive them from the user's inquiry and the naming rules. Mark anything else as "to confirm on
  your instance".
- **Pin the release, endpoint or interface, and contract version first.** REST: the syntax of `$filter` /
  `$expand` / `$select`, drop-down values and custom fields differs between Contract Version 5
  (`Default/26.200.001`, custom endpoints created from scratch) and Contract Version 4 (`Default/25.200.001` and
  earlier). OData: the DAC-based and inquiry-based interfaces take different URLs, syntax and limits, and pre-2026
  releases document other paths. Ask which Acumatica release and which endpoint or interface the client uses if it
  changes the answer; otherwise default to 2026 R2 (`Default/26.200.001` / Contract Version 5;
  `/t/<TenantName>/api/odata/dac`) and say so. `GET <instance>/entity` and `GET <base>/$metadata` list what an
  instance exposes.
- **Writes go through the REST or SOAP API, never OData and never the database.** OData is read-only. Acumatica's
  supported integration paths are the REST, SOAP and OData APIs, push notifications and webhooks; do not propose SQL
  inserts or updates against the Acumatica database.
- **Prefer OAuth 2.0 / OIDC for new work** and say why: the guide announces that username/password sign-in
  will be discontinued. When the user insists on cookie sign-in, show it with the mandatory sign-out. For OData the
  guide documents basic auth; say what each choice costs in licence terms (conventional user versus API user).
- **Never put real credentials, client secrets, tokens or cookies in examples or logs.** Use placeholders.
- If the user reports a fact the references lack or contradict, say the reference should be updated
  (`MAINTENANCE.md`) rather than silently preferring either.

## 3. REST integration development

Generate or review HTTP requests and client code (any language) against the **contract-based REST API**.

1. **Pin the request**: Acumatica release and endpoint (`Default/<version>`, custom endpoint, `MANUFACTURING`),
   contract version (4 or 5), tenant and branch, authentication (cookie or OAuth flow), the business operation
   (read / query / create / update / action / inquiry / report / file), and what already exists (client,
   session handling). Ask when the release or the contract version changes the answer.
2. **Read** `references/rest/INDEX.md`, then `references/rest/rest-api-guide.md`; for the request shape read
   `references/rest/query-parameters.md`, for sign-in and tokens `references/rest/authentication.md`, for
   version questions `references/rest/endpoint-versions.md`, for change notification
   `references/rest/push-and-webhooks.md`. Read `references/rest/common-mistakes.md` before writing code so
   you produce the documented pattern and not the usual wrong one.
3. **Find the documented example** for the operation: grep `references/rest/examples-catalogue.md` by entity
   (`^## SalesOrder`), action (`/ConfirmShipment`), title words or `$expand=` names. The row gives the method,
   URL, query string and features the guide uses; its link gives the request body. Model the answer on it.
4. **Look up every exact name, never invent it.** Read `references/endpoints/INDEX.md` once, then grep the
   snapshot of `Default/25.200.001`, one entry per line: `entities.md` (entity, form ID, screen title),
   `fields.md` (`Schema.Field : Type`, e.g. `^SalesOrder\.`), `expand-paths.md` (`Entity: Path -> Schema`, what
   `$expand` accepts and which schema holds a nested entity's fields) and `actions.md`
   (`Entity.Action(Parameter: Type, ...)`). Never read `fields.md` whole. The snapshot is **one endpoint
   version**: for `Default/26.200.001` or an older `Default`, check the renames, removals and additions in
   `references/rest/endpoint-versions.md` § 3 and say the name must be confirmed on the instance; for a custom
   endpoint or `MANUFACTURING` it does not apply. It holds names and types only: no key fields, no mandatory
   flags, no drop-down values, no custom or user-defined fields.
5. **Build the request from the rules**: base URL `<instance>/entity/<Endpoint>/<Version>/`; PUT to create or
   update, PATCH for selected fields, GET by keys or ID or with `$filter`, DELETE by keys or ID, POST for
   actions with `{"entity": ..., "parameters": ...}`; `{"value": ...}` wrappers; **every nested entity in
   `$expand`**; contract-version-correct literals and nesting; headers `Accept` / `Content-Type` /
   `Cookie` or `Authorization: Bearer`; `If-None-Match: *` / `If-Match: *` when create-only / update-only
   matters; `PX-CbApiBranch` / `PX-CbApiBusinessDate` when the document must post to another branch or date.
6. **Handle the lifecycle**: 204 from an action means done (no `Location`); 202 means poll the `Location` URL
   with a delay and a ceiling until 204, then re-read the record and check its status; make creates idempotent
   with a deterministic reference of your own;
   422 bodies carry per-field `error`; 429 means the license limits (throttle, do not hammer); PUT/PATCH 200
   does not prove the save, so re-read fields that matter; sign out (or manage the OAuth session) in
   `finally`.
7. **Deliver**: one code or ```http block per request, then a short note: the endpoint and contract version
   assumed, which reference backed each protocol fact, which entity / field / action names are from the
   `Default/25.200.001` contract snapshot, which from the guide's examples and which still need confirmation on
   the instance (`swagger.json`, `$adHocSchema`, Inspect Element), and the feature switches the example requires.
   Offer a test plan (Postman or curl) as a follow-up.
8. **Reviewing existing code** ("review / audit / clean up my Acumatica integration"): grep the code for the
   "Looks like" patterns in `references/rest/common-mistakes.md`, verify each hit against the rule, check the
   entity, field and action names it uses against the snapshot (step 4) when the endpoint matches, and report
   data-affecting defects first (silent non-saves, wrong contract-version syntax, unhandled 202/422), then
   session and license hygiene (sign-out, scopes, throttling), then the rest. Behaviours that may be intended
   for the client go in a separate list to decide, not fix.

## 4. OData data access

Read data (never write) through the **DAC-based** (`/t/<TenantName>/api/odata/dac`) or **generic-inquiry-based**
(`/t/<TenantName>/api/odata/gi`) OData interface: BI feeds (Excel, Power BI), reporting extracts, delta syncs,
"which DAC or field holds X", and reviews of OData URLs or Power Query.

1. **Pin the request**: Acumatica release (2026 R2 URLs, or the 2024 R1 `/OData` OData 3.0 and `/ODatav4` paths),
   interface (DAC or inquiry), tenant login name, authentication (basic or OAuth), the consumer (browser, Postman,
   Excel, Power BI, code), the data (form or DAC, inquiry, fields, filters, delta, deletions), and whether the user
   can send their instance's `$metadata` or inquiry definition. Ask when the release or interface changes the answer.
2. **Read** `references/odata/INDEX.md`, then `references/odata/odata-guide.md` (§ 4–5 for DACs, § 6 for
   inquiries, § 2 for auth / roles / licence, § 7 for CORS, § 8 for Excel and Power BI, § 9 to choose between OData
   and REST). Read `references/odata/common-mistakes.md` before writing or reviewing a request.
3. **Look up every DAC, field and navigation name** in `references/odata/metadata/` (read its `INDEX.md` once):
   `entity-sets.md` for the URL names (`PX_Objects_SO_SOOrder`, `SalesOrder`, `SOOrder`), the key and the
   **non-filterable** fields; `api/INDEX.md` for the type's `File` / `Line` / `Lines`, then read that range of
   `api/members-NN.md`, or grep the bundles for `^PX\.Objects\.SO\.SOOrder\.` (all fields and navigations of a DAC)
   or `\.LastModifiedDateTime : ` (every DAC with that field). Never read a bundle whole. Field lines carry the UI
   display name in quotes, so map the user's wording through it; a `BaseType` means the key and most fields are on
   the base DAC; a navigation line `A.BAccountByCustomerID -> PX.Objects.CR.BAccount (CustomerID=BAccountID)` is the
   `$expand` name and the join. Inquiry columns are tenant-specific: derive names from the inquiry's captions by the
   naming rules (guide § 6) or ask for its `$metadata`. Mark each name "verified in the 2026 R2 snapshot" or "to
   confirm on your instance".
4. **Build the URL from the rules**: base URL and tenant; entity set (DAC) or inquiry title / `<Title>_WithParameters(...)`;
   `$select` of the needed fields only; `$expand=Nav($select=...)` within depth 3; `$filter` with stored values,
   integer foreign keys, navigation paths and `Any` / `All` / `$count` lambdas, bare OData 4.01 literals (`%2b` for
   `+`); `$orderby` with `$top` / `$skip`; headers `PX-ApiDeleted: SHOW`, `PX-ApiArchive: SHOW`, `Accept-Language`
   or `locale`; `px.GetDeletedRecords()` for deletions. Check every `$select` / `$filter` field against the entity
   set's non-filterable list and inquiry filters against the formula-column rule.
5. **Deliver**: one ```http block per request (for Excel or Power BI, the feed URL and the sign-in steps instead),
   then a short note: the release and interface assumed, which reference backed each fact, which names are
   snapshot-verified and which need confirmation on the instance, the licence impact (basic auth = conventional user,
   OAuth = API user) and the reminder that OData is read-only (writes: § 3). Offer the equivalent REST request when the
   user also needs to write.
6. **Reviewing existing requests** ("review my OData / Power Query / BI extract"): grep for the "Looks like"
   patterns in `references/odata/common-mistakes.md`; report wrong-data defects first (unbound inquiry parameters,
   200 without a body, formula-column filters, missing deletions in a delta sync, non-filterable fields), then
   authentication / licence / CORS, then the rest.

## 5. Gotchas (things a careful engineer still gets wrong)

REST API:

- **PUT creates and updates; POST runs actions.** A `POST .../Customer` is not a create. (`rest-api-guide.md` § 5–6.)
- **No `$expand`, no details.** Nothing nested comes back unless named, also on PUT/PATCH responses.
- **Contract Version 5 changed the shapes.** Drop-downs are `{"value": {"id": "CL", "description": "..."}}`
  and filter by ID; date-only fields are `YYYY-MM-DD`; custom fields need `type` and live in `$select`
  (`$custom` is CV4); nested `$select`/`$expand` use parentheses, not slash paths; `contains` replaces
  `substringof`; bare date-time literals replace `datetimeoffset'...'`. (`query-parameters.md`.)
- **PUT writes only what differs and graph logic wins**; PATCH submits regardless; **200 can mean nothing was
  saved** (view-only user, field not settable). Re-read. (`rest-api-guide.md` § 5.)
- **Filtering on detail lines is unsupported**; results are unpredictable.
- **Generic inquiries are read with PUT**, never GET, and need `$expand=<Results entity>`.
- **202 is "in progress"**: poll `Location` with a delay and a ceiling until 204; **204 straight away means done
  and carries no `Location`**, so never index that header unconditionally. Other requests on that form in the
  same session fail meanwhile. Processing forms need the filter PUT and the Process POST in the **same session**.
- **Detail-line and inquiry-row IDs are session-scoped**; only top-level entities have persistent IDs (NoteID).
- **Detail lines are deleted with PUT + `"delete": true`**, not DELETE.
- **No count parameter**: page with `$top`/`$skip` until a short page.
- **Sign out, always.** Unclosed sessions linger 10 minutes and exhaust the license's API session limit;
  trial licenses allow two sessions. OAuth with `api` only also opens a session (closes with the token after
  one hour); `api:concurrent_access` sessions must each be signed out. (`authentication.md`.)
- **The OAuth client ID is `<GUID>@<Tenant>`**, the shared secret is shown once, HTTPS is mandatory, and the
  Resource Owner Password flow is discouraged by Acumatica itself; discover endpoints via
  `/identity/.well-known/openid-configuration`.
- **Rate limiting is silent queuing**: past 50 % of the per-minute limit requests are delayed; more than 20
  queued or 10 minutes waiting is declined (429 on data requests).
- **Push notifications are retried up to five times when you answer with an error** (duplicates) and the
  SignalR destination loses messages with no client connected. Dedupe on `Id`.
- **Multilingual values**: the `[{en:..},{fr:..}]` form in `value` blanks unlisted languages; use the
  `Translations` property.
- **The schema name is not the name you send.** A detail is addressed by its field on the parent (`Details`,
  `$expand=Details/Allocations`), not by its schema (`SalesOrderDetail`). (`references/endpoints/INDEX.md`.)
- **Contract action names are longer than the form's.** `Default/25.200.001` names `Payment.ReleasePayment` and
  `ProjectTask.ActivateProjectTask`, while the guide's examples post to `Payment/Release` and
  `ProjectTask/Activate`, which the contract does not define (workflow-action route). Say which you used.
- **A name from one `Default` version is not a name on another.** `SalesOrder.LastModified` (25.200.001) is
  `LastModifiedDateTime` on 26.200.001; drop-downs are `StringValue` on Contract Version 4 and select types on 5.
- **A system endpoint version appears with its release** (`Default/26.200.001` with 2026 R2) and keeps
  working on later releases; Contract Versions 2–3 died in 2023 R2. Check `GET /entity`. (`endpoint-versions.md`.)

OData (`odata-guide.md`, `odata/common-mistakes.md`):

- **OData is read-only**, and there are **two interfaces with two base URLs**: DACs at `/api/odata/dac`, exposed
  inquiries at `/api/odata/gi`, both under `/t/<TenantName>/` (tenant login name, space as `%20`). 2024 R1 documents
  `/OData/<Tenant>` as **OData 3.0** (`$format=json`, `datetime'...'`) and `/ODatav4/<Tenant>`; on 2026 R2
  `/odatav4/<Tenant>` still works as an undocumented alias of the DAC URL (owner-verified), the inquiry path is
  untested: probe `$metadata`.
- **An inquiry with parameters must be called as `<Title>_WithParameters(Param='x')`**; the plain entity set does not
  bind parameters and returns an empty result without an error.
- **200 with no body is not "no rows"** on the inquiry interface: it means an unsupported query, typically a filter or
  sort on a formula column. Empty results come back as `{"value": []}`.
- **Non-filterable fields are also non-selectable** on DACs (`Cap.FilterRestrictions`; `NoteText`, `DocBal`,
  `CuryRate` and other unbound fields); `Filterable=false` bars every field a derived DAC declares itself.
- **DAC filters use stored values and integer keys** (`ItemStatus eq 'AC'`, `InventoryID eq 41`); inquiry filters use
  the displayed values (`'Active'`). Codes such as `InventoryCD` live on the related DAC: `$expand` it.
- **Inquiries have no `$expand` or `$count`**; DAC expansion stops at depth 3 (`maxExpansionDepth`); aggregation
  (`$apply`) is unsupported everywhere; `+` in a date-time offset is `%2b`.
- **Deletions do not show in a `LastModifiedDateTime` delta.** Track the DAC on SM207010 and read
  `<DAC>/px.GetDeletedRecords()`; `PX-ApiDeleted: SHOW` reveals soft-deleted rows, `PX-ApiArchive: SHOW` archived ones.
- **Basic-auth OData sign-ins are conventional users** (Concurrent Users on SM604000), not API users; OAuth sessions
  are API users. Roles: `BI` for the predefined `BI-*` inquiries, `OData4 User` for DAC-based access, View Only on
  an exposed inquiry; the username carries no tenant suffix.
- **Derived DACs inherit**: `Customer` lists only the fields it adds to `BAccount`; read the base entry too.

## 6. Layout

```
references/rest/   INDEX.md (sources, verified dates, known limits), rest-api-guide.md (start here), query-parameters.md,
                   authentication.md, endpoint-versions.md, examples-catalogue.md (generated), push-and-webhooks.md,
                   common-mistakes.md
references/endpoints/  INDEX.md (lookup recipes, sources, limits) and Default-25.200.001/ (generated from the
                   endpoint's swagger.json): entities.md, fields.md, expand-paths.md, actions.md
references/odata/  INDEX.md, odata-guide.md (start here), common-mistakes.md, and metadata/ (generated from a clean
                   2026 R2 instance's /api/odata/dac/$metadata): INDEX.md, entity-sets.md, api/INDEX.md,
                   api/members-01..06.md, enums.md
scripts/           maintenance only: fetch_beacon_guide.py (cache a guide from beacon.acumatica.com),
                   build_examples_catalogue.py (regenerate the catalogue), build_endpoint_reference.py (regenerate
                   an endpoint snapshot from its swagger.json), build_odata_metadata_ref.py + bundle_util.py
                   (regenerate the DAC metadata snapshot), package_skill.py — never needed to answer
evals/evals.json   test prompts per capability
MAINTENANCE.md     how to refresh the references for a new Acumatica release, add a capability
```

Every `references/` folder has an `INDEX.md` with sources and verified dates per file — read it first, open
only what the request needs.
````

## File: skills/acumatica-assistant/README.md
size: 10248
sha: 02436845a839253f69569e49fdd6d000be8d09d0
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/README.md

````text
# Acumatica Assistant

A reference-backed Claude skill for **Acumatica ERP** consultants and integrators. Ask in plain English and it
looks the answer up in a bundled extraction of Acumatica's own Integration Development Guide, cites where it
came from, and tells you what it could not verify. It never guesses an endpoint URL, a query-parameter syntax,
a header, a status-code meaning or an OAuth scope.

## What it does

| Ask about | What you get |
|---|---|
| **REST integration development** | Generate and review HTTP requests and client code (any language) against the contract-based REST API: cookie sign-in and OAuth 2.0 / OIDC (all four flows, scopes, refresh, session rules), endpoint and contract versions (`Default/20.200.001` to `Default/26.200.001`, Contract Version 4 vs 5), the JSON record shape, `$filter` / `$expand` / `$select` / `$custom` / `$top` / `$skip` per contract version, create / update / PATCH / delete rules, actions and long-running operations, processing forms, generic inquiries, reports, custom and user-defined fields, attachments, license limits on sessions and requests, push notifications and webhooks. Backed by a catalogue of the 187 example requests the guide documents, with links to each page, and a 36-row common-mistakes checklist for code reviews. |
| **Exact entity, field and action names** | Which entity a form is exposed as, the fields of an entity and of its nested detail and linked entities, what `$expand` accepts, and the actions an entity has with their parameters. Looked up in a snapshot generated from the OpenAPI document (`swagger.json`) of the `Default/25.200.001` system endpoint (2025 R2, Contract Version 4): 119 top-level entities, 5,338 fields, 575 expand paths, 163 actions. Exact for that endpoint; for other `Default` versions the skill applies the documented differences and tells you what to confirm. |
| **OData data access** | Read Acumatica data for BI, reporting and delta syncs through the two read-only OData interfaces, DAC-based (`/t/<Tenant>/api/odata/dac`) and generic-inquiry-based (`/t/<Tenant>/api/odata/gi`): URLs and tenant names (and the pre-2026 `/OData` and `/ODatav4` shapes), basic auth versus OAuth and what each costs in licence terms, the `BI` and `OData4 User` roles, `$select` / `$expand` / `$filter` (navigation paths, `Any` / `All` / `$count` lambdas), paging, archived and deleted records (`PX-ApiArchive`, `PX-ApiDeleted`, `px.GetDeletedRecords()`), multilingual fields, exposing inquiries and calling them with parameters, the inquiry interface's unsupported options, CORS and `Web.config`, Excel and Power BI feeds, and when to prefer OData over the REST API. Exact DAC, field and navigation-property names come from a bundled `$metadata` snapshot of a clean 2026 R2 instance (2,265 DACs, 42,288 fields with their UI display names, 23,576 navigation properties with their joins, 5,108 entity-set names, the non-filterable fields of each DAC), plus a 22-row common-mistakes checklist for reviewing OData URLs and Power Query. |

The skill switches itself on whenever your question is about Acumatica, even if you only mention an endpoint
path, an entity like `SalesOrder`, a DAC like `SOOrder`, a form ID like `SO301000`, OData, or "connected
applications". There is no command to run. More capabilities (SOAP, customization development, versions and
upgrades) are planned.

### Example prompts

- "Write a request that creates a sales order with two lines for customer ABAKERY on Acumatica 2026 R2, then releases it from hold."
- "Our Acumatica instance is 2024 R2. Give me the `$filter` and `$expand` to list stock items changed since yesterday with their warehouse quantities."
- "Set up OAuth for a background service that syncs invoices nightly. Which flow and scopes, and how do we refresh?"
- "My PUT returns 200 but the field is unchanged. Why?"
- "Review this Python Acumatica client" (paste the code).
- "We poll the API every minute for new shipments. Is there a push option?"
- "We're on 2025 R2. Which fields does a sales order line have, and what can I `$expand` on a shipment?"
- "Power BI needs open sales orders with customer name and line items, read-only, refreshed hourly. Give me the OData URL."
- "Which DAC and fields hold the warehouse quantity on hand, and how do I join it to the stock item code?"
- "Our nightly OData sync filters on LastModifiedDateTime but deleted customers never disappear downstream. What are we missing?"

## Install

There are two ways to use the skill, depending on where you use Claude.

### Option 1: Claude Code (terminal, desktop app Code tab, VS Code or JetBrains)

Add this collection once, then install the skill. Type these in Claude Code:

```
/plugin marketplace add fdtaljaard/claude-skills
/plugin install acumatica-assistant@fdtaljaard-skills
```

To update later: `/plugin marketplace update fdtaljaard-skills`. To remove: `/plugin uninstall acumatica-assistant@fdtaljaard-skills`.

### Option 2: Claude desktop app and claude.ai (uploaded skill)

The Claude desktop app and claude.ai accept a packaged skill file under **Settings, Capabilities, Skills**.

1. Get `acumatica-assistant.skill` from the [Releases page](https://github.com/fdtaljaard/claude-skills/releases).
   To build it yourself from this repository instead (needs Python 3.10+ and PyYAML):

   ```bash
   python skills/acumatica-assistant/scripts/package_skill.py skills/acumatica-assistant dist
   ```

   This validates the skill and writes `dist/acumatica-assistant.skill`.
2. In Claude, open **Settings, Capabilities, Skills** and upload the file.
3. If an older version of this skill is already listed, remove it first so only one copy triggers.

To update, upload the newer `.skill` file and remove the old one.

<details>
<summary>Other ways (developers)</summary>

With the [skills CLI](https://agentskills.io):

```bash
npx -y skills add fdtaljaard/claude-skills --skill acumatica-assistant --agent claude-code
```

Manually, copy the folder into your Claude skills directory (`~/.claude/skills/` for every project, or
`<project>/.claude/skills/` for one):

```bash
git clone https://github.com/fdtaljaard/claude-skills.git
cp -r claude-skills/skills/acumatica-assistant ~/.claude/skills/
```

</details>

## How it answers

Every material claim comes from a file in `references/` and is cited:

```
references/rest/   the REST API guide, query parameters per contract version, authentication and license limits,
                   endpoint and contract versions, the generated examples catalogue, push notifications and
                   webhooks, and the common-mistakes checklist
references/endpoints/  the Default/25.200.001 contract generated from its swagger.json: entities with form IDs,
                   every field, the expand paths and the actions with their parameters
references/odata/  the OData guide (both interfaces, auth, query options, headers, inquiries, CORS, Excel / Power BI,
                   OData versus REST), its common-mistakes checklist, and metadata/ — the DAC $metadata snapshot
                   of a clean 2026 R2 instance (entity-set names, a type index, bundled per-DAC field and
                   navigation lists with display names and joins)
```

Each folder's `INDEX.md` lists the sources, the edition or build and the verified date of every file. The skill
states which release, endpoint or interface and contract version it assumed. For the REST API it names only
entities, fields and actions that are in the `Default/25.200.001` contract snapshot or in the guide's own
examples, says which, and asks you to confirm them on your instance's OpenAPI document (`swagger.json`) or the
Web Service Endpoints (SM207060) form when your endpoint is a different one. For OData it names only DACs, fields
and navigation properties found in the 2026 R2 metadata snapshot and asks you to confirm them on your instance's
`$metadata`. No custom endpoint, inquiry, customization or user-defined field is bundled.

## Keeping it current and contributing

- [`SKILL.md`](SKILL.md) is what Claude loads; it describes routing, ground rules, the workflow and the gotchas.
- [`MAINTENANCE.md`](MAINTENANCE.md) explains how to refresh the references when Acumatica publishes a new
  release of the guide, and how to add a capability.
- [`evals/evals.json`](evals/evals.json) holds test prompts per capability.
- Corrections and additions are welcome. See the repository's [CONTRIBUTING.md](../../CONTRIBUTING.md).

## Privacy and data handling

Answers come from the bundled references only. The skill reads its own files, sends nothing anywhere, and has no
MCP server, hook, telemetry or backend. It writes code and queries as text and never connects to or runs anything
against your systems. The maintenance scripts in `scripts/` are never used to answer questions; when a maintainer
runs `fetch_beacon_guide.py` it downloads guide pages from beacon.acumatica.com. Your conversation with Claude is
covered by Anthropic's terms and privacy policy. See
[PRIVACY.md](https://github.com/fdtaljaard/claude-skills/blob/main/PRIVACY.md) for the full policy.

## Disclaimer

Acumatica is a trademark of Acumatica, Inc. This skill is independent and not affiliated with or endorsed by
Acumatica. Its references are a compact extraction of facts (URL patterns, parameters, headers, status codes,
JSON shapes, rules) from the **2026 R2** editions of Acumatica's publicly available Integration Development Guide
and Reporting Tools Guide on beacon.acumatica.com (plus one System Administration Guide topic and, for pre-2026
OData URLs, the I300 *Data Retrieval with OData* training course, 2024 R1), not a copy of those pages, and
Acumatica's own terms apply to that material. The entity, field and action names of one system endpoint
(`Default/25.200.001`, 2025 R2) are bundled as extracted from its OpenAPI document, and the DAC, field and
navigation names of a clean 2026 R2 instance as extracted from its DAC-based OData `$metadata` (no business data,
no customer customization); other endpoint versions and releases differ where the references say so and may
differ elsewhere. Confirm against Acumatica's documentation, and on the client's instance, before relying on any
of it.
````

## File: skills/acumatica-assistant/scripts/build_endpoint_reference.py
size: 14522
sha: 7a2062f64fb6a061fff4f8600ac366975ecf5280
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/scripts/build_endpoint_reference.py

````text
#!/usr/bin/env python3
"""Build references/endpoints/<Endpoint>-<Version>/ from an endpoint's swagger.json (maintenance only).

    python scripts/build_endpoint_reference.py --swagger <swagger.json> --out references/endpoints \
        --release "2025 R2" --build 25.201.0213 --verified YYYY-MM-DD [--source-note "..."] \
        [--scrub-to ../../sources/acumatica-assistant/<Endpoint>-<Version>.swagger.json]

The input is the OpenAPI 3.0 document of ONE endpoint (`GET <Base endpoint URL>/swagger.json`, or More > OpenAPI
3.0 on the Web Service Endpoints (SM207060) form). Use a system endpoint (`Default`): its contract is fixed by
Acumatica, so it is the same on every instance of that release. Never feed a custom endpoint or an endpoint
extension, which carry a customer's own entities and fields. The raw swagger stays outside the repository;
`--scrub-to` writes a copy with `servers` removed (the only instance-specific member), which is committed under
`sources/acumatica-assistant/` so the snapshot can be regenerated from it later.

Only names and types are extracted, into four fully regenerated files under <out>/<Endpoint>-<Version>/:
  entities.md      top-level entities with form ID, screen title and counts
  fields.md        one line per field of every entity schema: `Schema.Field : Type`
  expand-paths.md  one line per linked/detail path of every top-level entity: `Entity: Path -> Schema`
  actions.md       one line per action: `Entity.Action(Parameter: Type, ...)`
The instance URL in `servers` is never written, and nothing is written if any part of its host name (generic words
such as `erp` or `sandbox` excepted) shows up in the output.
It prints the counts for references/endpoints/INDEX.md and every `Usr`-prefixed name, which a maintainer must
confirm is Acumatica's own (the guide's Comparison of System Endpoints lists them) before committing.
"""
import argparse
import json
import os
import re
import sys
from functools import lru_cache
from urllib.parse import urlparse

BASE_ENTITY = "Entity"
SKIP_FIELDS = {"_workflowActions"}  # on every entity (workflow actions outside the contract); named once in entities.md
# Host-name labels that name a role or a vendor, not a customer, and so need not be absent from the output.
GENERIC_LABELS = {"www", "erp", "sandbox", "demo", "test", "uat", "dev", "stage", "staging", "prod", "api", "app",
                  "apps", "cloud", "portal", "acumatica", "com", "net", "org", "local", "localhost"}

def ref_name(node):
    return node["$ref"].rsplit("/", 1)[-1] if "$ref" in node else None

def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--swagger", required=True)
    ap.add_argument("--out", required=True, help="references/endpoints (the snapshot folder is created inside)")
    ap.add_argument("--release", required=True, help='Acumatica release of the instance, e.g. "2025 R2"')
    ap.add_argument("--build", required=True, help="build of the instance, e.g. 25.201.0213")
    ap.add_argument("--verified", required=True)
    ap.add_argument("--source-note", default="", help="where the swagger came from, without naming the instance")
    ap.add_argument("--scrub-to", default="", help="also write the swagger with `servers` removed to this path")
    a = ap.parse_args()

    doc = json.load(open(a.swagger, encoding="utf-8-sig"))
    endpoint = doc["info"]["title"]  # "Default/25.200.001"
    contract = doc["info"]["version"]
    schemas = doc["components"]["schemas"]
    paths = doc["paths"]

    def parts(name):
        return schemas[name].get("allOf", [schemas[name]])

    entities = sorted(n for n, s in schemas.items() if "allOf" in s and ref_name(s["allOf"][0]) == BASE_ENTITY)
    entity_set = set(entities)
    odd = set()

    @lru_cache(maxsize=None)
    def fields(name):
        """[(field, type text, nested schema or None, is array)] sorted by field name."""
        out = []
        for part in parts(name):
            for fname, node in part.get("properties", {}).items():
                if fname in SKIP_FIELDS:
                    continue
                is_array = node.get("type") == "array"
                target = ref_name(node.get("items", {}) if is_array else node)
                if target is None:
                    odd.add(f"{name}.{fname}")
                    target = node.get("items", {}).get("type", "?") if is_array else node.get("type", "?")
                out.append((fname, target + ("[]" if is_array else ""), target if target in entity_set else None, is_array))
        return tuple(sorted(out))

    top = []  # (entity, form, title)
    for t in doc.get("tags", []):
        m = re.match(r"^(.*?)\s*\(([A-Za-z0-9.]+)\)\s*$", t.get("description", ""))
        top.append((t["name"], m.group(2) if m else "", m.group(1) if m else t.get("description", "")))
    top.sort()
    top_names = [t[0] for t in top]
    missing = [n for n in top_names if n not in entity_set]
    if missing:
        sys.exit(f"tags without an entity schema: {missing}")

    actions = {}  # entity -> [(action, body entity, [(param, type)])]
    for p, item in paths.items():
        seg = p.strip("/").split("/")
        if len(seg) != 2 or seg[1].startswith(("{", "$")) or "post" not in item:
            continue
        body = schemas[ref_name(item["post"]["requestBody"]["content"]["application/json"]["schema"])]
        params = body["properties"].get("parameters", {}).get("properties", {})
        actions.setdefault(seg[0], []).append((
            seg[1],
            ref_name(body["properties"]["entity"]),
            [(k, ref_name(v) or v.get("type", "?")) for k, v in params.items()],
        ))

    expand = {}  # entity -> [(path, schema, is array)]
    reached = set()

    def walk(name, prefix, stack, out):
        for fname, _, nested, is_array in fields(name):
            if nested is None or nested in stack:
                continue
            reached.add(nested)
            out.append((prefix + fname, nested, is_array))
            walk(nested, prefix + fname + "/", stack + [nested], out)

    for name in top_names:
        expand[name] = []
        walk(name, "", [name], expand[name])
    orphans = [n for n in entities if n not in reached and n not in top_names]

    folder = os.path.join(a.out, endpoint.replace("/", "-"))
    note = f" ({a.source_note})" if a.source_note else ""
    header = (
        f"<!-- source: swagger.json (OpenAPI {doc.get('openapi', '3.0')}) of the {endpoint} system endpoint{note} | "
        f"version: Acumatica ERP {a.release}, build {a.build}, Contract Version {contract} | verified: {a.verified} | "
        "generated by scripts/build_endpoint_reference.py -->"
    )
    n_fields = sum(len(fields(n)) for n in entities)
    n_nested = sum(1 for n in entities for f in fields(n) if f[2])
    n_actions = sum(len(v) for v in actions.values())
    n_paths = sum(len(v) for v in expand.values())
    value_types = sorted(n for n, s in schemas.items() if "allOf" not in s and n.endswith("Value"))
    files = {}

    lines = [
        header,
        "",
        f"# {endpoint}: top-level entities",
        "",
        f"The {len(top)} entities that `{endpoint}` exposes at `/entity/{endpoint}/<Entity>`, with the form each is",
        "mapped to. `Fields` counts the value fields, `Nested` the linked and detail entities (each needs `$expand`),",
        "`Actions` the actions the contract names. Details: `fields.md`, `expand-paths.md`, `actions.md` in this folder.",
        "",
        f"Counts: {len(top)} top-level entities, {len(entities) - len(top)} nested entity schemas, {n_fields} fields "
        f"({n_fields - n_nested} value fields, {n_nested} linked/detail), {n_paths} expand paths, {n_actions} actions on "
        f"{len(actions)} entities ({sum(1 for v in actions.values() for x in v if x[2])} with parameters).",
        "",
        "Every entity also carries the system members `id`, `rowNumber`, `note`, `custom`, `error`, `files`, `_links` and",
        "`_workflowActions` (the form's workflow actions outside the contract, listed by `$adHocSchema`,",
        "`../../rest/rest-api-guide.md` § 2); they are not repeated per entity. Every top-level entity accepts the same",
        "requests (list, by keys, by ID, PUT,",
        "PATCH, DELETE, `files`, `$adHocSchema`) and `POST <Entity>/<action name>` for workflow actions that are not in",
        "the contract. The swagger does not name the key fields (`ids` is one slash-delimited path value): they are the",
        "form's keys, in the order the form defines them (`../../rest/rest-api-guide.md` § 5).",
        "",
        "| Entity | Form | Screen title | Fields | Nested | Actions |",
        "|---|---|---|---:|---:|---:|",
    ]
    for name, form, title in top:
        fs = fields(name)
        nested = sum(1 for f in fs if f[2])
        lines.append(f"| {name} | {form} | {title} | {len(fs) - nested} | {nested} | {len(actions.get(name, []))} |")
    if orphans:
        lines += ["", "Entity schemas in the swagger that no top-level entity references (listed in `fields.md` only): "
                  + ", ".join(f"`{n}`" for n in orphans) + "."]
    files["entities.md"] = lines

    lines = [
        header,
        "",
        f"# {endpoint}: fields",
        "",
        "One line per field of every entity schema (top-level and nested): `Schema.Field : Type`. Grep",
        "`^SalesOrder\\.` for an entity's fields or `\\.InventoryID ` for a field name across entities.",
        "",
        f"- A `...Value` type is a value field, sent and returned as `{{\"value\": ...}}`: {', '.join(value_types)}.",
        "  Contract Version 4 has no drop-down types: a drop-down is a `StringValue` and the swagger does not list its",
        "  allowed values.",
        "- Any other type is another schema in this file: a **linked entity** (`Address`) or, with `[]`, a **detail",
        "  entity** (`SalesOrderDetail[]`). Neither is returned unless named in `$expand` (`expand-paths.md`).",
        "",
        "```text",
    ]
    for name in entities:
        lines += [f"{name}.{fname} : {ftype}" for fname, ftype, _, _ in fields(name)]
    lines.append("```")
    files["fields.md"] = lines

    lines = [
        header,
        "",
        f"# {endpoint}: expand paths",
        "",
        "One line per linked or detail entity reachable from a top-level entity: `Entity: Path -> Schema`, `[]` for a",
        "detail (array). Grep `^SalesOrder: ` for everything `SalesOrder` can expand, or `-> Address` for where a",
        "schema is used. The path is the Contract Version 4 `$expand` value; a nested path needs its parent listed too",
        "(`$expand=Details,Details/Allocations`). Look the schema's fields up in `fields.md`.",
        "",
        "```text",
    ]
    for name in top_names:
        lines += [f"{name}: {path} -> {schema}{'[]' if is_array else ''}" for path, schema, is_array in expand[name]]
    lines.append("```")
    files["expand-paths.md"] = lines

    lines = [
        header,
        "",
        f"# {endpoint}: actions",
        "",
        "One line per action in the contract: `Entity.Action(Parameter: Type, ...)`. Invoke with",
        f"`POST /entity/{endpoint}/<Entity>/<Action>` and the body `{{\"entity\": {{...}}, \"parameters\": {{...}}}}`; the",
        "entity part identifies the record (its fields are in `fields.md`). Grep `^Shipment\\.` for an entity's actions.",
        "Workflow actions outside the contract are discovered with `<Entity>/$adHocSchema`.",
        "",
        "```text",
    ]
    for name in sorted(actions):
        for action, body_entity, params in sorted(actions[name]):
            sig = ", ".join(f"{k}: {v}" for k, v in params)
            other = f"  [entity body: {body_entity}]" if body_entity != name else ""
            lines.append(f"{name}.{action}({sig}){other}")
    lines.append("```")
    files["actions.md"] = lines

    # The instance must stay anonymous: every label of the host name, and every hyphen-separated part of a label,
    # must be absent from the output unless it is a generic word. A short label must be absent as a whole word
    # (`SalesOrder` is the words `sales` and `order`); a label of six or more characters as a substring too, so a
    # customer's name glued into an identifier (`ContosoOrder`) is caught. All files are checked before any is written.
    host = urlparse((doc.get("servers") or [{}])[0].get("url", "")).hostname or ""
    tokens = {t.lower() for label in host.split(".") for t in (label, *label.split("-"))}
    banned = {t for t in tokens if len(t) > 2 and t not in GENERIC_LABELS}
    texts = {fname: "\n".join(body) + "\n" for fname, body in files.items()}
    checks = dict(texts)
    if a.scrub_to:
        scrubbed = {k: v for k, v in doc.items() if k != "servers"}
        checks[a.scrub_to] = json.dumps(scrubbed, indent=1, ensure_ascii=False) + "\n"
    for fname, text in checks.items():
        lowered = text.lower()
        words = set(re.findall(r"[a-z0-9]+", re.sub(r"(?<=[a-z0-9])(?=[A-Z])", " ", text).lower()))
        hit = sorted(b for b in banned if b in words or (len(b) >= 6 and b in lowered))
        if host and host.lower() in lowered:
            hit.append(host)
        if hit:
            sys.exit(f"{fname} would contain the instance name {hit}; nothing written")
    os.makedirs(folder, exist_ok=True)
    for fname, text in texts.items():
        with open(os.path.join(folder, fname), "w", encoding="utf-8", newline="\n") as f:
            f.write(text)
    if a.scrub_to:
        os.makedirs(os.path.dirname(os.path.abspath(a.scrub_to)), exist_ok=True)
        with open(a.scrub_to, "w", encoding="utf-8", newline="\n") as f:
            f.write(checks[a.scrub_to])
        print(f"scrubbed swagger (servers removed) -> {a.scrub_to}")

    print(f"{endpoint} (Contract Version {contract}) -> {folder}")
    print(f"  {len(top)} top-level entities, {len(entities) - len(top)} nested entity schemas, {n_fields} fields, "
          f"{n_paths} expand paths, {n_actions} actions on {len(actions)} entities")
    usr = [f"{n}.{f[0]}" for n in entities for f in fields(n) if f[0].startswith("Usr")] + [n for n in entities if n.startswith("Usr")]
    print(f"  Usr-prefixed names to confirm as Acumatica's own: {usr or 'none'}")
    if odd:
        print(f"  fields with an inline type (no $ref): {sorted(odd)}")
    if orphans:
        print(f"  entity schemas not referenced by a top-level entity: {orphans}")

if __name__ == "__main__":
    main()
````

## File: skills/acumatica-assistant/scripts/build_examples_catalogue.py
size: 4832
sha: dacb4f2d8202791cf65b3d1f473bcc05c48452fe
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/scripts/build_examples_catalogue.py

```text
#!/usr/bin/env python3
"""Build references/rest/examples-catalogue.md from a cached Integration Development Guide (maintenance only).

    python scripts/build_examples_catalogue.py --cache <dir written by fetch_beacon_guide.py> --out references/rest/examples-catalogue.md --verified YYYY-MM-DD

For every topic under "REST API Examples" (the Basic Requests, the query-parameter topics and the per-entity
examples) the script extracts the facts a developer needs to find the right request shape, never the page text:
the topic title, the endpoint and entity in the request URL, every distinct request line (method, path and query
string, whitespace-collapsed) and the features the topic says must be enabled. One table row per topic, grouped
by entity, each row linking to the Beacon page. Re-run after every re-fetch; the file is fully regenerated.
"""
import argparse
import glob
import json
import os
import re

BASE = "https://beacon.acumatica.com"

def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--cache", required=True)
    ap.add_argument("--out", required=True)
    ap.add_argument("--verified", required=True)
    a = ap.parse_args()

    toc = json.load(open(os.path.join(a.cache, "toc.json"), encoding="utf-8"))
    meta = json.load(open(os.path.join(a.cache, "map.json"), encoding="utf-8"))
    version = next((m["values"][0] for m in meta.get("metadata", []) if m["key"] == "version"), "?")

    groups = {}
    order = []
    for i, t in enumerate(toc, 1):
        pu = t["prettyUrl"]
        if "/REST-API-Examples/" not in pu or t["depth"] != 2:
            continue
        files = glob.glob(os.path.join(a.cache, f"{i:03d}-*.md"))
        if not files:
            continue
        txt = open(files[0], encoding="utf-8").read()
        group = pu.split("/REST-API-Examples/")[1].split("/")[0]
        reqs = re.findall(r"^((?:GET|PUT|POST|PATCH|DELETE) /entity[^\n]*(?:\n[ \t]+[^\n]+)*)", txt, flags=re.M)
        reqs = [" ".join(r.replace(" HTTP/1.1", "").split()) for r in reqs]
        seen = []
        for r in reqs:
            if r not in seen:
                seen.append(r)
        feats = re.findall(r"make sure that (?:the )?([^.]*?) features? (?:are|is) enabled", txt, flags=re.S)
        feats = [" ".join(f.split()) for f in feats]
        feats = [f.split("form, make sure that the ")[-1] for f in feats]  # drop a preceding sentence when the regex spans one
        endpoints = sorted({m.group(1) for r in seen for m in [re.search(r"/entity/([A-Za-z0-9_.]+)/", r)] if m})
        if group not in groups:
            groups[group] = []
            order.append(group)
        groups[group].append({"title": t["title"], "url": BASE + pu, "requests": seen, "features": feats, "endpoints": endpoints})

    n = sum(len(v) for v in groups.values())
    lines = [
        f"<!-- source: Acumatica Integration Development Guide, REST API Examples ({BASE}/r/Integration-Development-Guide/REST-API-Examples) | version: Acumatica ERP {version} (guide edition {meta.get('lastEdition')}) | verified: {a.verified} | generated by scripts/build_examples_catalogue.py -->",
        "",
        "# REST API examples catalogue",
        "",
        f"One row per example topic in the guide's **REST API Examples** chapter ({n} topics in {len(groups)} groups), with the",
        "request lines the topic shows (method, path, query string) and the features it says must be enabled. The row tells you",
        "which entity, action and `$expand`/`$select` shape Acumatica documents for a task; open the linked page for the request",
        "body, which is not reproduced here. Request lines are whitespace-collapsed; `<Acumatica ERP host>` is omitted.",
        "",
        "Endpoints seen: `Default` (the system endpoint) and `MANUFACTURING` (manufacturing entities); both at version",
        f"`26.200.001` in the {version} guide. Replace the version with the one your instance exposes (`GET /entity`).",
        "",
        "Grep by entity (`^## SalesOrder`), by action (`/ConfirmShipment`), by title words or by `$expand=` names.",
        "",
    ]
    for g in order:
        lines.append(f"## {g}")
        lines.append("")
        lines.append("| Example | Request(s) | Features required | Page |")
        lines.append("|---|---|---|---|")
        for e in groups[g]:
            req = "<br>".join(f"`{r}`" for r in e["requests"]) or "(no request line in the topic)"
            feats = "; ".join(e["features"]) or ""
            lines.append(f"| {e['title']} | {req} | {feats} | [page]({e['url']}) |")
        lines.append("")
    os.makedirs(os.path.dirname(a.out), exist_ok=True)
    with open(a.out, "w", encoding="utf-8", newline="\n") as f:
        f.write("\n".join(lines))
    print(f"{n} examples in {len(groups)} groups -> {a.out}")

if __name__ == "__main__":
    main()
```

## File: skills/acumatica-assistant/scripts/build_odata_metadata_ref.py
size: 21644
sha: 141979234b57fe93e0cabd7a93af11ff3dda1677
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/scripts/build_odata_metadata_ref.py

```text
#!/usr/bin/env python3
"""Compile an Acumatica DAC-based OData v4 `$metadata` document into grep-friendly Markdown references (maintenance only).

    python scripts/build_odata_metadata_ref.py <metadata.xml> references/odata/metadata \\
        --verified YYYY-MM-DD --label "Acumatica ERP 2026 R2"

Fetch the metadata outside this script from a **clean** instance (never a customer's):
    GET <instance URL>/t/<TenantName>/api/odata/dac/$metadata
The document carries no instance-specific member, so a gzipped copy is committed under
sources/acumatica-assistant/ (the script reads .gz directly) for anyone to regenerate the snapshot. The script writes:

    INDEX.md            provenance, counts, how the files are meant to be read
    entity-sets.md      one row per DAC: every entity-set name (URL alias) that reaches it, the key, the fields the
                        metadata marks non-filterable / non-selectable, and singletons
    api/INDEX.md        one row per EntityType / ComplexType: key, counts, base type, entity sets, and the bundle
                        file + line range of its entry
    api/members-NN.md   the entries, bundled: a heading per type, then one line per field
                        (`Type.Field : Edm.Type [key] [required] "Display name"`) and per navigation property
                        (`Type.Nav -> Target (LocalField=TargetField)`), so a grep for `^PX.Objects.SO.SOOrder.` returns
                        the whole DAC and a grep for `\\.OrderNbr ` finds every DAC with that field
    enums.md            EnumType members (the DAC metadata has very few)

Use --exclude-regex to drop types whose fully qualified name matches (for example customization-project namespaces)
when the source instance is not clean; the generated INDEX.md records every filter used.
"""
from __future__ import annotations

import argparse
import re
import sys
import xml.etree.ElementTree as ET
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parent))
import bundle_util  # noqa: E402  (shared with the other skills' builders: bundles + File/Line/Lines ranges)

EDM = "http://docs.oasis-open.org/odata/ns/edm"
EDMX = "http://docs.oasis-open.org/odata/ns/edmx"
DESCRIPTION = "Org.OData.Core.V1.Description"
MAX_BYTES = 1_000_000  # bundle size, the repo standard (a skill must stay under 200 files)

def q(ns: str, name: str) -> str:
    return f"{{{ns}}}{name}"

def truth(value: str | None) -> bool:
    return value is not None and value.lower() == "true"

def description(el: ET.Element) -> str:
    for ann in el.findall(q(EDM, "Annotation")):
        if ann.attrib.get("Term") == DESCRIPTION and ann.attrib.get("String"):
            return ann.attrib["String"].replace('"', "'").strip()
    return ""

def filter_restrictions(es: ET.Element) -> tuple[list[str], bool]:
    """Return (NonFilterableProperties, Filterable=false) from a Cap.FilterRestrictions annotation on an entity set.

    The guide (DAC-Based OData: General Information) says every field in NonFilterableProperties is treated as
    non-filterable *and* non-selectable, and Filterable=false means no field declared in the DAC itself may be used
    in $filter or $select (inherited fields may). Both forms are kept."""
    non_filterable: list[str] = []
    not_filterable = False
    for ann in es.findall(q(EDM, "Annotation")):
        term = ann.attrib.get("Term", "")
        if not term.endswith("FilterRestrictions"):
            continue
        for pv in ann.iter(q(EDM, "PropertyValue")):
            prop = pv.attrib.get("Property")
            if prop == "NonFilterableProperties":
                non_filterable += [p.text.strip() for p in pv.iter(q(EDM, "PropertyPath")) if p.text]
            elif prop == "Filterable" and pv.attrib.get("Bool", "").lower() == "false":
                not_filterable = True
    return non_filterable, not_filterable

def parse(path: Path):
    # The committed copy under sources/acumatica-assistant/ is gzipped (20 MB raw, 1 MB compressed).
    if path.suffix == ".gz":
        import gzip
        with gzip.open(path, "rb") as f:
            root = ET.parse(f).getroot()
    else:
        root = ET.parse(path).getroot()
    if root.tag != q(EDMX, "Edmx"):
        raise SystemExit("Expected OData v4 edmx:Edmx in the OASIS namespace.")
    if root.attrib.get("Version") not in (None, "4.0"):
        raise SystemExit(f"Expected OData v4 metadata, got Edmx Version={root.attrib.get('Version')!r}.")
    schemas = root.findall(".//" + q(EDM, "Schema"))
    if not schemas:
        raise SystemExit("No OData v4 Schema elements found.")
    return schemas

def build(metadata: Path, out: Path, verified: str, label: str, source: str, excludes: list[re.Pattern[str]],
          max_bytes: int = MAX_BYTES) -> dict:
    schemas = parse(metadata)
    if out.exists() and any(out.iterdir()):
        raise SystemExit(f"Output directory is not empty: {out}. Build into an empty scratch directory.")
    excluded: set[str] = set()

    def blocked(name: str) -> bool:
        if any(rx.search(name) for rx in excludes):
            excluded.add(name)
            return True
        return False

    # ---- pass 1: containers (entity sets and singletons), so type entries can list their URL names ------------
    sets_by_type: dict[str, list[str]] = {}
    singletons_by_type: dict[str, list[str]] = {}
    restrictions_by_type: dict[str, tuple[list[str], bool]] = {}
    restriction_conflicts: list[str] = []
    for schema in schemas:
        for container in schema.findall(q(EDM, "EntityContainer")):
            for es in container.findall(q(EDM, "EntitySet")):
                t = es.attrib.get("EntityType", "")
                if blocked(t):
                    continue
                sets_by_type.setdefault(t, []).append(es.attrib["Name"])
                r = filter_restrictions(es)
                if t in restrictions_by_type and restrictions_by_type[t] != r:
                    restriction_conflicts.append(f"{t}: {es.attrib['Name']}")
                restrictions_by_type.setdefault(t, r)
            for sg in container.findall(q(EDM, "Singleton")):
                t = sg.attrib.get("Type", "")
                if blocked(t):
                    continue
                singletons_by_type.setdefault(t, []).append(sg.attrib["Name"])

    def url_names(t: str) -> list[str]:
        # The generated `PX_Namespace_Class` name first, then the display-name and class-name aliases as listed.
        names = sets_by_type.get(t, [])
        return sorted(names, key=lambda n: (not n.startswith("PX_") and "_" not in n, names.index(n)))

    # ---- pass 2a: keys per type, so a derived DAC (Customer : BAccount) can show the key it inherits ------------
    own_keys: dict[str, list[str]] = {}
    base_of: dict[str, str] = {}
    for schema in schemas:
        ns = schema.attrib.get("Namespace", "")
        for kind in ("EntityType", "ComplexType"):
            for el in schema.findall(q(EDM, kind)):
                full = f"{ns}.{el.attrib['Name']}" if ns else el.attrib["Name"]
                own_keys[full] = [x.attrib.get("Name", "") for x in el.findall(f"{q(EDM,'Key')}/{q(EDM,'PropertyRef')}")]
                if el.attrib.get("BaseType"):
                    base_of[full] = el.attrib["BaseType"]

    def resolved_keys(full: str) -> tuple[list[str], str]:
        """(key fields, type that declares them): the type's own key, else the nearest base type's."""
        seen, t = set(), full
        while t and t not in seen:
            seen.add(t)
            if own_keys.get(t):
                return own_keys[t], t
            t = base_of.get(t, "")
        return [], ""

    # ---- pass 2b: types -----------------------------------------------------------------------------------------
    type_entries: list[tuple[str, str]] = []
    type_rows: list[dict] = []
    enum_lines: list[str] = []
    n_props = n_navs = n_labelled = 0
    edm_types: dict[str, int] = {}

    for schema in schemas:
        ns = schema.attrib.get("Namespace", "")
        for kind in ("EntityType", "ComplexType"):
            for el in schema.findall(q(EDM, kind)):
                full = f"{ns}.{el.attrib['Name']}" if ns else el.attrib["Name"]
                if blocked(full):
                    continue
                keys, key_owner = resolved_keys(full)
                props = el.findall(q(EDM, "Property"))
                navs = el.findall(q(EDM, "NavigationProperty"))
                label_text = description(el)
                base = el.attrib.get("BaseType", "")
                names = url_names(full)
                non_filterable, not_filterable = restrictions_by_type.get(full, ([], False))

                lines = [f"# {full} ({kind})", ""]
                if label_text:
                    lines.append(f'Label: "{label_text}"')
                if base:
                    lines.append(f"BaseType: {base}")
                if truth(el.attrib.get("Abstract")):
                    lines.append("Abstract: true")
                if truth(el.attrib.get("OpenType")):
                    lines.append("OpenType: true")
                if keys:
                    lines.append("Key: " + ", ".join(keys) + (f" (inherited from {key_owner})" if key_owner != full else ""))
                if names:
                    lines.append("Entity sets: " + ", ".join(names))
                if singletons_by_type.get(full):
                    lines.append("Singletons: " + ", ".join(singletons_by_type[full]))
                if not_filterable:
                    lines.append("Filterable: false (fields declared in this DAC cannot be used in $filter or $select; inherited ones can)")
                if non_filterable:
                    lines.append("Non-filterable, non-selectable: " + ", ".join(non_filterable))
                lines.append("")
                for p in props:
                    name, etype = p.attrib.get("Name", ""), p.attrib.get("Type", "")
                    edm_types[etype] = edm_types.get(etype, 0) + 1
                    tags = []
                    if name in keys and key_owner == full:
                        tags.append("key")
                    if p.attrib.get("Nullable") == "false":
                        tags.append("required")
                    lab = description(p)
                    n_labelled += bool(lab)
                    lines.append(f"{full}.{name} : {etype}" + (" [" + " ".join(tags) + "]" if tags else "") + (f' "{lab}"' if lab else ""))
                n_props += len(props)
                for nv in navs:
                    name, target = nv.attrib.get("Name", ""), nv.attrib.get("Type", "")
                    rc = [(c.attrib.get("Property", ""), c.attrib.get("ReferencedProperty", "")) for c in nv.findall(q(EDM, "ReferentialConstraint"))]
                    via = " (" + ", ".join(f"{a}={b}" for a, b in rc) + ")" if rc else ""
                    lines.append(f"{full}.{name} -> {target}{via}")
                n_navs += len(navs)
                type_entries.append((full, "\n".join(lines).rstrip() + "\n"))
                type_rows.append(dict(name=full, kind=kind, label=label_text, keys=", ".join(keys), props=len(props),
                                      navs=len(navs), base=base, sets=names, singletons=singletons_by_type.get(full, []),
                                      non_filterable=non_filterable, not_filterable=not_filterable))

        for el in schema.findall(q(EDM, "EnumType")):
            full = f"{ns}.{el.attrib['Name']}" if ns else el.attrib["Name"]
            if blocked(full):
                continue
            for m in el.findall(q(EDM, "Member")):
                enum_lines.append(f"{full}.{m.attrib.get('Name','')} = {m.attrib.get('Value','')}")

    type_entries.sort(key=lambda x: x[0].lower())
    type_rows.sort(key=lambda r: r["name"].lower())
    enum_lines.sort(key=str.lower)

    # ---- write ------------------------------------------------------------------------------------------------------
    out.mkdir(parents=True, exist_ok=True)
    provenance = f"<!-- source: {source} | version: {label} | verified: {verified} -->"
    locs = bundle_util.write_bundles([("members", type_entries)], str(out / "api"), provenance, max_bytes, numbered_prefix="members")

    lines = [provenance, "", "# DAC-based OData metadata: type index", "",
             "One row per EntityType / ComplexType. Open the entry with the `File`, `Line` and `Lines` columns "
             "(a line-range read of `api/<File>`), or grep `api/members-*.md` for `^<Type>\\.`. A type with a BaseType "
             "lists only the fields it adds; its key and the rest of its fields are those of the base type (the entry "
             "says which type declares the key).", "",
             "| Type | Kind | Label | Key | Fields | Navigation | BaseType | Entity sets | File | Line | Lines |",
             "|---|---|---|---|---:|---:|---|---|---|---:|---:|"]
    for r in type_rows:
        f, ln, n = locs[r["name"]]
        lines.append(f"| {r['name']} | {r['kind']} | {r['label']} | {r['keys']} | {r['props']} | {r['navs']} | {r['base']} | {', '.join(r['sets'])} | {f} | {ln} | {n} |")
    (out / "api" / "INDEX.md").write_text("\n".join(lines) + "\n", encoding="utf-8", newline="\n")

    lines = [provenance, "", "# DAC-based OData entity sets", "",
             "One row per DAC that the container exposes. **Entity sets** are the names accepted after `/api/odata/dac/` "
             "(the generated `PX_Namespace_Class` name, the display-name alias and the class-name alias; a digit suffix "
             "means the alias collided with another DAC). **Non-filterable** fields are the `Cap.FilterRestrictions` "
             "`NonFilterableProperties` of the entity set, which the DAC-based OData interface refuses in both `$filter` "
             "and `$select`; **Filterable=false** means no field declared in the DAC itself may be used in `$filter` or "
             "`$select`.", "",
             "| DAC | Label | Entity sets | Key | Non-filterable fields | Filterable=false |", "|---|---|---|---|---|---|"]
    n_sets = 0
    for r in type_rows:
        if not r["sets"]:
            continue
        n_sets += len(r["sets"])
        lines.append(f"| {r['name']} | {r['label']} | {', '.join(r['sets'])} | {r['keys']} | {', '.join(r['non_filterable'])} | {'yes' if r['not_filterable'] else ''} |")
    singles = [(r["name"], r["singletons"], r["label"]) for r in type_rows if r["singletons"]]
    if singles:
        lines += ["", "## Singletons", "", "Setup-style DACs exposed as a single record (`GET .../api/odata/dac/<Name>` returns one object, not a `value` array).", "",
                  "| DAC | Label | Singleton names |", "|---|---|---|"]
        lines += [f"| {t} | {lab} | {', '.join(names)} |" for t, names, lab in singles]
    (out / "entity-sets.md").write_text("\n".join(lines) + "\n", encoding="utf-8", newline="\n")

    (out / "enums.md").write_text(provenance + "\n\n# DAC-based OData enum members\n\n" + ("\n".join(enum_lines) + "\n" if enum_lines else "(none)\n"), encoding="utf-8", newline="\n")

    counts = {
        "schemas": len(schemas),
        "entity_types": sum(r["kind"] == "EntityType" for r in type_rows),
        "complex_types": sum(r["kind"] == "ComplexType" for r in type_rows),
        "fields": n_props, "fields_with_display_name": n_labelled, "navigation_properties": n_navs,
        "entity_sets": n_sets, "dacs_with_entity_sets": sum(bool(r["sets"]) for r in type_rows),
        "singletons": sum(len(v) for v in singletons_by_type.values()),
        "dacs_with_non_filterable_fields": sum(bool(r["non_filterable"]) for r in type_rows),
        "dacs_filterable_false": sum(r["not_filterable"] for r in type_rows),
        "enum_members": len(enum_lines), "excluded_types": len(excluded),
        "member_bundles": len({v[0] for v in locs.values()}),
    }
    namespaces = sorted({s.attrib.get("Namespace", "") for s in schemas if s.attrib.get("Namespace")})
    lines = [provenance, "", "# DAC-based OData metadata snapshot", "",
             f"Compiled from `GET <instance URL>/t/<TenantName>/api/odata/dac/$metadata` of a clean **{label}** instance by "
             "`scripts/build_odata_metadata_ref.py`. It is the OData v4 CSDL of the DAC-based interface, not a tenant's "
             "generic-inquiry (`/api/odata/gi`) metadata and not the contract-based REST API's `swagger.json`.", "",
             "| Path | Covers |", "|---|---|",
             "| `entity-sets.md` | One row per DAC: the entity-set names accepted in the URL, key fields, non-filterable fields, `Filterable=false`; plus singletons |",
             "| `api/INDEX.md` | One row per EntityType / ComplexType: label, key, counts, base type, entity sets, and the bundle file + line range of its entry |",
             "| `api/members-NN.md` | The entries: a heading per type, then `Type.Field : Edm.Type [key] [required] \"Display name\"` and `Type.Nav -> Target (LocalField=TargetField)` lines |",
             "| `enums.md` | `Enum.Member = Value` lines |", "",
             "## How to read it", "",
             "- **Which DAC / which URL name?** grep `entity-sets.md` for the class name, the display name (`| Sales Order |`) or the URL alias.",
             "- **Fields of a DAC**: grep `api/members-*.md` for `^PX\\.Objects\\.SO\\.SOOrder\\.` (one line per field and navigation property), or take `File` / `Line` / `Lines` from `api/INDEX.md` and read that range. A DAC with a `BaseType` (for example `PX.Objects.AR.Customer : PX.Objects.CR.BAccount`) lists only the fields it adds; read the base type's entry for the rest, including the key.",
             "- **Which DACs have a field named X?** grep `api/members-*.md` for `\\.X : `.",
             "- **Joins**: a navigation line `A.BAccountByCustomerID -> PX.Objects.CR.BAccount (CustomerID=BAccountID)` means `$expand=BAccountByCustomerID` and that `A.CustomerID` equals `BAccount.BAccountID`; `A.SOLineCollection -> Collection(PX.Objects.SO.SOLine)` is a detail collection.",
             "- Field lines carry the field's UI display name in quotes when the metadata has one (the `Org.OData.Core.V1.Description` annotation), which is how a user's wording (\"Customer Order Nbr.\") maps to a field (`CustomerOrderNbr`).", "",
             "## Counts", ""]
    lines += [f"- {k}: {v}" for k, v in counts.items()]
    lines += ["", "## Edm types used", "", ", ".join(f"`{t}` ({n})" for t, n in sorted(edm_types.items(), key=lambda x: -x[1])), "",
              "## Scope and limits", "",
              "- One clean instance, one release. A customer's instance adds customization and user-defined fields, extension DACs and "
              "custom namespaces, and may lack modules (Manufacturing, Payroll, Field Service, Construction ...) whose DACs are listed here. "
              "Absence here is not proof of absence there, and presence here is not proof of presence there: confirm on the "
              "client's `/api/odata/dac/$metadata`.",
              "- The DAC-based interface exposes DACs, not forms. A DAC's fields are the database-backed and unbound fields the "
              "server publishes; the metadata does not say which fields are populated for a given record type.",
              "- Navigation property names are generated (`<Target>By<LocalField>` for lookups, `<Detail>Collection` for details); "
              "the referential constraint in parentheses is the join the server uses.",
              "- `Edm.Decimal` fields are declared with `Scale=\"Variable\"`; `Edm.Binary` is used for `tstamp`; no `MaxLength` "
              "or `Precision` facets are published.",
              "- The `px.GetDeletedRecords()` function documented for removed-record tracking is not declared in this metadata; "
              "its result shape is the `PX.Api.OData.DAC.DeletedRecordResult` complex type (`RefNoteID`, `DeleteDate`).",
              "- Namespaces: " + ", ".join(namespaces) + "."]
    if restriction_conflicts:
        lines += ["", "## Restriction conflicts", "",
                  "Entity sets of the same DAC with different `Cap.FilterRestrictions` (the first one seen was kept):", ""]
        lines += [f"- {c}" for c in restriction_conflicts]
    if excludes:
        lines += ["", "## Exclusion filters", ""] + [f"- type name: `{rx.pattern}`" for rx in excludes]
    (out / "INDEX.md").write_text("\n".join(lines) + "\n", encoding="utf-8", newline="\n")
    return counts

def main() -> None:
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("metadata", type=Path)
    ap.add_argument("out", type=Path)
    ap.add_argument("--verified", required=True, help="YYYY-MM-DD")
    ap.add_argument("--label", required=True, help='e.g. "Acumatica ERP 2026 R2"')
    ap.add_argument("--source", default="DAC-based OData $metadata of a clean Acumatica ERP instance (GET <instance URL>/t/<TenantName>/api/odata/dac/$metadata)",
                    help="provenance text; never include an instance URL with credentials")
    ap.add_argument("--exclude-regex", action="append", default=[], help="repeatable regex matched against fully qualified type names")
    ap.add_argument("--max-bytes", type=int, default=MAX_BYTES, help="bundle size before a bundle file is split")
    args = ap.parse_args()
    counts = build(args.metadata, args.out, args.verified, args.label, args.source,
                   [re.compile(p) for p in args.exclude_regex], args.max_bytes)
    for k, v in counts.items():
        print(f"{k}: {v}")

if __name__ == "__main__":
    main()
```

## File: skills/acumatica-assistant/scripts/bundle_util.py
size: 2393
sha: 10152d7c6c5cc6e335673e1fab77588a35c04023
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/scripts/bundle_util.py

```text
"""Shared by the build scripts: write many small entries (tables, classes, enumerations) into a few bundle files.

The skill must stay under 200 files, so each build script groups its entries into bundles of about `max_bytes` and
records where each entry landed (file, 1-based start line, line count). The index files carry those three values so
a reader can open exactly one entry with a line-range read, or grep for its heading.
"""
import os
import re

def slug(label):
    return re.sub(r"[^A-Za-z0-9]+", "-", label).strip("-")

def _chunk(entries, max_bytes):
    chunks, cur, size = [], [], 0
    for e in entries:
        b = len(e[1].encode("utf-8")) + 2
        if cur and size + b > max_bytes:
            chunks.append(cur)
            cur, size = [], 0
        cur.append(e)
        size += b
    if cur:
        chunks.append(cur)
    return chunks

def write_bundles(groups, out_dir, header, max_bytes, numbered_prefix=None):
    """groups: ordered list of (label, [(name, text), ...]).  text is the entry's markdown, starting with its heading.

    Files are named from the group label (`Marketing-Documents.md`, `Marketing-Documents-2.md` when a group is split) or,
    with numbered_prefix, `<prefix>-01.md`, `<prefix>-02.md` ... over all groups in order.
    Returns {name: (file name, start line, line count)}.
    """
    os.makedirs(out_dir, exist_ok=True)
    plan = []  # (file name, entries)
    if numbered_prefix:
        entries = [e for _, es in groups for e in es]
        for n, ch in enumerate(_chunk(entries, max_bytes), 1):
            plan.append((f"{numbered_prefix}-{n:02d}.md", ch))
    else:
        for label, es in groups:
            chunks = _chunk(es, max_bytes)
            for n, ch in enumerate(chunks, 1):
                plan.append((f"{slug(label)}{'' if len(chunks) == 1 else '-' + str(n)}.md", ch))
    where = {}
    for fname, ch in plan:
        head = header.rstrip("\n") + "\n\n"
        line = head.count("\n") + 1
        parts = [head]
        for name, text in ch:
            text = text.rstrip("\n")
            n_lines = text.count("\n") + 1
            where[name] = (fname, line, n_lines)
            parts.append(text + "\n\n")
            line += n_lines + 1
        with open(os.path.join(out_dir, fname), "w", encoding="utf-8", newline="\n") as f:
            f.write("".join(parts).rstrip("\n") + "\n")
    return where
```

## File: skills/acumatica-assistant/scripts/fetch_beacon_guide.py
size: 7762
sha: 6e56419341ed8dd4b98c8927338cc3b889e868a9
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/scripts/fetch_beacon_guide.py

````text
#!/usr/bin/env python3
"""Fetch an Acumatica Beacon guide (beacon.acumatica.com, a Fluid Topics portal) into a local cache (maintenance only).

    python scripts/fetch_beacon_guide.py --map UpQu337K_38feMdsBg0ruQ --cache <dir outside the repo> [--delay 0.3] [--filter REGEX]

The reader URLs (`/r/<Guide>/<Topic>`) are a JavaScript shell to curl, but the portal's public knowledge-hub API
returns each topic's HTML:

    GET /api/khub/maps/<mapId>                       map metadata (title, version, lastEdition)
    GET /api/khub/maps/<mapId>/toc                   nested table of contents (tocId, contentId, prettyUrl, title)
    GET /api/khub/maps/<mapId>/topics/<contentId>/content   the topic body as HTML

The map id is the first path segment of any `ft-internal-link` inside a topic (e.g. `/r/UpQu337K_38feMdsBg0ruQ/...`).
`UpQu337K_38feMdsBg0ruQ` is the Integration Development Guide at the time of writing; re-check it after a new
release is published, since a new edition may get a new map id.

For every topic the script writes `<cache>/<NNN>-<slug>.html` (raw) and `<cache>/<NNN>-<slug>.md` (a plain-text
rendering: headings, paragraphs, notes, fenced code blocks, pipe tables, list items), plus `<cache>/toc.json`
and `<cache>/map.json`. Re-running skips topics already cached. The cache is Acumatica's documentation and is
**not** to be committed: curate facts from it into `references/` and cite the topic titles and URLs.
"""
import argparse
import html
import json
import os
import re
import sys
import time
import urllib.request

BASE = "https://beacon.acumatica.com"
UA = "Mozilla/5.0 (compatible; claude-skills maintenance fetch; +https://github.com/fdtaljaard/claude-skills)"

def get(url):
    req = urllib.request.Request(url, headers={"User-Agent": UA, "Accept": "application/json, text/html"})
    with urllib.request.urlopen(req, timeout=60) as r:
        return r.read().decode("utf-8")

def flatten(nodes, depth=0, out=None):
    out = [] if out is None else out
    for n in nodes:
        out.append({"tocId": n["tocId"], "contentId": n["contentId"], "prettyUrl": n["prettyUrl"],
                    "title": n["title"], "depth": depth})
        flatten(n.get("children", []), depth + 1, out)
    return out

# --- minimal HTML -> text ---------------------------------------------------------------------------------------

BLOCK_RE = re.compile(r"<(pre|table|h[1-6]|p|li|div|ul|ol|tr|td|th|section|br)\b[^>]*>|</(pre|table|h[1-6]|p|li|div|ul|ol|tr|td|th|section)>", re.I)

def strip_tags(s):
    """Remove tags only; entities (e.g. the &lt;placeholder&gt; in code samples) are unescaped once, at the end."""
    return re.sub(r"<[^>]+>", "", s)

def collapse(s):
    return re.sub(r"[ \t\r\f\v]+", " ", s).strip()

def render(doc):
    """Render the topic HTML to readable text. Good enough for curation, not a general converter."""
    out = []
    # code blocks first (keep whitespace)
    def code_repl(m):
        code = strip_tags(m.group(1))
        return "\n```\n" + code.strip("\n") + "\n```\n"
    doc = re.sub(r"<pre[^>]*>(.*?)</pre>", code_repl, doc, flags=re.S | re.I)
    # tables -> pipe rows
    def table_repl(m):
        rows = []
        for tr in re.findall(r"<tr[^>]*>(.*?)</tr>", m.group(1), flags=re.S | re.I):
            cells = re.findall(r"<t[hd][^>]*>(.*?)</t[hd]>", tr, flags=re.S | re.I)
            rows.append("| " + " | ".join(collapse(strip_tags(c)) for c in cells) + " |")
        return "\n" + "\n".join(rows) + "\n"
    doc = re.sub(r"<table[^>]*>(.*?)</table>", table_repl, doc, flags=re.S | re.I)
    # headings
    def h_repl(m):
        level = int(m.group(1))
        return "\n" + "#" * min(level + 1, 6) + " " + collapse(strip_tags(m.group(2))) + "\n"
    doc = re.sub(r"<h([1-6])[^>]*>(.*?)</h\1>", h_repl, doc, flags=re.S | re.I)
    # notes
    doc = re.sub(r'<span class="(?:note|attention|important|tip|caution|warning)title">(.*?)</span>', r"**\1**", doc, flags=re.S | re.I)
    # list items and paragraphs
    doc = re.sub(r"<li[^>]*>", "\n- ", doc, flags=re.I)
    doc = re.sub(r"</(p|li|div|ul|ol|section)>", "\n", doc, flags=re.I)
    doc = re.sub(r"<(p|div|ul|ol|section)[^>]*>", "\n", doc, flags=re.I)
    doc = re.sub(r"<br\s*/?>", "\n", doc, flags=re.I)
    # inline code
    doc = re.sub(r"<code[^>]*>(.*?)</code>", r"`\1`", doc, flags=re.S | re.I)
    text = html.unescape(strip_tags(doc))
    # tidy: collapse spaces per line outside fenced code, max two blank lines
    lines, fenced, out = text.split("\n"), False, []
    for ln in lines:
        if ln.strip().startswith("```"):
            fenced = not fenced
            out.append(ln.strip())
            continue
        out.append(ln if fenced else collapse(ln))
    text = "\n".join(out)
    text = re.sub(r"\n{3,}", "\n\n", text)
    return text.strip() + "\n"

def slug(pretty):
    """Topic path without the guide segment, kept short for Windows path limits."""
    path = pretty.split("/r/", 1)[-1].split("/", 1)[-1]
    return re.sub(r"[^A-Za-z0-9.-]+", "-", path.replace("/", "__"))[:90]

def main():
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--map", required=True, help="Fluid Topics map id, e.g. UpQu337K_38feMdsBg0ruQ")
    ap.add_argument("--cache", required=True, help="output folder (outside the repo)")
    ap.add_argument("--delay", type=float, default=0.3, help="seconds between requests")
    ap.add_argument("--filter", default=None, help="regex on the pretty URL; fetch only matching topics")
    ap.add_argument("--rerender", action="store_true", help="rewrite the .md files from cached .html without fetching")
    a = ap.parse_args()
    os.makedirs(a.cache, exist_ok=True)

    meta = json.loads(get(f"{BASE}/api/khub/maps/{a.map}"))
    json.dump(meta, open(os.path.join(a.cache, "map.json"), "w", encoding="utf-8"), indent=1)
    version = next((m["values"][0] for m in meta.get("metadata", []) if m["key"] == "version"), "?")
    print(f"{meta['title']} | version {version} | lastEdition {meta.get('lastEdition')} | words {next((m['values'][0] for m in meta.get('metadata', []) if m['key']=='ft:wordCount'), '?')}")

    toc = json.loads(get(f"{BASE}/api/khub/maps/{a.map}/toc"))
    flat = flatten(toc)
    json.dump(flat, open(os.path.join(a.cache, "toc.json"), "w", encoding="utf-8"), indent=1)
    print(f"{len(flat)} topics in the table of contents")

    pat = re.compile(a.filter) if a.filter else None
    fetched = skipped = failed = 0
    for i, t in enumerate(flat, 1):
        if pat and not pat.search(t["prettyUrl"]):
            continue
        base = os.path.join(a.cache, f"{i:03d}-{slug(t['prettyUrl'])}")
        if a.rerender and os.path.exists(base + ".html"):
            body = open(base + ".html", encoding="utf-8").read()
        elif os.path.exists(base + ".md"):
            skipped += 1
            continue
        else:
            url = f"{BASE}/api/khub/maps/{a.map}/topics/{t['contentId']}/content"
            try:
                body = get(url)
            except Exception as e:  # noqa: BLE001
                failed += 1
                print(f"FAILED {t['prettyUrl']}: {e}", file=sys.stderr)
                continue
            with open(base + ".html", "w", encoding="utf-8") as f:
                f.write(body)
            time.sleep(a.delay)
        header = f"<!-- {t['title']} | {BASE}{t['prettyUrl']} | version {version} | lastEdition {meta.get('lastEdition')} -->\n# {t['title']}\n\n"
        with open(base + ".md", "w", encoding="utf-8") as f:
            f.write(header + render(body))
        fetched += 1
    print(f"fetched {fetched}, skipped (cached) {skipped}, failed {failed} -> {a.cache}")

if __name__ == "__main__":
    main()
````

## File: skills/acumatica-assistant/scripts/package_skill.py
size: 3031
sha: e8fba4f14428ac89e3530dac95742e74dd6494ee
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/scripts/package_skill.py

```text
#!/usr/bin/env python3
"""Package the skill folder as a .skill (zip) for upload to Claude (maintenance only).

    python scripts/package_skill.py <skill folder> <output folder>

Checks before writing anything, because an upload fails on any of them:
  * SKILL.md has YAML frontmatter with `name` equal to the folder name, `description` <= 1024 characters and
    `compatibility` <= 500 characters;
  * the archive has at most 200 files (Claude's upload limit; the skill's large references are bundled to stay under it);
  * no file is a Python cache, a script unit test (`scripts/test_*.py`) or an OS artefact.
Writes <output>/<name>.skill and a byte-identical <name>.zip, with every file under a single top-level <name>/ folder.
"""
import os
import sys
import zipfile

MAX_FILES = 200

def main():
    if len(sys.argv) != 3:
        sys.exit(__doc__)
    src, out_dir = os.path.abspath(sys.argv[1]), sys.argv[2]
    name = os.path.basename(src.rstrip("/\\"))
    text = open(os.path.join(src, "SKILL.md"), encoding="utf-8").read()
    parts = text.split("---")
    if not text.startswith("---") or len(parts) < 3:
        sys.exit("SKILL.md has no frontmatter")
    try:
        import yaml
        fm = yaml.safe_load(parts[1])
    except ImportError:
        sys.exit("needs PyYAML (pip install pyyaml) to read the frontmatter")
    problems = []
    if fm.get("name") != name:
        problems.append(f"name {fm.get('name')!r} must equal the folder name {name!r}")
    if len(fm.get("description", "")) > 1024:
        problems.append(f"description is {len(fm['description'])} characters (max 1024)")
    if len(fm.get("compatibility", "")) > 500:
        problems.append(f"compatibility is {len(fm['compatibility'])} characters (max 500)")
    files = []
    for root, dirs, names in os.walk(src):
        dirs[:] = [d for d in dirs if d != "__pycache__"]
        for n in sorted(names):
            if n.endswith((".pyc", ".DS_Store")) or n == "Thumbs.db" or (n.startswith("test_") and n.endswith(".py")):
                continue
            files.append(os.path.join(root, n))
    if len(files) > MAX_FILES:
        problems.append(f"{len(files)} files (max {MAX_FILES}); bundle more of the references")
    if problems:
        sys.exit("not packaged:\n  " + "\n  ".join(problems))
    os.makedirs(out_dir, exist_ok=True)
    out = os.path.join(out_dir, name + ".skill")
    if os.path.exists(out):
        os.remove(out)
    with zipfile.ZipFile(out, "w", zipfile.ZIP_DEFLATED, compresslevel=9) as z:
        for p in files:
            z.write(p, name + "/" + os.path.relpath(p, src).replace(os.sep, "/"))
    with zipfile.ZipFile(out) as z:
        assert z.testzip() is None
        assert f"{name}/SKILL.md" in z.namelist()
    zip_copy = os.path.join(out_dir, name + ".zip")
    with open(out, "rb") as a, open(zip_copy, "wb") as b:
        b.write(a.read())
    print(f"{len(files)} files, {os.path.getsize(out) / 1e6:.1f} MB -> {out} (and {os.path.basename(zip_copy)})")

if __name__ == "__main__":
    main()
```

## File: skills/acumatica-assistant/references/endpoints/Default-25.200.001/actions.md
size: 9305
sha: 3e26510728b13ab42d3c0a3b70509233bd1b6bd3
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/endpoints/Default-25.200.001/actions.md

````text
<!-- source: swagger.json (OpenAPI 3.0.1) of the Default/25.200.001 system endpoint (a sandbox instance; instance name withheld, raw file not in the repository) | version: Acumatica ERP 2025 R2, build 25.201.0213, Contract Version 4 | verified: 2026-10-05 | generated by scripts/build_endpoint_reference.py -->

# Default/25.200.001: actions

One line per action in the contract: `Entity.Action(Parameter: Type, ...)`. Invoke with
`POST /entity/Default/25.200.001/<Entity>/<Action>` and the body `{"entity": {...}, "parameters": {...}}`; the
entity part identifies the record (its fields are in `fields.md`). Grep `^Shipment\.` for an entity's actions.
Workflow actions outside the contract are discovered with `<Entity>/$adHocSchema`.

```text
Activity.CompleteActivity()
Appointment.AppRecalcExternalTax()
Appointment.CancelAppointment()
Appointment.CloseAppointment()
Appointment.CompleteAppointment()
Appointment.InvoiceAppointment()
Appointment.PauseAppointment()
Appointment.ReopenAppointment()
Appointment.ResumeAppointment()
Appointment.StartAppointment()
Appointment.UncloseAppointment()
Bill.ReleaseBill()
Bill.ReleaseRetainage(AmtToRelease: DecimalValue, Date: DateTimeValue, PostPeriod: StringValue)
Bill.ReverseBill()
BusinessAccount.ChangeBusinessAccountID(BusinessAccountID: StringValue)
BusinessAccount.CheckForBusinessAccountDuplicates()
BusinessAccount.ConvertBusinessAccountToCustomer()
BusinessAccount.CreateContactFromBusinessAccount(FirstName: StringValue, LastName: StringValue, JobTitle: StringValue, Phone1Type: StringValue, Phone1: StringValue, Phone2Type: StringValue, Phone2: StringValue, Email: StringValue, ContactClass: StringValue)
BusinessAccount.MarkBusinessAccountAsValidated()
BusinessAccount.ValidateBusinessAccountAddresses()
Case.AssignCase()
Case.ReleaseCase()
CashSale.ReleaseCashSale()
CashTransaction.ReleaseCashTransaction()
ChangeOrder.ApproveChangeOrder()
ChangeOrder.EmailChangeOrder()
ChangeOrder.HoldChangeOrder()
ChangeOrder.RejectChangeOrder()
ChangeOrder.ReleaseChangeOrder()
ChangeOrder.RemoveChangeOrderFromHold()
ChangeOrder.ReverseChangeOrder()
Check.ReleaseCheck()
Check.VoidCheck()
Contact.CheckForContactDuplicates()
Contact.CreateAccountFromContact(BusinessAccountID: StringValue, BusinessAccountName: StringValue, BusinessAccountClass: StringValue)
Contact.MarkContactAsValidated()
Contact.ValidateContactAddress()
CostCode.ChangeCostCodeID(CostCodeID: StringValue)
Customer.CreateContactFromCustomer(FirstName: StringValue, LastName: StringValue, JobTitle: StringValue, Phone1Type: StringValue, Phone1: StringValue, Phone2Type: StringValue, Phone2: StringValue, Email: StringValue, ContactClass: StringValue)
Discount.UpdateDiscounts(Date: DateTimeValue)
Email.ArchiveEmail()
Email.CancelSendingEmail()
Email.CreateCaseFromEmail()
Email.CreateContactFromEmail()
Email.CreateEventFromEmail()
Email.CreateExpenseReceiptFromEmail()
Email.CreateLeadFromEmail()
Email.CreateOpportunityFromEmail()
Email.CreateTaskFromEmail()
Email.ProcessEmail()
Email.RestoreArchivedEmail()
Email.RestoreDeletedEmail()
Email.SendEmail()
EmailProcessing.ProcessAllEmailProcessing()
EmailProcessing.ProcessEmailProcessing()
Employee.ChangeEmployeeID(EmployeeID: StringValue)
EmployeePayrollSettings.ImportEmployeeTaxes()
Event.AcceptInvitationEvent()
Event.CancelActivityEvent()
Event.CompleteEvent()
Event.ExportCardEvent()
Event.InviteAllEvent()
Event.InviteEvent()
Event.RejectInvitationEvent()
ExpenseClaim.ApproveExpenseClaim()
ExpenseClaim.PutOnHoldExpenseClaim()
ExpenseClaim.RejectExpenseClaim()
ExpenseClaim.ReleaseExpenseClaim()
ExpenseClaim.SubmitExpenseClaim()
ExpenseReceipt.ApproveExpenseReceipt()
ExpenseReceipt.ClaimExpenseReceipt()
ExpenseReceipt.PutOnHoldExpenseReceipt()
ExpenseReceipt.RejectExpenseReceipt()
ExpenseReceipt.SubmitExpenseReceipt()
InventoryAdjustment.ReleaseAdjustment()
InventoryIssue.ReleaseInventoryIssue()
InventoryReceipt.ReleaseInventoryReceipt()
Invoice.ReleaseInvoice()
JournalTransaction.ReleaseJournalTransaction()
KitAssembly.ReleaseKitAssembly()
Lead.CheckLeadForDuplicates()
Lead.ConvertLeadToBAccount(FirstName: StringValue, LastName: StringValue, JobTitle: StringValue, Phone1Type: StringValue, Phone1: StringValue, Phone2Type: StringValue, Phone2: StringValue, Email: StringValue, ContactClass: StringValue, BusinessAccountID: StringValue, BusinessAccountName: StringValue, BusinessAccountClass: StringValue)
Lead.ConvertLeadToContact(FirstName: StringValue, LastName: StringValue, AccountName: StringValue, JobTitle: StringValue, Phone1Type: StringValue, Phone1: StringValue, Phone2Type: StringValue, Phone2: StringValue, Email: StringValue, ContactClass: StringValue)
Lead.ConvertLeadToOpportunity(FirstName: StringValue, LastName: StringValue, AccountName: StringValue, JobTitle: StringValue, Phone1Type: StringValue, Phone1: StringValue, Phone2Type: StringValue, Phone2: StringValue, Email: StringValue, ContactClass: StringValue, BusinessAccountID: StringValue, BusinessAccountName: StringValue, BusinessAccountClass: StringValue, OpportunitySubject: StringValue, OpportunityCloseDate: StringValue, OpportunityClass: StringValue)
Lead.MarkLeadAsValidated()
Lead.ValidateLeadAddress()
NonStockItem.UpdateStandardCostNonStockItem()
Opportunity.CreateAccountFromOpportunity(FirstName: StringValue, LastName: StringValue, AccountName: StringValue, JobTitle: StringValue, Phone1Type: StringValue, Phone1: StringValue, Phone2Type: StringValue, Phone2: StringValue, Email: StringValue, ContactClass: StringValue, LinkContactToAccount: BooleanValue, BusinessAccountID: StringValue, BusinessAccountName: StringValue, BusinessAccountClass: StringValue)
Opportunity.CreateContactFromOpportunity(FirstName: StringValue, LastName: StringValue, AccountName: StringValue, JobTitle: StringValue, Phone1Type: StringValue, Phone1: StringValue, Phone2Type: StringValue, Phone2: StringValue, Email: StringValue, ContactClass: StringValue)
Opportunity.CreateOpportunityInvoice()
Opportunity.CreateOpportunitySalesOrder(OrderType: StringValue, RecalculatePricesandDiscounts: BooleanValue)
Payment.CaptureCreditCardPayment()
Payment.CardOperation(TranType: StringValue, TranNbr: StringValue, TranApiNbr: StringValue, AuthNumber: StringValue, ExtProfileId: StringValue, TranDate: DateTimeValue, OrigTranNbr: StringValue, Amount: DecimalValue)
Payment.ReleasePayment()
Payment.VoidCardPayment(TranType: StringValue, TranNbr: StringValue, TranApiNbr: StringValue, ExtProfileId: StringValue, TranDate: DateTimeValue, NeedValidation: BooleanValue, OrigTranNbr: StringValue)
Payment.VoidPayment()
PayrollBatch.ReleaseBatch()
PhysicalInventoryReview.CancelPhysicalInventory()
PhysicalInventoryReview.CompletePhysicalInventory()
PhysicalInventoryReview.FinishCountingPhysicalInventory()
ProFormaInvoice.ApproveProFormaInvoice()
ProFormaInvoice.EmailProFormaInvoice()
ProFormaInvoice.HoldProFormaInvoice()
ProFormaInvoice.RejectProFormaInvoice()
ProFormaInvoice.ReleaseProFormaInvoice()
ProFormaInvoice.RemoveProFormaInvoiceFromHold()
Project.ActivateProject()
Project.ApproveProject()
Project.CancelProject()
Project.ChangeProjectID(ProjectID: StringValue)
Project.CompleteProject()
Project.HoldProject()
Project.LockProjectBudget()
Project.LockProjectCommitments()
Project.RejectProject()
Project.RunProjectAllocation()
Project.RunProjectBilling()
Project.SuspendProject()
Project.UnlockProjectBudget()
Project.UnlockProjectCommitments()
Project.ValidateProjectBalance()
ProjectTask.ActivateProjectTask()
ProjectTask.CancelProjectTask()
ProjectTask.CompleteProjectTask()
ProjectTask.HoldProjectTask()
ProjectTemplate.ActivateProjectTemplate()
ProjectTemplate.HoldProjectTemplate()
ProjectTransaction.ReleaseTransactions()
PurchaseReceipt.CreateAPBill()
PurchaseReceipt.ReleasePurchaseReceipt()
SalesInvoice.ReleaseSalesInvoice()
SalesOrder.AutoRecalculateDiscounts()
SalesOrder.CancelSalesOrder()
SalesOrder.OpenSalesOrder()
SalesOrder.PrepareSalesInvoice()
SalesOrder.RecalculatePricesDiscounts(OverrideManualDiscounts: BooleanValue, OverrideManualDocGroupDiscounts: BooleanValue, OverrideManualPrices: BooleanValue, RecalcDiscounts: BooleanValue, RecalcUnitPrices: BooleanValue)
SalesOrder.ReleaseFromCreditHoldSalesOrder()
SalesOrder.ReopenSalesOrder()
SalesOrder.SalesOrderCreateReceipt(ShipmentDate: DateTimeValue, WarehouseID: StringValue)
SalesOrder.SalesOrderCreateShipment(ShipmentDate: DateTimeValue, WarehouseID: StringValue)
SalesPriceWorksheet.ReleaseSalesPriceWorksheet()
ServiceOrder.AllowBilling()
ServiceOrder.CancelOrder()
ServiceOrder.CloseOrder()
ServiceOrder.CompleteOrder()
ServiceOrder.InvoiceOrder()
ServiceOrder.RecalcExternalTax()
ServiceOrder.ReopenOrder()
ServiceOrder.UncloseOrder()
Shipment.ConfirmShipment()
Shipment.CorrectShipment()
Shipment.PrepareInvoice()
Shipment.UpdateIN()
StockItem.UpdateStandardCostStockItem()
Subcontract.PutOnHold()
Subcontract.ReleaseFromHold()
Task.CancelActivityTask()
Task.CompleteTask()
TimeEntry.CompleteTimeEntry()
TimeEntry.OpenTimeEntry()
TransferOrder.ReleaseTransferOrder()
Vendor.CreateContactFromVendor(FirstName: StringValue, LastName: StringValue, JobTitle: StringValue, Phone1Type: StringValue, Phone1: StringValue, Phone2Type: StringValue, Phone2: StringValue, Email: StringValue, ContactClass: StringValue)
VendorPriceWorksheet.ReleaseVendorPriceWorksheet()
```
````

## File: skills/acumatica-assistant/references/endpoints/Default-25.200.001/entities.md
size: 8340
sha: 677cb219562d6a98210acc55c776bfc243fdf271
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/endpoints/Default-25.200.001/entities.md

```text
<!-- source: swagger.json (OpenAPI 3.0.1) of the Default/25.200.001 system endpoint (a sandbox instance; instance name withheld, raw file not in the repository) | version: Acumatica ERP 2025 R2, build 25.201.0213, Contract Version 4 | verified: 2026-10-05 | generated by scripts/build_endpoint_reference.py -->

# Default/25.200.001: top-level entities

The 119 entities that `Default/25.200.001` exposes at `/entity/Default/25.200.001/<Entity>`, with the form each is
mapped to. `Fields` counts the value fields, `Nested` the linked and detail entities (each needs `$expand`),
`Actions` the actions the contract names. Details: `fields.md`, `expand-paths.md`, `actions.md` in this folder.

Counts: 119 top-level entities, 309 nested entity schemas, 5338 fields (4938 value fields, 400 linked/detail), 575 expand paths, 163 actions on 50 entities (21 with parameters).

Every entity also carries the system members `id`, `rowNumber`, `note`, `custom`, `error`, `files`, `_links` and
`_workflowActions` (the form's workflow actions outside the contract, listed by `$adHocSchema`,
`../../rest/rest-api-guide.md` § 2); they are not repeated per entity. Every top-level entity accepts the same
requests (list, by keys, by ID, PUT,
PATCH, DELETE, `files`, `$adHocSchema`) and `POST <Entity>/<action name>` for workflow actions that are not in
the contract. The swagger does not name the key fields (`ids` is one slash-delimited path value): they are the
form's keys, in the order the form defines them (`../../rest/rest-api-guide.md` § 5).

| Entity | Form | Screen title | Fields | Nested | Actions |
|---|---|---|---:|---:|---:|
| Account | GL202500 | Chart of Accounts | 19 | 0 | 0 |
| AccountDetailsForPeriodInquiry | GL404001 | Account Details for Period | 5 | 1 | 0 |
| AccountGroup | PM201000 |  | 8 | 1 | 0 |
| AccountSummaryInquiry | GL401000 | Account Summary | 5 | 1 | 0 |
| Activity | CR306010 | Activity | 16 | 1 | 1 |
| AmazonStore | BC201020 |  | 8 | 0 | 0 |
| Appointment | FS300200 |  | 38 | 11 | 10 |
| AttributeDefinition | CS205000 | Attributes | 8 | 1 | 0 |
| BigCommerceStores | BC201000 |  | 11 | 0 | 0 |
| Bill | AP301000 | Bills and Adjustments | 22 | 4 | 3 |
| Budget | GL302010 | Budgets | 8 | 1 | 0 |
| BusinessAccount | CR303000 |  | 23 | 18 | 6 |
| Carrier | CS207700 | Carriers | 11 | 2 | 0 |
| Case | CR306000 |  | 34 | 4 | 2 |
| CashSale | AR304000 | Cash Sales | 16 | 1 | 1 |
| CashTransaction | CA304000 | Cash Transactions | 6 | 1 | 1 |
| ChangeOrder | PM308000 |  | 21 | 5 | 7 |
| ChangeOrderClass | PM203000 |  | 7 | 1 | 0 |
| Check | AP302000 | Checks and Payments | 14 | 2 | 2 |
| CompaniesStructure | CS401000 | Company Branch | 0 | 1 | 0 |
| CompanyFinancialPeriod | GL201100 | Company Financial Calendar | 4 | 1 | 0 |
| Contact | CR302000 | Contacts | 58 | 12 | 4 |
| ContractUsage | CT303000 |  | 2 | 2 | 0 |
| CostCode | PM209500 |  | 3 | 0 | 1 |
| Currency | CM202000 | Currencies | 8 | 0 | 0 |
| Customer | AR303000 | Customers | 55 | 9 | 1 |
| CustomerClass | AR201000 | Customer Classes | 60 | 1 | 0 |
| CustomerLocation | AR303020 | Customer Locations | 32 | 2 | 0 |
| CustomerPaymentMethod | AR303010 | Customer Payment Methods | 11 | 1 | 0 |
| CustomerPriceClass | AR208000 | Customer Price Classes | 5 | 0 | 0 |
| DeductionBenefitCode | PR101060 |  | 14 | 8 | 0 |
| Discount | AR209500 | Discounts | 13 | 6 | 1 |
| DiscountCode | AR209000 | Discount Codes | 6 | 0 | 0 |
| EarningTypeCode | PR102000 |  | 10 | 4 | 0 |
| Email | CR306015 | Email Activity | 25 | 1 | 13 |
| EmailProcessing | SM507000 | Emails Pending Processing | 6 | 1 | 2 |
| Employee | EP203000 | Employees | 4 | 7 | 1 |
| EmployeePayrollClass | PR202000 |  | 3 | 1 | 0 |
| EmployeePayrollSettings | PR203000 |  | 9 | 12 | 1 |
| Event | CR306030 | Event | 18 | 4 | 7 |
| ExpenseClaim | EP301000 |  | 18 | 4 | 5 |
| ExpenseReceipt | EP301020 |  | 9 | 2 | 5 |
| ExternalCommitment | PM209000 |  | 21 | 0 | 0 |
| FOBPoint | CS208500 | FOB Points | 2 | 0 | 0 |
| FinancialPeriod | GL201000 | Master Financial Calendar | 6 | 1 | 0 |
| FinancialYear | GL101000 | Financial Year | 15 | 1 | 0 |
| InventoryAdjustment | IN303000 | Adjustments | 9 | 1 | 1 |
| InventoryAllocationInquiry | IN402000 | Inventory Allocation Details | 29 | 1 | 0 |
| InventoryIssue | IN302000 | Issues | 12 | 1 | 1 |
| InventoryQuantityAvailable | SO640590 | Available Quantity by Inventory Item | 2 | 1 | 0 |
| InventoryReceipt | IN301000 | Receipts | 12 | 1 | 1 |
| InventorySummaryInquiry | IN401000 | Inventory Summary | 5 | 1 | 0 |
| Invoice | AR301000 | Invoices and Memos | 24 | 7 | 1 |
| ItemClass | IN201000 | Item Classes | 17 | 1 | 0 |
| ItemSalesCategory | IN204060 | Item Sales Categories | 7 | 1 | 0 |
| ItemWarehouse | IN204500 | Item Warehouse  Details | 34 | 0 | 0 |
| JournalTransaction | GL301000 | Journal Transactions | 12 | 1 | 1 |
| KitAssembly | IN307000 | Kit Assembly | 16 | 3 | 1 |
| KitSpecification | IN209500 | Kit Specifications | 6 | 2 | 0 |
| LaborCostRate | PM209900 | Labor Rates | 7 | 1 | 0 |
| Lead | CR301000 |  | 47 | 7 | 6 |
| Ledger | GL201500 | Ledgers | 6 | 2 | 0 |
| LotSerialClass | IN207000 | Lot/Serial Classes | 6 | 1 | 0 |
| NonStockItem | IN202000 | Non-Stock Items | 55 | 6 | 1 |
| Opportunity | CR304000 |  | 34 | 8 | 4 |
| PTOBank | PR204000 |  | 16 | 4 | 0 |
| PayGroup | PR205000 |  | 23 | 0 | 0 |
| PayPeriod | PR201000 |  | 6 | 1 | 0 |
| Payment | AR302000 | Payments and Applications | 27 | 6 | 5 |
| PaymentMethod | CA204000 | Payment Methods | 12 | 3 | 0 |
| PayrollBatch | PR301000 |  | 14 | 4 | 1 |
| PayrollUnionLocal | PR209700 |  | 6 | 2 | 0 |
| PayrollWCCCode | PR209800 |  | 1 | 1 | 0 |
| PhysicalInventoryCount | IN305010 | Physical Inventory Count | 5 | 1 | 0 |
| PhysicalInventoryReview | IN305000 | Physical Inventory Review | 10 | 1 | 3 |
| ProFormaInvoice | PM307000 |  | 19 | 6 | 6 |
| Project | PM301000 |  | 12 | 15 | 15 |
| ProjectBudget | PM309000 |  | 45 | 0 | 0 |
| ProjectTask | PM302000 |  | 7 | 7 | 4 |
| ProjectTemplate | PM208000 |  | 4 | 7 | 2 |
| ProjectTemplateTask | PM208010 |  | 4 | 5 | 0 |
| ProjectTransaction | PM304000 |  | 11 | 1 | 1 |
| PurchaseOrder | PO301000 | Purchase Orders | 27 | 3 | 0 |
| PurchaseReceipt | PO302000 | Shipment Manager | 26 | 1 | 2 |
| SalesInvoice | SO303000 | Invoices | 32 | 13 | 1 |
| SalesOrder | SO301000 | Sales Orders | 54 | 15 | 9 |
| SalesPriceWorksheet | AR202010 | Sales Price Worksheets | 9 | 1 | 1 |
| SalesPricesInquiry | AR202000 | Sales Prices | 11 | 1 | 0 |
| Salesperson | AR205000 | Salespersons | 7 | 0 | 0 |
| ServiceOrder | FS300100 |  | 30 | 12 | 8 |
| ShipVia | CS207500 | Ship via Codes | 10 | 2 | 0 |
| Shipment | SO302000 | Shipments | 44 | 4 | 4 |
| ShippingBox | CS207600 | Boxes | 13 | 0 | 0 |
| ShippingTerm | CS208000 | Shipping Terms | 2 | 1 | 0 |
| ShippingZones | CS207510 | Shipping Zones | 2 | 0 | 0 |
| ShopifyStore | BC201010 |  | 7 | 0 | 0 |
| StockItem | IN202500 | Stock Items | 83 | 9 | 1 |
| StorageDetailsByLocationInquiry | IN408055 | Storage Details by Item Warehouse Location | 2 | 1 | 0 |
| StorageDetailsInquiry | IN408050 | Storage Details | 1 | 1 | 0 |
| Subaccount | GL203000 | Subaccounts | 5 | 0 | 0 |
| Subcontract | SC301000 |  | 31 | 4 | 2 |
| Task | CR306020 | Task | 21 | 4 | 2 |
| Tax | TX205000 | Taxes | 23 | 2 | 0 |
| TaxCategory | TX205500 | Tax Categories | 6 | 1 | 0 |
| TaxReportingSettings | TX205100 | Reporting Settings | 1 | 1 | 0 |
| TaxZone | TX206000 | Tax Zones | 4 | 1 | 0 |
| TemplateItems | IN203000 |  | 29 | 5 | 0 |
| TimeEntry | PM209100 |  | 23 | 0 | 2 |
| TransferOrder | IN304000 | Transfers | 12 | 1 | 1 |
| UnionLocal | PM209700 |  | 3 | 0 | 0 |
| UnitsOfMeasure | CS203500 | Units of Measure | 3 | 1 | 0 |
| Vendor | AP303000 | Vendors | 47 | 7 | 1 |
| VendorClass | AP201000 | Vendor Classes | 4 | 1 | 0 |
| VendorPriceWorksheet | AP202010 | Vendor Price Worksheets | 10 | 1 | 1 |
| VendorPricesInquiry | AP202000 | Vendor Prices | 5 | 1 | 0 |
| Warehouse | IN204000 | Warehouses | 34 | 1 | 0 |
| WorkCalendar | CS209000 | Work Calendar | 3 | 2 | 0 |
| WorkClassCompensationCode | PM209800 |  | 5 | 0 | 0 |
| WorkLocation | PR101040 |  | 5 | 1 | 0 |

Entity schemas in the swagger that no top-level entity references (listed in `fields.md` only): `EmployeePaycheckEarningDetail`, `ItemPriceClassesDetails`, `ItemsDetails`, `PurchaseSettings`.
```

## File: skills/acumatica-assistant/references/endpoints/Default-25.200.001/expand-paths.md
size: 32798
sha: aede529ba1694289b3cef9900100ab1e18985b61
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/endpoints/Default-25.200.001/expand-paths.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/endpoints/Default-25.200.001/expand-paths.md

## File: skills/acumatica-assistant/references/endpoints/Default-25.200.001/fields.md
size: 242795
sha: 655021f935e44b435db452df3c09599b15c0399d
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/endpoints/Default-25.200.001/fields.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/endpoints/Default-25.200.001/fields.md

## File: skills/acumatica-assistant/references/endpoints/INDEX.md
size: 7678
sha: 2ab19dd155cc7d687b8c3c5a9d349e715948894c
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/endpoints/INDEX.md

```text
<!-- source: swagger.json (OpenAPI 3.0) of the system endpoints listed below; cross-checked against Acumatica's Integration Development Guide | version: per snapshot (Default/25.200.001 = Acumatica ERP 2025 R2, build 25.201.0213) | verified: 2026-10-05 -->

# Endpoint contract references index

**Exact entity, field and action names** of a system endpoint, generated from that endpoint's OpenAPI document
by `scripts/build_endpoint_reference.py`. One folder per endpoint version. Use it to name things; the protocol
rules (URLs, `$expand` syntax, PUT/POST, status codes) stay in `references/rest/`.

| Path | Covers | Version | Verified |
|---|---|---|---|
| `Default-25.200.001/entities.md` | **Start here.** The 119 top-level entities with form ID, screen title and counts of fields, nested entities and actions; the system members every entity carries | 2025 R2, Contract Version 4 | 2026-10-05 |
| `Default-25.200.001/fields.md` | Every field of all 428 entity schemas (119 top-level, 309 nested), one line each: `Schema.Field : Type` (5,338 lines) | 2025 R2, Contract Version 4 | 2026-10-05 |
| `Default-25.200.001/expand-paths.md` | The 575 linked/detail paths reachable from the top-level entities, one line each: `Entity: Path -> Schema` | 2025 R2, Contract Version 4 | 2026-10-05 |
| `Default-25.200.001/actions.md` | The 163 actions the contract names on 50 entities, with parameter names and types: `Entity.Action(Parameter: Type, ...)` | 2025 R2, Contract Version 4 | 2026-10-05 |

No snapshot of `Default/26.200.001` (Contract Version 5) or of `MANUFACTURING` is bundled yet.

## Looking a name up

Grep; never read `fields.md` whole.

| Question | Grep |
|---|---|
| Does the entity exist, which form is it | `^\| SalesOrder \|` or the form ID (`SO301000`) in `entities.md` |
| An entity's fields | `^SalesOrder\.` in `fields.md` |
| Is it `CustomerID` or `Customer` on this entity | `^SalesOrder\.Customer` in `fields.md` |
| Which entities carry a field | `\.InventoryID ` in `fields.md` |
| What can be expanded, and the schema behind it | `^SalesOrder: ` in `expand-paths.md`, then `^SalesOrderDetail\.` in `fields.md` |
| Where a nested schema is used | `-> Address` in `expand-paths.md` |
| An entity's actions and their parameters | `^Shipment\.` in `actions.md` |
| Which action does X | the verb (`Release`, `Confirm`, `Hold`) in `actions.md` |

A nested schema's name is not the name you send: requests use the **field** name on the parent (`Details`), the
schema name (`SalesOrderDetail`) only tells you where its fields are listed.

## Using the snapshot for another endpoint version

The snapshot is exact for `Default/25.200.001` only.

- **`Default/26.200.001` (Contract Version 5):** most names carry over, but check
  `references/rest/endpoint-versions.md` § 3 first: it lists the entities added, the fields renamed or removed
  (for example `SalesOrder.LastModified` became `LastModifiedDateTime`, every `Subitem` field went, and
  `SalesOrder.UsrExternalOrderOriginal` became `ExternalOrderOriginal`) and the retyping of drop-down and date-only
  fields. Say the name was taken from the 25.200.001 contract and must be confirmed on the instance.
- **`Default/24.200.001` and earlier:** a name here may not exist yet; `endpoint-versions.md` § 3 lists what each
  later version added. Same caveat.
- **Custom endpoints, endpoint extensions and `MANUFACTURING`:** not covered. Use the instance's `swagger.json`.

## Sources

| ID | Source | Role | Verified |
|---|---|---|---|
| `swagger-25.200.001` | `GET <instance URL>/entity/Default/25.200.001/swagger.json` (OpenAPI 3.0.1, `info.version` 4) from an Acumatica ERP 2025 R2 instance, build 25.201.0213. The instance was a **sandbox of a live site, not a clean demo instance**; its name is withheld. The raw document is not in the repository; a scrubbed copy (`servers` removed) belongs at `sources/acumatica-assistant/Default-25.200.001.swagger.json` so the snapshot can be rebuilt. **Pending:** that copy has not been added yet, so until it is the snapshot cannot be rebuilt by others (`sources/acumatica-assistant/README.md`). | Every file under `Default-25.200.001/` | 2026-10-05 |
| `guide-2025r2` | Acumatica ERP *Integration Development* developer guide, 2025 R2 (PDF, last updated 2025-12-15), topic *Comparison of System Endpoints*. Maintenance input, not in the repository. | Cross-check of the snapshot (below) | 2026-10-05 |
| `guide` | `references/rest/endpoint-versions.md` and `references/rest/examples-catalogue.md` (2026 R2 guide) | Cross-check of the snapshot (below) | 2026-10-05 |

## Why a sandbox's swagger is safe to bundle, and how it was checked

- A system endpoint's contract cannot be changed, and the endpoint version fixes its entities, fields and actions
  (`references/rest/rest-api-guide.md` § 1, guide topic *Endpoints and Contracts*), so the `Default` contract does
  not carry a site's customizations. Custom fields and user-defined fields are outside the contract and are not
  in the swagger.
- The only site-specific value in the document is the instance URL in `servers`; the generator never writes it
  and writes nothing if any part of the host name (generic words such as `erp` or `sandbox` excepted) appears in
  its output.
- One name has the `Usr` prefix customizations use: `SalesOrder.UsrExternalOrderOriginal`. It is Acumatica's own:
  the 2025 R2 guide lists it for Sales Orders, and the 2026 R2 guide records its removal in `Default/26.200.001`
  in favour of `ExternalOrderOriginal`.
- Cross-checks run on 2026-10-05, all passing: none of the 14 entities the guide says are new in 26.200.001 is
  present; both entities and the 50 field and action names the 2025 R2 guide lists as new in 25.200.001 are
  present; the eight fields it lists as removed in 25.200.001 are absent; all 49 `Default` entities used by the
  guide's examples are present.

## Scope and limits

- **Names and types only.** The swagger has no field descriptions, no mandatory flags, no key fields and, in
  Contract Version 4, no drop-down values (a drop-down is a `StringValue`). Find allowed values on the form, and
  key fields from the form (`rest-api-guide.md` § 5).
- **The contract, not the instance.** The snapshot says what the contract defines, not which features the
  client's instance has enabled: the guide's examples name the features each needs (`examples-catalogue.md`,
  "Features required") and `GET /entity` returns `features[]`. A name that is absent here is absent from
  `Default/25.200.001`, not necessarily from the form: an element outside the contract is reached as a custom
  field (`rest-api-guide.md` § 7).
- **Contract actions are not all the actions.** Any workflow action of the form can be posted to
  `<Entity>/<action name>` and is discovered with `$adHocSchema` (`rest-api-guide.md` § 2 and § 6). The guide's own
  examples post to four names that this contract does not define: `Case/Close` (its custom-action example),
  `Bill/Approve`, `Payment/Release` and `ProjectTask/Activate`; the contract's names for the last two are
  `Payment.ReleasePayment` and `ProjectTask.ActivateProjectTask`. Prefer the contract name when one exists and say
  which you used.
- Four entity schemas are defined but not referenced by any top-level entity (`EmployeePaycheckEarningDetail`,
  `ItemPriceClassesDetails`, `ItemsDetails`, `PurchaseSettings`); they are in `fields.md` and cannot be reached
  through this endpoint.
- Build 25.201.0213 is one build of 2025 R2. The guide states the endpoint version fixes the contract, so other
  2025 R2 builds should expose the same `Default/25.200.001`; this was not tested against a second build.
```

## File: skills/acumatica-assistant/references/odata/common-mistakes.md
size: 7905
sha: 1b5d62efbe5d4164679ccbab3b6353b6a001bfbf
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/odata/common-mistakes.md

```text
<!-- source: facts from the Acumatica Reporting Tools Guide topics named per row (URLs in INDEX.md), the System Administration Guide "User Roles: Predefined Roles", the I300 "Data Retrieval with OData" course (2024 R1) and the bundled 2026 R2 DAC metadata snapshot; the "wrong" column is the mistake an integrator makes, the "right" column is the documented rule | version: Acumatica ERP 2026 R2 (guide edition 2026-09-30) | verified: 2026-10-06 -->

# Common mistakes when reading Acumatica through OData

Use as a review checklist for OData consumers (BI tools, Power Query, sync jobs). Grep the request, Power Query M or
code for the pattern in "Looks like", then apply the rule.

| # | Looks like | Why it is wrong | Rule (source) |
|---|---|---|---|
| 1 | `PUT` / `POST` / `PATCH` / `DELETE` to `/api/odata/...` | Both OData interfaces are read-only. Writes go through the REST API (`references/rest/`). | I300 *OData Endpoints*; *Accessing DACs Through OData* |
| 2 | `/odata/dac/SOOrder` without `/t/<TenantName>/`, or the tenant appended to the username | 2026 R2 URLs are `<instance>/t/<TenantName>/api/odata/dac` and `.../gi`; the tenant is the login name from Tenant List (SM203530), spaces as `%20`; the username carries no tenant suffix. The 2024 R1 shapes are `/OData/<Tenant>` (3.0) and `/ODatav4/<Tenant>` (4.0), tenant optional on single-tenant instances; `/odatav4/<Tenant>` still answers on a clean 2026 R2 instance as an alias of `/t/<Tenant>/api/odata/dac` (owner-verified), so do not flag it as broken, only as undocumented. | *DAC-Based OData: General Information*; *... in Microsoft Excel*; I300 Examples 1.1.1, 1.1.2; owner test 2026-10-06 |
| 3 | Treating `/OData/` (inquiry) requests as OData 4.0 on an older release, or `datetime'...'` literals on 2026 R2 | 2024 R1 documents the inquiry endpoint as OData **3.0** (`odata.metadata` key, `$format=json`, `datetime'...'`); 2026 R2 documents `/api/odata/gi` as OData 4.0 with bare literals. Probe `$metadata` and read its `edmx` version. | I300 Example 1.1.1; *Generic Inquiries and OData: General Information* |
| 4 | Polling `/api/odata/gi/<Inquiry>` for an inquiry that has parameters | The entity set does not bind parameters and can return an empty result without an error; call `<Title>_WithParameters(Param='value')` (or `(Param=@1)?@1='value'`). | *Generic Inquiry Access Through OData: Data Retrieval* |
| 5 | `$expand=` or `$count` on an inquiry-based URL | Not supported by the inquiry-based interface, nor is `IsOf()`. Build one inquiry per detail kind, or use the DAC-based interface. | *Generic Inquiries and OData: Preparation of an Inquiry for Exposure* |
| 6 | Reading an empty 200 response as "no rows" | For inquiries, 200 with **no body** signals an unsupported query (for example filtering or sorting on a formula column); an empty result is `{"value": []}`. | *... Data Retrieval*; *... Preparation of an Inquiry for Exposure* |
| 7 | `$filter=NoteText eq ...` or `$select=...,DocBal` on a DAC | Fields in the entity set's `Cap.FilterRestrictions` `NonFilterableProperties` are refused in **both** `$filter` and `$select`; `Filterable=false` bars every field declared in that DAC (inherited fields allowed). Check `metadata/entity-sets.md`. | *DAC-Based OData: General Information*, *Basic Data Retrieval*, *Filtering Records* |
| 8 | `$filter=ItemStatus eq 'Active'` on `InventoryItem` | DAC filters use the **stored value** (`'AC'`); inquiry filters use the displayed value (`'Active'`). Element Inspector's Drop-Down Values lists both. | *DAC-Based OData: To Filter the Requested Data*; *... To Filter the Results of a Generic Inquiry*; *DAC Discovery: General Information* |
| 9 | `$filter=InventoryID eq 'AALEGO500'` on `INSiteStatus` | DAC foreign keys are integer IDs (`InventoryID eq 41`); the code lives on the related DAC (`$expand=InventoryItemByInventoryID($select=InventoryCD)`), and filtering on a related field uses the navigation path (`Nav/Field eq ...`). Check the field's Edm type in the snapshot. | *... $expand, $select, and $filter Parameters*; *Filtering Records* |
| 10 | `$filter=SOLineCollection/InventoryID eq 1` | Collections are filtered with lambdas: `SOLineCollection/Any(x: x/InventoryID eq 1)`, `All(...)`, or `SOLineCollection/$count eq 3`. | *DAC-Based OData: Filtering Records* |
| 11 | `$expand=A($expand=B($expand=C($expand=D)))` | Expansion depth is 3 by default; raise `maxExpansionDepth` on the `odata` element in `Web.config` or flatten the query. | *DAC-Based OData: Basic Data Retrieval* |
| 12 | `$top`/`$skip` paging without `$orderby` | The documented pattern adds `$orderby`; without it the server orders by key fields ascending, which is fine only if that is what the page boundaries assume. | *Basic Data Retrieval*; *... Data Retrieval* |
| 13 | `$apply=groupby(...)` or `aggregate(...)` | The OData aggregation extension is not supported; aggregate client-side or build an inquiry. | *DAC-Based OData: General Information*; I300 Example 3.1.2 |
| 14 | Delta sync on `LastModifiedDateTime` only | Deletions are invisible to a modified-date filter. Add the DAC on Tables to Track Deleted Records (SM207010) and read `<DAC>/px.GetDeletedRecords()?$filter=DeleteDate ge ...`; send `PX-ApiDeleted: SHOW` to see soft-deleted rows, `PX-ApiArchive: SHOW` for archived ones. | *DAC-Based OData: Retrieving Archived and Removed Records* |
| 15 | `2024-11-01T00:00:00+03:00` unencoded in a URL | `+` must be sent as `%2b` in a query string; `Z` or a negative offset needs no encoding. | *Retrieving Archived and Removed Records*; I300 Example 3.1.2 |
| 16 | Sizing the API-user licence for OData basic-auth clients | Basic-auth OData sign-ins count as **conventional users** (Concurrent Users on License Monitoring Console (SM604000)), not API users; OAuth sessions count as API users. | *DAC-Based OData: General Information*; I300 Appendix A |
| 17 | Giving a BI account `Administrator` because OData "returned nothing" | Inquiry-based reads need **View Only** on the inquiry (Hidden node when it has no workspace); the `BI` role covers the predefined `BI-*` inquiries and `OData4 User` covers DAC-based access; the DAC interface shows what the UI rights show. | *... To Expose Inquiry Results Through OData*; *User Roles: Predefined Roles* |
| 18 | Expecting the inquiry's grid columns only | Inquiry metadata also publishes the source tables' key fields even when they are not in the results grid; names are generated from English captions (spaces removed, leading digit prefixed with `_`, duplicates suffixed `_2`). | *Generic Inquiry Access Through OData: General Information*; *... Preparation of an Inquiry for Exposure* |
| 19 | Parsing `QtyOnHand` as a number from an inquiry response, or `odata.metadata` as `@odata.context` | The inquiry examples print decimals as strings and the key `odata.metadata`; DAC responses print JSON numbers and `@odata.context`. Parse defensively. | *... with Parameters*, *... To Filter the Results ...*; *DAC-Based OData: Basic Data Retrieval* |
| 20 | Naming a DAC or field that is not in `metadata/` and not on the client's `$metadata` | A clean 2026 R2 snapshot is bundled; a client's instance differs by modules, customizations and user-defined fields. Verify on the client's `/api/odata/dac/$metadata` or with Element Inspector. | `metadata/INDEX.md`; *DAC Discovery: General Information* |
| 21 | Opening CORS to `*` in production because "it did not work" | CORS is already on for all origins by default; browser clients need the four OData headers in `exposedHeaders`. Restrict `origins` instead; saving `Web.config` restarts the site. | *To Configure CORS* |
| 22 | Reading `Customer` fields from the `Customer` entry only | Derived DACs list only added fields; `PX.Objects.AR.Customer` inherits key and most fields from `PX.Objects.CR.BAccount` (`BaseType` column in `metadata/api/INDEX.md`). | bundled snapshot |
```

## File: skills/acumatica-assistant/references/odata/INDEX.md
size: 6450
sha: 6a5a8aacfc0e597ee27df77f1f815fb7641fb13c
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/odata/INDEX.md

```text
<!-- source: Acumatica Reporting Tools Guide and System Administration Guide on Acumatica Beacon, the I300 "Data Retrieval with OData" training course (2024 R1), and the DAC-based OData $metadata of a clean 2026 R2 instance (sources table below) | version: Acumatica ERP 2026 R2 (guide edition 2026-09-30); I300 is 2024 R1 | verified: 2026-10-06 -->

# OData references index

Curated facts for the two **read-only** OData interfaces: DAC-based (`/t/<TenantName>/api/odata/dac`, data access
classes straight from the metadata) and generic-inquiry-based (`/t/<TenantName>/api/odata/gi`, exposed inquiries).
Read `odata-guide.md` first; open the metadata snapshot only to look up a DAC, a field, a navigation property or an
entity-set name. The prose files are extractions (URL patterns, parameters, headers, rules and their exceptions),
not copies of the pages; every section names the topic it came from so it can be re-checked.

| Path | Covers | Version | Verified |
|---|---|---|---|
| `odata-guide.md` | **Start here.** The two interfaces, URLs and tenant names (2026 R2 and the 2024 R1 shapes), authentication / roles / licence, what `$metadata` contains, DAC-based requests (`$select`, `$expand`, `$filter` incl. navigation and lambda filters, paging, key access), headers (`PX-ApiArchive`, `PX-ApiDeleted`, `Accept-Language` / `locale`), `px.GetDeletedRecords()`, inquiry-based requests (`_WithParameters`, unsupported options, 200-without-body), CORS / `Web.config`, Excel and Power BI, OData versus REST | 2026 R2 (+ 2024 R1 where marked) | 2026-10-06 |
| `common-mistakes.md` | 22 review rules for OData consumers: the wrong pattern, why, and the topic with the rule | 2026 R2 | 2026-10-06 |
| `metadata/INDEX.md` | **Generated** snapshot of a clean 2026 R2 instance's DAC-based `$metadata`: how to read it, counts, Edm types, limits | 2026 R2 | 2026-10-06 |
| `metadata/entity-sets.md` | One row per DAC: URL names (`PX_Objects_SO_SOOrder`, `SalesOrder`, `SOOrder`), key, non-filterable fields, `Filterable=false`; singletons | 2026 R2 | 2026-10-06 |
| `metadata/api/INDEX.md` | One row per EntityType / ComplexType: label, key, field and navigation counts, base type, entity sets, bundle file and line range | 2026 R2 | 2026-10-06 |
| `metadata/api/members-01.md` ... `members-06.md` | The entries: `Type.Field : Edm.Type [key] [required] "Display name"` and `Type.Nav -> Target (LocalField=TargetField)`, one line each, grouped by type | 2026 R2 | 2026-10-06 |
| `metadata/enums.md` | The single EnumType the DAC metadata declares | 2026 R2 | 2026-10-06 |

## Sources

| ID | Source | Role | Verified |
|---|---|---|---|
| `rtg` | https://beacon.acumatica.com/r/Reporting-Tools-Guide/Reporting-Tools-Guide | Acumatica's Reporting Tools Guide (Fluid Topics map `4PtabvulGtJrxqfuktkFcw`, 229 topics, metadata version "2026 R2", last edition 2026-09-30). | 2026-10-06 |
| `rtg/dac` | https://beacon.acumatica.com/r/Reporting-Tools-Guide/Accessing-DACs-Through-OData | Chapter *Accessing DACs Through OData* (11 topics: general information, basic data retrieval, filtering, related data, localized and custom fields, archived and removed records, four activities) | 2026-10-06 |
| `rtg/gi-expose` | https://beacon.acumatica.com/r/Reporting-Tools-Guide/Managing-Generic-Inquiries/Exposing-Inquiry-Results-by-Using-OData | Chapter *Exposing Inquiry Results by Using OData* (4 topics) | 2026-10-06 |
| `rtg/gi-access` | https://beacon.acumatica.com/r/Reporting-Tools-Guide/Managing-Generic-Inquiries/Accessing-the-Exposed-Inquiry-Results-Through-OData | Chapter *Accessing the Exposed Inquiry Results Through OData* (10 topics: general information, data retrieval, Power BI, Excel, CORS, four activities) | 2026-10-06 |
| `rtg/dac-discovery` | https://beacon.acumatica.com/r/Reporting-Tools-Guide/Managing-Generic-Inquiries/Discovering-DACs/DAC-Discovery-General-Information | *DAC Discovery: General Information* and *Data from Multiple Data Sources: DAC Schema Browser* (finding the DAC and field behind a form element) | 2026-10-06 |
| `sag/roles` | https://beacon.acumatica.com/r/System-Administration-Guide/Configuring-User-Roles/User-Roles-Predefined-Roles | System Administration Guide, *User Roles: Predefined Roles* (the `BI` and `OData4 User` roles), 2026 R2 edition | 2026-10-06 |
| `i300` | Acumatica training course *I300 Data Retrieval with OData*, 2024 R1, revision 2024-03-21 (PDF; Postman collection in the `IntegrationDevelopment\I300` folder of Acumatica's Help-and-Training-Examples GitHub repository) | The 2024 R1 endpoint shapes (`/OData/<Tenant>` OData 3.0 for inquiries, `/ODatav4/<Tenant>` for DACs), OData 3.0 request syntax, Appendix A comparison of OData 3.0 / 4.0 / REST | 2026-10-06 |
| `metadata` | `GET <instance URL>/t/<TenantName>/api/odata/dac/$metadata` of a clean Acumatica ERP 2026 R2 instance, 20 MB CSDL, compiled by `scripts/build_odata_metadata_ref.py` (the raw XML is not committed) | `metadata/` | 2026-10-06 |

Any Reporting Tools Guide topic is reachable as
`https://beacon.acumatica.com/r/Reporting-Tools-Guide/<Chapter>/<Topic-Title-With-Hyphens>`.

## Known limits of these references

- **Two editions.** The guide is 2026 R2 and documents only the `/t/<TenantName>/api/odata/{dac,gi}` URLs and OData
  4.0 for both interfaces. The course is 2024 R1 and documents `/OData/` (OData 3.0) and `/ODatav4/`. Nothing here says
  in which release the URLs changed. The owner verified on a clean local 2026 R2 instance (Postman, 2026-10-06) that
  `/odatav4/<TenantName>/$metadata` and `/t/<TenantName>/api/odata/dac/$metadata` are interchangeable; the
  inquiry-based `/OData/<TenantName>` path was not tested, so probe `$metadata` on the client's instance and read the
  `edmx` version before relying on it.
- **One clean instance.** The metadata snapshot has every module of a clean 2026 R2 install (2,265 DACs, 5,108 entity
  sets) and no customization. A client's instance adds custom and user-defined fields and extension DACs and may lack
  modules; confirm names on the client's `$metadata`. No inquiry-based (`/api/odata/gi`) metadata is bundled, because
  it is tenant-specific.
- The guide's request examples are reproduced as URL patterns only; response bodies are summarised.
- Behaviour the pages do not state (status codes for refused fields, page-size caps, timeouts, `$search`,
  `$batch`, `$metadata` caching) is **not covered**; say so rather than guessing from the OData standard.
```

## File: skills/acumatica-assistant/references/odata/metadata/api/INDEX.md
size: 452265
sha: 43a3c9103692b8a125b5e956010d1ea70062e6a4
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/odata/metadata/api/INDEX.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/odata/metadata/api/INDEX.md

## File: skills/acumatica-assistant/references/odata/metadata/api/members-01.md
size: 995790
sha: 2f38f09e0984d6db7601eae793491cbd5a8c716e
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/odata/metadata/api/members-01.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/odata/metadata/api/members-01.md

## File: skills/acumatica-assistant/references/odata/metadata/api/members-02.md
size: 998824
sha: 6bdb5a15004094d26de0412b64327ebe2b463134
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/odata/metadata/api/members-02.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/odata/metadata/api/members-02.md

## File: skills/acumatica-assistant/references/odata/metadata/api/members-03.md
size: 999695
sha: 49a6dab5ee2eb82690ce925ba3a51f68d062f9a2
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/odata/metadata/api/members-03.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/odata/metadata/api/members-03.md

## File: skills/acumatica-assistant/references/odata/metadata/api/members-04.md
size: 997587
sha: ff78a995b4baf0a2a6bbd0bdc587880b031d550f
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/odata/metadata/api/members-04.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/odata/metadata/api/members-04.md

## File: skills/acumatica-assistant/references/odata/metadata/api/members-05.md
size: 993773
sha: c80c08d189bae11f0c2d8efbb846e4adb197e318
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/odata/metadata/api/members-05.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/odata/metadata/api/members-05.md

## File: skills/acumatica-assistant/references/odata/metadata/api/members-06.md
size: 924884
sha: 80827814ae710575e5096c904475e20800657f5e
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/odata/metadata/api/members-06.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/odata/metadata/api/members-06.md

## File: skills/acumatica-assistant/references/odata/metadata/entity-sets.md
size: 398438
sha: 97709740e83e7f2772ac62f38fb4b2c9a97b5aed
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/odata/metadata/entity-sets.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/odata/metadata/entity-sets.md

## File: skills/acumatica-assistant/references/odata/metadata/enums.md
size: 424
sha: b1b9a431005c4381ae874738bad8569fabc3ce5c
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/odata/metadata/enums.md

```text
<!-- source: DAC-based OData $metadata of a clean Acumatica ERP instance (GET <instance URL>/t/<TenantName>/api/odata/dac/$metadata) | version: Acumatica ERP 2026 R2 | verified: 2026-10-06 -->

# DAC-based OData enum members

PX.SM.CustObjectTypes.ColumnLength = 4
PX.SM.CustObjectTypes.Raw = 0
PX.SM.CustObjectTypes.Schema = 3
PX.SM.CustObjectTypes.Sql = 1
PX.SM.CustObjectTypes.Table = 2
PX.SM.CustObjectTypes.Unknown = 5
```

## File: skills/acumatica-assistant/references/odata/metadata/INDEX.md
size: 9577
sha: d2507e5cef1dfeb31197d09aeaf8a8299b461f2d
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/odata/metadata/INDEX.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/odata/metadata/INDEX.md

## File: skills/acumatica-assistant/references/odata/odata-guide.md
size: 18692
sha: a228aa3a5a9d747cfd6b3a03cf1157fb320eabb8
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/odata/odata-guide.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/odata/odata-guide.md

## File: skills/acumatica-assistant/references/rest/authentication.md
size: 10431
sha: 1fa4f8219782b5f2f5a19106b4a3d7a5b9c224ba
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/rest/authentication.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/rest/authentication.md

## File: skills/acumatica-assistant/references/rest/common-mistakes.md
size: 8738
sha: b751aec6e985337337accb95dd895dc6c6ecfd93
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/rest/common-mistakes.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/rest/common-mistakes.md

## File: skills/acumatica-assistant/references/rest/endpoint-versions.md
size: 10948
sha: 339dacf4a1f1c2d425ab7edb084e61336ea85967
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/rest/endpoint-versions.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/rest/endpoint-versions.md

## File: skills/acumatica-assistant/references/rest/examples-catalogue.md
size: 57146
sha: 2096123ce4cca644048ec154bb86f0fb72ebaa41
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/rest/examples-catalogue.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/rest/examples-catalogue.md

## File: skills/acumatica-assistant/references/rest/INDEX.md
size: 5632
sha: 81ba120596f9d5d51bf3bf31e3da9b10d15f5253
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/rest/INDEX.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/rest/INDEX.md

## File: skills/acumatica-assistant/references/rest/push-and-webhooks.md
size: 5528
sha: 134e25b3fd2781cb0912935fed7b08e0cd7e10c5
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/rest/push-and-webhooks.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/rest/push-and-webhooks.md

## File: skills/acumatica-assistant/references/rest/query-parameters.md
size: 6165
sha: 5a74477c78c2bf14512c91fcdabc8a49bad1eb93
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/rest/query-parameters.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/rest/query-parameters.md

## File: skills/acumatica-assistant/references/rest/rest-api-guide.md
size: 20952
sha: 7f0957f2d550be25c9fc07084d9a825cad2528b7
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/rest/rest-api-guide.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/references/rest/rest-api-guide.md

## File: skills/acumatica-assistant/.claude-plugin/plugin.json
size: 1666
sha: cc4b896e60f48effd28cac464c1ef0cac9f7edb8
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/.claude-plugin/plugin.json

```text
{
  "name": "acumatica-assistant",
  "displayName": "Acumatica Assistant",
  "description": "Acumatica ERP assistant: REST integration development against the contract-based REST API from a bundled extraction of Acumatica's Integration Development Guide (2026 R2) — sign-in and OAuth 2.0/OIDC, endpoint and contract versions, JSON record shape, query parameters per contract version, CRUD, actions and long-running operations, custom fields, files, license limits, push notifications and webhooks, with a catalogue of 187 documented example requests, and exact entity, field and action names from a snapshot of the Default/25.200.001 contract (2025 R2); OData data access — DAC-based and generic-inquiry-based OData v4 reads (URLs, auth and licence, $filter/$expand, deleted-record tracking, CORS, Excel and Power BI) from the Reporting Tools Guide (2026 R2), with a DAC $metadata snapshot of a clean 2026 R2 instance for exact DAC, field and navigation names. More capabilities to follow.",
  "author": {
    "name": "Francois Taljaard",
    "url": "https://github.com/fdtaljaard"
  },
  "homepage": "https://github.com/fdtaljaard/claude-skills/tree/main/skills/acumatica-assistant",
  "repository": "https://github.com/fdtaljaard/claude-skills",
  "license": "MIT",
  "keywords": [
    "acumatica",
    "erp",
    "rest-api",
    "odata",
    "integration"
  ],
  "icon": "./icon.png",
  "documentationUrl": "https://github.com/fdtaljaard/claude-skills/tree/main/skills/acumatica-assistant#readme",
  "supportUrl": "https://github.com/fdtaljaard/claude-skills/issues",
  "privacyPolicyUrl": "https://github.com/fdtaljaard/claude-skills/blob/main/PRIVACY.md"
}
```

## File: skills/acumatica-assistant/evals/evals.json
size: 15971
sha: 869b7b96e17a874edaf3d1daf423469c592df176
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/evals/evals.json

Content is not inlined in the catalog. Read the upstream file: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/evals/evals.json

## File: skills/acumatica-assistant/icon.png
size: 99173
sha: eea24098c71a9f03246c0c81c9c4026f5f00a29f
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/icon.png

Content is not inlined in the catalog. Read the upstream file: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/icon.png

## File: skills/acumatica-assistant/MAINTENANCE.md
size: 15179
sha: 5e4022f5271ad199ce33ce667c267f94a4563bca
upstream: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/MAINTENANCE.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fdtaljaard/claude-skills/blob/main/skills/acumatica-assistant/MAINTENANCE.md
