acumatica-api 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,232 @@
1
+ Metadata-Version: 2.4
2
+ Name: acumatica-api
3
+ Version: 0.1.0
4
+ Summary: A lightweight Python SDK for the Acumatica contract-based REST API, built with `httpx2`.
5
+ Requires-Python: >=3.14
6
+ Description-Content-Type: text/markdown
7
+ Requires-Dist: httpx2>=2.4.0
8
+ Requires-Dist: tenacity>=9.1.4
9
+
10
+ # Acumatica
11
+
12
+ A lightweight Python SDK for the [Acumatica](https://www.acumatica.com) contract-based
13
+ REST API, built on [`httpx`](https://www.python-httpx.org/).
14
+
15
+ Read-only. The ODS mirrors the ERP rather than driving it, and a contract-based `PUT`
16
+ creates as well as updates, so write support waits until something needs it.
17
+
18
+ ## Installation
19
+
20
+ ```bash
21
+ uv add acumatica-api
22
+ ```
23
+
24
+ ## Requirements
25
+
26
+ - Python 3.14+
27
+
28
+ ## Quick Start
29
+
30
+ ```python
31
+ from acumatica import Acumatica
32
+
33
+ with Acumatica(
34
+ "https://example.acumatica.com",
35
+ client_id="11111111-2222-3333-4444-555555555555@MyTenant",
36
+ client_secret="...",
37
+ username="ods",
38
+ password="...",
39
+ ) as client:
40
+ item = client.entity("StockItem").get("127-004033-001")
41
+ print(item["Descr"]["value"])
42
+ ```
43
+
44
+ ## Authentication
45
+
46
+ Resource Owner Password Credentials, which is the only headless flow you can actually
47
+ register. The identity server advertises `client_credentials`, but Connected
48
+ Applications (SM303010) offers only Authorization Code, Implicit, ROPC and Hybrid.
49
+
50
+ **The tenant lives in the client ID**, not in a separate parameter. The ID issued at
51
+ registration ends in `@Tenant`, and that is what scopes the session.
52
+
53
+ The client requests the `api` and `offline_access` scopes, which means Acumatica reuses
54
+ a single session ID across the whole refresh chain. Pass a `TokenStore` so that chain
55
+ survives a cold start:
56
+
57
+ ```python
58
+ from acumatica import Acumatica, TokenStore
59
+
60
+
61
+ class SecretsManagerTokenStore(TokenStore):
62
+ def load(self) -> str | None: ...
63
+ def save(self, refresh_token: str) -> None: ...
64
+
65
+
66
+ client = Acumatica(..., token_store=SecretsManagerTokenStore())
67
+ ```
68
+
69
+ > **Refresh tokens are single-use and rotate, so a persisted one is mutable shared
70
+ > state.** If several workers cold-start and refresh from the same value, one wins and
71
+ > the rest get `invalid_grant` — and a loser writing its spent token back destroys the
72
+ > chain for everyone. Prefer a single refresher: one rate-limited queue consumer rather
73
+ > than a worker per webhook notification.
74
+
75
+ By default the whole chain expires 30 days after the *initial* authentication however
76
+ often it is redeemed, unless Sliding Expiration is configured for the application on
77
+ SM303010. The client falls back to the password grant when a refresh is refused, so
78
+ this recovers without a human — but it is worth turning the setting on.
79
+
80
+ ## Endpoints
81
+
82
+ An endpoint is a contract, not a namespace, so a client is bound to one. Reading
83
+ manufacturing data alongside inventory means a second client:
84
+
85
+ ```python
86
+ default = Acumatica(creds..., endpoint="Default", version="25.200.001")
87
+ mfg = Acumatica(
88
+ creds...,
89
+ endpoint="MANUFACTURING",
90
+ version="25.100.001",
91
+ limiter=default.limiter,
92
+ session=default.session,
93
+ )
94
+ ```
95
+
96
+ **Share the limiter and the session whenever a process holds more than one
97
+ client.** The budget is tenant-wide, so two clients each pacing to 100/min spend
98
+ 200 against a cap of 150; and since both address the same instance with the same
99
+ credentials, a shared session is one token and one of the 20 API user slots rather
100
+ than two of each. `close()` ends what it was given, so close the borrower first or
101
+ let one owner do it.
102
+
103
+ **Pin the version and treat a bump as breaking.** `Default/26.200.001` is contract
104
+ version 5, which changes the query syntax (`$expand=Operations($expand=Material)`
105
+ rather than `Operations/Material`) *and* the data shape (a dropdown returns an ID and a
106
+ description rather than a plain value).
107
+
108
+ There are no named entity attributes, unlike the other SDKs in the house. Acumatica's
109
+ entity set belongs to the endpoint and can be extended per instance, so a list baked
110
+ into this package would be wrong somewhere. `acumatica.entities` holds the names proven
111
+ readable on the ADi instance; the authoritative check is per endpoint:
112
+
113
+ ```
114
+ GET {base_url}/entity/{endpoint}/{version}/swagger.json
115
+ ```
116
+
117
+ ## Reading
118
+
119
+ ```python
120
+ items = client.entity("StockItem")
121
+
122
+ items.get("127-004033-001")
123
+ items.get("SO", "000123") # compound keys, in order
124
+ items.list(filter="ItemStatus eq 'Active'") # one page
125
+ items.stream(page_size=200) # every record
126
+ ```
127
+
128
+ Payloads come back exactly as Acumatica sent them, so every scalar is wrapped in
129
+ `{"value": ...}`. Flatten them when you want to:
130
+
131
+ ```python
132
+ from acumatica import unwrap
133
+
134
+ unwrap(items.get("127-004033-001")) # {"InventoryID": "127-004033-001", ...}
135
+ ```
136
+
137
+ `unwrap` leaves a field that carries anything besides `value` — such as the per-field
138
+ `error` contract version 5 adds — as a dict, because collapsing it would turn a
139
+ rejected field into a plausible-looking value.
140
+
141
+ ### Incremental sync
142
+
143
+ ```python
144
+ from datetime import UTC, datetime
145
+ from acumatica import modified_since
146
+
147
+ since = datetime(2026, 11, 17, 18, 24, 6, tzinfo=UTC)
148
+ for record in client.entity("StockItem").stream(filter=modified_since(since)):
149
+ ...
150
+ ```
151
+
152
+ Not every entity supports this. 129 of `Default`'s 735 schemas expose
153
+ `LastModifiedDateTime`; **`MANUFACTURING` exposes it on none of its 277**, and a
154
+ `$filter` on it there returns HTTP 500 rather than 400, so it reads like a server fault
155
+ rather than a bad field name. The underlying DACs do carry it, so it exists and is
156
+ simply unmapped — an endpoint extension surfaces it, and until then manufacturing
157
+ reconciles by full sweep.
158
+
159
+ ## Two ways to get the wrong data with a 200
160
+
161
+ Both are closed by the client rather than left to callers, because neither produces an
162
+ error, a bad status, or a row count anything could compare against.
163
+
164
+ **A sub-second watermark drops rows.** Acumatica compares `LastModifiedDateTime`
165
+ against a value that can sit fractionally below the one it reported. `watermark` and
166
+ `modified_since` truncate to the whole second and back off by five minutes, so the
167
+ error direction is re-reading a row rather than missing one.
168
+
169
+ **An unqualified `$select` beside `$expand` silently empties the expansion.** The
170
+ collection comes back present and empty. Requesting it raises instead:
171
+
172
+ ```python
173
+ items.list(select="InventoryID", expand="WarehouseDetails")
174
+ # ValueError: $select is set but names no field under the expanded
175
+ # 'WarehouseDetails'. Acumatica would answer 200 with 'WarehouseDetails' empty
176
+ # rather than failing.
177
+
178
+ items.list(
179
+ select=["InventoryID", "WarehouseDetails/WarehouseID"],
180
+ expand="WarehouseDetails",
181
+ )
182
+ ```
183
+
184
+ ## Rate limiting
185
+
186
+ Acumatica's licence caps three things, and the binding one is not the one that looks
187
+ binding. Measured on the TESTING tenant (tier M1 - Prime):
188
+
189
+ | constraint | value |
190
+ |---|---|
191
+ | Web Services API Users | 20 |
192
+ | Concurrent Web Services API Requests | 3 |
193
+ | Web Services API Requests per Minute | **150** |
194
+
195
+ 150/min is 2.5 req/s, so three concurrent requests stay legal only above 1.2s mean
196
+ latency. Measured latencies run 0.40–1.76s, mean around 0.8s — so the rate binds and
197
+ the concurrency limit never does. Hence a token bucket, not a semaphore.
198
+
199
+ All three are tenant-wide and shared with every other integration on the instance,
200
+ which is why the client defaults to 100/min rather than 150. The budget covers token
201
+ requests too: the System Monitor counts `/identity/` alongside `/entity/`, `/api/`,
202
+ `/soap/` and `/Webhooks/`.
203
+
204
+ ```python
205
+ client = Acumatica(..., requests_per_minute=100, burst=10)
206
+ ```
207
+
208
+ The limiter is in-process. Several Lambda containers each holding their own can still
209
+ exceed the budget between them — that case needs a rate-limited queue consumer, which
210
+ is the same conclusion the refresh-token hazard reaches.
211
+
212
+ ## Error Handling
213
+
214
+ ```python
215
+ from acumatica import Acumatica, AcumaticaError
216
+
217
+ try:
218
+ client.entity("StockItem").list()
219
+ except AcumaticaError as e:
220
+ print(e.status_code) # e.g. 403
221
+ print(str(e)) # "Acumatica API error 403: Insufficient rights to screen IN202500"
222
+ ```
223
+
224
+ A 403 names the form whose access right is missing, which is how the `ODS Integration`
225
+ role's grants were mapped. Timeouts, 429 and gateway statuses get three attempts in
226
+ total with exponential backoff; a 401 triggers one forced token refresh and one retry, then
227
+ gives up — a second 401 is a credentials problem, and retrying it burns rate budget and
228
+ risks the 20-slot API user limit.
229
+
230
+ ## Version History
231
+
232
+ See [CHANGELOG.md](CHANGELOG.md).
@@ -0,0 +1,223 @@
1
+ # Acumatica
2
+
3
+ A lightweight Python SDK for the [Acumatica](https://www.acumatica.com) contract-based
4
+ REST API, built on [`httpx`](https://www.python-httpx.org/).
5
+
6
+ Read-only. The ODS mirrors the ERP rather than driving it, and a contract-based `PUT`
7
+ creates as well as updates, so write support waits until something needs it.
8
+
9
+ ## Installation
10
+
11
+ ```bash
12
+ uv add acumatica-api
13
+ ```
14
+
15
+ ## Requirements
16
+
17
+ - Python 3.14+
18
+
19
+ ## Quick Start
20
+
21
+ ```python
22
+ from acumatica import Acumatica
23
+
24
+ with Acumatica(
25
+ "https://example.acumatica.com",
26
+ client_id="11111111-2222-3333-4444-555555555555@MyTenant",
27
+ client_secret="...",
28
+ username="ods",
29
+ password="...",
30
+ ) as client:
31
+ item = client.entity("StockItem").get("127-004033-001")
32
+ print(item["Descr"]["value"])
33
+ ```
34
+
35
+ ## Authentication
36
+
37
+ Resource Owner Password Credentials, which is the only headless flow you can actually
38
+ register. The identity server advertises `client_credentials`, but Connected
39
+ Applications (SM303010) offers only Authorization Code, Implicit, ROPC and Hybrid.
40
+
41
+ **The tenant lives in the client ID**, not in a separate parameter. The ID issued at
42
+ registration ends in `@Tenant`, and that is what scopes the session.
43
+
44
+ The client requests the `api` and `offline_access` scopes, which means Acumatica reuses
45
+ a single session ID across the whole refresh chain. Pass a `TokenStore` so that chain
46
+ survives a cold start:
47
+
48
+ ```python
49
+ from acumatica import Acumatica, TokenStore
50
+
51
+
52
+ class SecretsManagerTokenStore(TokenStore):
53
+ def load(self) -> str | None: ...
54
+ def save(self, refresh_token: str) -> None: ...
55
+
56
+
57
+ client = Acumatica(..., token_store=SecretsManagerTokenStore())
58
+ ```
59
+
60
+ > **Refresh tokens are single-use and rotate, so a persisted one is mutable shared
61
+ > state.** If several workers cold-start and refresh from the same value, one wins and
62
+ > the rest get `invalid_grant` — and a loser writing its spent token back destroys the
63
+ > chain for everyone. Prefer a single refresher: one rate-limited queue consumer rather
64
+ > than a worker per webhook notification.
65
+
66
+ By default the whole chain expires 30 days after the *initial* authentication however
67
+ often it is redeemed, unless Sliding Expiration is configured for the application on
68
+ SM303010. The client falls back to the password grant when a refresh is refused, so
69
+ this recovers without a human — but it is worth turning the setting on.
70
+
71
+ ## Endpoints
72
+
73
+ An endpoint is a contract, not a namespace, so a client is bound to one. Reading
74
+ manufacturing data alongside inventory means a second client:
75
+
76
+ ```python
77
+ default = Acumatica(creds..., endpoint="Default", version="25.200.001")
78
+ mfg = Acumatica(
79
+ creds...,
80
+ endpoint="MANUFACTURING",
81
+ version="25.100.001",
82
+ limiter=default.limiter,
83
+ session=default.session,
84
+ )
85
+ ```
86
+
87
+ **Share the limiter and the session whenever a process holds more than one
88
+ client.** The budget is tenant-wide, so two clients each pacing to 100/min spend
89
+ 200 against a cap of 150; and since both address the same instance with the same
90
+ credentials, a shared session is one token and one of the 20 API user slots rather
91
+ than two of each. `close()` ends what it was given, so close the borrower first or
92
+ let one owner do it.
93
+
94
+ **Pin the version and treat a bump as breaking.** `Default/26.200.001` is contract
95
+ version 5, which changes the query syntax (`$expand=Operations($expand=Material)`
96
+ rather than `Operations/Material`) *and* the data shape (a dropdown returns an ID and a
97
+ description rather than a plain value).
98
+
99
+ There are no named entity attributes, unlike the other SDKs in the house. Acumatica's
100
+ entity set belongs to the endpoint and can be extended per instance, so a list baked
101
+ into this package would be wrong somewhere. `acumatica.entities` holds the names proven
102
+ readable on the ADi instance; the authoritative check is per endpoint:
103
+
104
+ ```
105
+ GET {base_url}/entity/{endpoint}/{version}/swagger.json
106
+ ```
107
+
108
+ ## Reading
109
+
110
+ ```python
111
+ items = client.entity("StockItem")
112
+
113
+ items.get("127-004033-001")
114
+ items.get("SO", "000123") # compound keys, in order
115
+ items.list(filter="ItemStatus eq 'Active'") # one page
116
+ items.stream(page_size=200) # every record
117
+ ```
118
+
119
+ Payloads come back exactly as Acumatica sent them, so every scalar is wrapped in
120
+ `{"value": ...}`. Flatten them when you want to:
121
+
122
+ ```python
123
+ from acumatica import unwrap
124
+
125
+ unwrap(items.get("127-004033-001")) # {"InventoryID": "127-004033-001", ...}
126
+ ```
127
+
128
+ `unwrap` leaves a field that carries anything besides `value` — such as the per-field
129
+ `error` contract version 5 adds — as a dict, because collapsing it would turn a
130
+ rejected field into a plausible-looking value.
131
+
132
+ ### Incremental sync
133
+
134
+ ```python
135
+ from datetime import UTC, datetime
136
+ from acumatica import modified_since
137
+
138
+ since = datetime(2026, 11, 17, 18, 24, 6, tzinfo=UTC)
139
+ for record in client.entity("StockItem").stream(filter=modified_since(since)):
140
+ ...
141
+ ```
142
+
143
+ Not every entity supports this. 129 of `Default`'s 735 schemas expose
144
+ `LastModifiedDateTime`; **`MANUFACTURING` exposes it on none of its 277**, and a
145
+ `$filter` on it there returns HTTP 500 rather than 400, so it reads like a server fault
146
+ rather than a bad field name. The underlying DACs do carry it, so it exists and is
147
+ simply unmapped — an endpoint extension surfaces it, and until then manufacturing
148
+ reconciles by full sweep.
149
+
150
+ ## Two ways to get the wrong data with a 200
151
+
152
+ Both are closed by the client rather than left to callers, because neither produces an
153
+ error, a bad status, or a row count anything could compare against.
154
+
155
+ **A sub-second watermark drops rows.** Acumatica compares `LastModifiedDateTime`
156
+ against a value that can sit fractionally below the one it reported. `watermark` and
157
+ `modified_since` truncate to the whole second and back off by five minutes, so the
158
+ error direction is re-reading a row rather than missing one.
159
+
160
+ **An unqualified `$select` beside `$expand` silently empties the expansion.** The
161
+ collection comes back present and empty. Requesting it raises instead:
162
+
163
+ ```python
164
+ items.list(select="InventoryID", expand="WarehouseDetails")
165
+ # ValueError: $select is set but names no field under the expanded
166
+ # 'WarehouseDetails'. Acumatica would answer 200 with 'WarehouseDetails' empty
167
+ # rather than failing.
168
+
169
+ items.list(
170
+ select=["InventoryID", "WarehouseDetails/WarehouseID"],
171
+ expand="WarehouseDetails",
172
+ )
173
+ ```
174
+
175
+ ## Rate limiting
176
+
177
+ Acumatica's licence caps three things, and the binding one is not the one that looks
178
+ binding. Measured on the TESTING tenant (tier M1 - Prime):
179
+
180
+ | constraint | value |
181
+ |---|---|
182
+ | Web Services API Users | 20 |
183
+ | Concurrent Web Services API Requests | 3 |
184
+ | Web Services API Requests per Minute | **150** |
185
+
186
+ 150/min is 2.5 req/s, so three concurrent requests stay legal only above 1.2s mean
187
+ latency. Measured latencies run 0.40–1.76s, mean around 0.8s — so the rate binds and
188
+ the concurrency limit never does. Hence a token bucket, not a semaphore.
189
+
190
+ All three are tenant-wide and shared with every other integration on the instance,
191
+ which is why the client defaults to 100/min rather than 150. The budget covers token
192
+ requests too: the System Monitor counts `/identity/` alongside `/entity/`, `/api/`,
193
+ `/soap/` and `/Webhooks/`.
194
+
195
+ ```python
196
+ client = Acumatica(..., requests_per_minute=100, burst=10)
197
+ ```
198
+
199
+ The limiter is in-process. Several Lambda containers each holding their own can still
200
+ exceed the budget between them — that case needs a rate-limited queue consumer, which
201
+ is the same conclusion the refresh-token hazard reaches.
202
+
203
+ ## Error Handling
204
+
205
+ ```python
206
+ from acumatica import Acumatica, AcumaticaError
207
+
208
+ try:
209
+ client.entity("StockItem").list()
210
+ except AcumaticaError as e:
211
+ print(e.status_code) # e.g. 403
212
+ print(str(e)) # "Acumatica API error 403: Insufficient rights to screen IN202500"
213
+ ```
214
+
215
+ A 403 names the form whose access right is missing, which is how the `ODS Integration`
216
+ role's grants were mapped. Timeouts, 429 and gateway statuses get three attempts in
217
+ total with exponential backoff; a 401 triggers one forced token refresh and one retry, then
218
+ gives up — a second 401 is a credentials problem, and retrying it burns rate budget and
219
+ risks the 20-slot API user limit.
220
+
221
+ ## Version History
222
+
223
+ See [CHANGELOG.md](CHANGELOG.md).
@@ -0,0 +1,20 @@
1
+ """
2
+ .. include:: ../README.md
3
+ """
4
+
5
+ from acumatica.auth import AcumaticaAuthError as AcumaticaAuthError
6
+ from acumatica.auth import MemoryTokenStore as MemoryTokenStore
7
+ from acumatica.auth import TokenStore as TokenStore
8
+ from acumatica.client import DEFAULT_ENDPOINT as DEFAULT_ENDPOINT
9
+ from acumatica.client import DEFAULT_VERSION as DEFAULT_VERSION
10
+ from acumatica.client import Acumatica as Acumatica
11
+ from acumatica.endpoints.base import DEFAULT_PAGE_SIZE as DEFAULT_PAGE_SIZE
12
+ from acumatica.endpoints.base import Entity as Entity
13
+ from acumatica.entities import DEFAULT_ENTITIES as DEFAULT_ENTITIES
14
+ from acumatica.entities import MANUFACTURING_ENTITIES as MANUFACTURING_ENTITIES
15
+ from acumatica.errors import AcumaticaError as AcumaticaError
16
+ from acumatica.errors import AcumaticaRetryableError as AcumaticaRetryableError
17
+ from acumatica.ratelimit import RateLimiter as RateLimiter
18
+ from acumatica.utils import modified_since as modified_since
19
+ from acumatica.utils import unwrap as unwrap
20
+ from acumatica.utils import watermark as watermark