acumatica-api 0.1.0__py3-none-any.whl

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,13 @@
1
+ acumatica/__init__.py,sha256=Z0wAt_fNFwPlxIyPJO2Avrqzwc8hgQenDLCZ4F-gWu0,1037
2
+ acumatica/auth.py,sha256=PbO2vadaUo-e19DEXPyfLp7s3gx0X3QsZXk87TpHCKc,12456
3
+ acumatica/client.py,sha256=P4SkdAHonRDU3E6VCw2LrCZse-cFOCaoghuYHF9Xa2E,10896
4
+ acumatica/entities.py,sha256=GRRy7GtH3EOcGQt7yS-Bj-dAqtMT6eaEphR0h9Gf_UI,2698
5
+ acumatica/errors.py,sha256=QFgToOBdcn2NeqSq5EcQYdC0QXBJCl13fdeXU00WthM,584
6
+ acumatica/ratelimit.py,sha256=2prwLruJFywIzXEOXQDIY6_b97RcdhA_PIvoNFf0tXQ,3929
7
+ acumatica/utils.py,sha256=X5hcfp-Fm4tLcgd8YYaAhP8IqKZiYIajJZwezULpe5E,8145
8
+ acumatica/endpoints/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
9
+ acumatica/endpoints/base.py,sha256=yPZaQznLPOOH0G693jlcVrXxaxBzEaNHcWZEI7XaIWY,7537
10
+ acumatica_api-0.1.0.dist-info/METADATA,sha256=fAszDiS2FiuQamAjgYpHGvyOiqrzIMonNcGA09EzKTs,8443
11
+ acumatica_api-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
12
+ acumatica_api-0.1.0.dist-info/top_level.txt,sha256=5VmEJsNcf9kAOyNPulwIqjRGnDTiwENxC4j4ikQGOAk,10
13
+ acumatica_api-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1 @@
1
+ acumatica