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.
- acumatica/__init__.py +20 -0
- acumatica/auth.py +318 -0
- acumatica/client.py +284 -0
- acumatica/endpoints/__init__.py +0 -0
- acumatica/endpoints/base.py +191 -0
- acumatica/entities.py +88 -0
- acumatica/errors.py +21 -0
- acumatica/ratelimit.py +106 -0
- acumatica/utils.py +206 -0
- acumatica_api-0.1.0.dist-info/METADATA +232 -0
- acumatica_api-0.1.0.dist-info/RECORD +13 -0
- acumatica_api-0.1.0.dist-info/WHEEL +5 -0
- acumatica_api-0.1.0.dist-info/top_level.txt +1 -0
|
@@ -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 @@
|
|
|
1
|
+
acumatica
|