wflow-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.
- wflow_api/__init__.py +20 -0
- wflow_api/auth.py +85 -0
- wflow_api/client.py +130 -0
- wflow_api/errors.py +13 -0
- wflow_api/guards.py +132 -0
- wflow_api/models/__init__.py +128 -0
- wflow_api/models/account.py +127 -0
- wflow_api/models/admin.py +98 -0
- wflow_api/models/common.py +117 -0
- wflow_api/models/documents.py +514 -0
- wflow_api/models/registers.py +165 -0
- wflow_api/models/requests.py +341 -0
- wflow_api/models/storage.py +38 -0
- wflow_api/operation.py +50 -0
- wflow_api/operations/__init__.py +21 -0
- wflow_api/operations/account.py +46 -0
- wflow_api/operations/admin.py +307 -0
- wflow_api/operations/approvals.py +235 -0
- wflow_api/operations/document_files.py +145 -0
- wflow_api/operations/document_properties.py +204 -0
- wflow_api/operations/document_tags.py +60 -0
- wflow_api/operations/documents.py +603 -0
- wflow_api/operations/integrations.py +63 -0
- wflow_api/operations/organization.py +51 -0
- wflow_api/operations/registers.py +2273 -0
- wflow_api/operations/storage_files.py +477 -0
- wflow_api/operations/storage_folders.py +132 -0
- wflow_api/operations/webhooks.py +67 -0
- wflow_api/py.typed +0 -0
- wflow_api-0.1.0.dist-info/METADATA +48 -0
- wflow_api-0.1.0.dist-info/RECORD +33 -0
- wflow_api-0.1.0.dist-info/WHEEL +4 -0
- wflow_api-0.1.0.dist-info/licenses/LICENSE +202 -0
|
@@ -0,0 +1,603 @@
|
|
|
1
|
+
"""Documents tag: the documents themselves, and everything hanging off one."""
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
from typing import Annotated, Any
|
|
5
|
+
|
|
6
|
+
from pydantic import Field
|
|
7
|
+
|
|
8
|
+
from wflow_api.client import WflowClient
|
|
9
|
+
from wflow_api.guards import ensure_list, path_segment, query_params, write_json, write_json_list
|
|
10
|
+
from wflow_api.models import (
|
|
11
|
+
DocumentUpdate,
|
|
12
|
+
OrgSlug,
|
|
13
|
+
Page,
|
|
14
|
+
Paged,
|
|
15
|
+
PageSize,
|
|
16
|
+
PaymentCreate,
|
|
17
|
+
Query,
|
|
18
|
+
Search,
|
|
19
|
+
Sort,
|
|
20
|
+
StructuredFilter,
|
|
21
|
+
TeamBase,
|
|
22
|
+
WriteResult,
|
|
23
|
+
)
|
|
24
|
+
from wflow_api.models.common import FileContent
|
|
25
|
+
from wflow_api.models.documents import (
|
|
26
|
+
Comment,
|
|
27
|
+
Document,
|
|
28
|
+
DocumentBase,
|
|
29
|
+
DocumentEvent,
|
|
30
|
+
DocumentType,
|
|
31
|
+
DocumentTypeFull,
|
|
32
|
+
)
|
|
33
|
+
from wflow_api.operation import operation
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
@operation
|
|
37
|
+
async def list_documents(
|
|
38
|
+
client: WflowClient,
|
|
39
|
+
organization: OrgSlug,
|
|
40
|
+
sort: Sort = None,
|
|
41
|
+
query: Query = None,
|
|
42
|
+
pageSize: PageSize = None,
|
|
43
|
+
page: Page = None,
|
|
44
|
+
) -> Paged[DocumentBase]:
|
|
45
|
+
"""Documents in the workspace — invoices, contracts, orders and cash slips.
|
|
46
|
+
|
|
47
|
+
The starting point for any question about what a workspace contains. Use `query` to
|
|
48
|
+
narrow by amount, partner, date or status; use `get_document` for the full record
|
|
49
|
+
once you have an id. Note there is no `search` argument on this endpoint.
|
|
50
|
+
|
|
51
|
+
Fields:
|
|
52
|
+
|
|
53
|
+
- `number`, `serie`, `internalCode`, `variableSymbol` — how the document is identified
|
|
54
|
+
- `issueDate`, `dueDate`, `vatDate`, `acceptDate` — the dates that drive approval
|
|
55
|
+
and payment deadlines
|
|
56
|
+
- `totalAmount`, `taxExclusiveAmount`, `currency`, `exchangeRate` — the money
|
|
57
|
+
- `partnerName`, `partnerIC`, `partnerVAT` — who it is with
|
|
58
|
+
- `approvalStatus`, `flowStatus`, `locked`, `removed` — where it is in its lifecycle
|
|
59
|
+
- `type`, `tags`, `createdBy`, `created`, `updated`
|
|
60
|
+
"""
|
|
61
|
+
payload = await client.request(
|
|
62
|
+
"GET",
|
|
63
|
+
f"/api/{organization}/documents",
|
|
64
|
+
params=query_params(sort=sort, query=query, pageSize=pageSize, page=page),
|
|
65
|
+
)
|
|
66
|
+
return Paged[DocumentBase].model_validate(payload or {})
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
@operation
|
|
70
|
+
async def get_document(client: WflowClient, organization: OrgSlug, documentId: str) -> Document:
|
|
71
|
+
"""One document in full, including its lines, VAT breakdown and accounting.
|
|
72
|
+
|
|
73
|
+
`list_documents` returns a summary; this adds the lines and the resolved register
|
|
74
|
+
records a summary only names.
|
|
75
|
+
|
|
76
|
+
Fields: beyond those on the list summary —
|
|
77
|
+
|
|
78
|
+
- `lines` — the document lines, each with description, quantity, unit price, VAT
|
|
79
|
+
and its own accounting dimensions
|
|
80
|
+
- `vaTs` — the VAT breakdown per rate
|
|
81
|
+
- `accounting` — how the document is posted
|
|
82
|
+
- `partner`, `deliveryLocation` — the resolved register records; the list summary
|
|
83
|
+
carries only the names copied onto the document
|
|
84
|
+
|
|
85
|
+
Already on the list summary, not new here: `serie` (also a resolved record, not a
|
|
86
|
+
string), `payment`, `series` (a deprecated code, distinct from `serie`), `source`
|
|
87
|
+
and `dataSource`.
|
|
88
|
+
"""
|
|
89
|
+
return Document.model_validate(
|
|
90
|
+
await client.request("GET", f"/api/{organization}/documents/{path_segment(documentId)}") or {}
|
|
91
|
+
)
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
@operation
|
|
95
|
+
async def get_document_metadata(client: WflowClient, organization: OrgSlug, documentId: str) -> dict[str, Any]:
|
|
96
|
+
"""Raw extraction metadata for a document — what wflow read off the source file.
|
|
97
|
+
|
|
98
|
+
Returned untyped on purpose: the spec describes the response only as "Metadata as
|
|
99
|
+
JSON string" and publishes no schema for it, so the shape is whatever wflow sends —
|
|
100
|
+
including, per that description, a JSON-encoded string rather than an object, which
|
|
101
|
+
this operation decodes for you. Treat the keys as unstable.
|
|
102
|
+
|
|
103
|
+
Fields: undocumented upstream. Inspect what comes back rather than assuming.
|
|
104
|
+
"""
|
|
105
|
+
payload = await client.request("GET", f"/api/{organization}/documents/{path_segment(documentId)}/metadata") or {}
|
|
106
|
+
# The spec calls this "Metadata as JSON string", so it may arrive double-encoded.
|
|
107
|
+
if isinstance(payload, str):
|
|
108
|
+
try:
|
|
109
|
+
payload = json.loads(payload)
|
|
110
|
+
except ValueError:
|
|
111
|
+
return {"metadata": payload}
|
|
112
|
+
return payload if isinstance(payload, dict) else {"metadata": payload}
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
@operation
|
|
116
|
+
async def list_document_events(client: WflowClient, organization: OrgSlug, documentId: str) -> list[DocumentEvent]:
|
|
117
|
+
"""The audit trail of one document — every change, approval and file event, in order.
|
|
118
|
+
|
|
119
|
+
Read this to reconstruct what happened to a document and who did it, rather than
|
|
120
|
+
just its current state.
|
|
121
|
+
|
|
122
|
+
Fields:
|
|
123
|
+
|
|
124
|
+
- `type` — e.g. Create, Update, Approved, Rejected, FileAdded, ChangedFlowStatus
|
|
125
|
+
- `identity` — who triggered the event, when known
|
|
126
|
+
- `info` — free-text detail
|
|
127
|
+
- `created` — when it happened
|
|
128
|
+
"""
|
|
129
|
+
payload = await client.request("GET", f"/api/{organization}/documents/{path_segment(documentId)}/events") or []
|
|
130
|
+
return [DocumentEvent.model_validate(item) for item in payload]
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
@operation
|
|
134
|
+
async def list_documents_to_export(
|
|
135
|
+
client: WflowClient, organization: OrgSlug, typeId: str | None = None, exclude: bool | None = None
|
|
136
|
+
) -> list[str]:
|
|
137
|
+
"""Ids of documents ready to export to an ERP or accounting system.
|
|
138
|
+
|
|
139
|
+
Fields: a bare array of document ids, in no typed shape to model.
|
|
140
|
+
|
|
141
|
+
- `typeId` — restrict to one document type
|
|
142
|
+
- `exclude` — when true, ignore the document type's own "exclude from standard
|
|
143
|
+
integration into ERP" setting and return everything otherwise ready
|
|
144
|
+
"""
|
|
145
|
+
path = f"/api/{organization}/documents/toexport"
|
|
146
|
+
payload = await client.request("GET", path, params=query_params(typeId=typeId, exclude=exclude)) or []
|
|
147
|
+
return ensure_list(path, payload)
|
|
148
|
+
|
|
149
|
+
|
|
150
|
+
@operation
|
|
151
|
+
async def list_documents_to_extract(client: WflowClient, organization: OrgSlug) -> list[str]:
|
|
152
|
+
"""Ids of documents queued for data extraction from their source file.
|
|
153
|
+
|
|
154
|
+
Fields: a bare array of document ids, in no typed shape to model.
|
|
155
|
+
"""
|
|
156
|
+
path = f"/api/{organization}/documents/toextract"
|
|
157
|
+
payload = await client.request("GET", path) or []
|
|
158
|
+
return ensure_list(path, payload)
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
@operation
|
|
162
|
+
async def list_document_comments(client: WflowClient, organization: OrgSlug, documentId: str) -> list[Comment]:
|
|
163
|
+
"""The comment thread on one document.
|
|
164
|
+
|
|
165
|
+
Fields:
|
|
166
|
+
|
|
167
|
+
- `author` — who wrote it
|
|
168
|
+
- `text`, `markdown` — the comment content, plain and formatted
|
|
169
|
+
- `created`, `updated`, `removed`
|
|
170
|
+
- `teams` — which teams the comment is visible to, and whether each has resolved it
|
|
171
|
+
"""
|
|
172
|
+
payload = await client.request("GET", f"/api/{organization}/documents/{path_segment(documentId)}/comments") or []
|
|
173
|
+
return [Comment.model_validate(item) for item in payload]
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
@operation
|
|
177
|
+
async def list_document_links(client: WflowClient, organization: OrgSlug, documentId: str) -> list[DocumentBase]:
|
|
178
|
+
"""Other documents linked to this one, e.g. an order linked to the invoice it produced.
|
|
179
|
+
|
|
180
|
+
Each item is a full document summary, the same shape `list_documents` returns, not
|
|
181
|
+
just an id — use it directly rather than following up with `get_document`. `created`
|
|
182
|
+
and `updated` are null on these summaries; `get_document` has them.
|
|
183
|
+
|
|
184
|
+
Fields: see `list_documents`.
|
|
185
|
+
"""
|
|
186
|
+
payload = await client.request("GET", f"/api/{organization}/documents/{path_segment(documentId)}/links") or []
|
|
187
|
+
return [DocumentBase.model_validate(item) for item in payload]
|
|
188
|
+
|
|
189
|
+
|
|
190
|
+
@operation
|
|
191
|
+
async def get_document_rights(client: WflowClient, organization: OrgSlug, documentId: str) -> list[TeamBase]:
|
|
192
|
+
"""The teams allowed to see and act on one document.
|
|
193
|
+
|
|
194
|
+
Fields:
|
|
195
|
+
|
|
196
|
+
- `name`, `description` — the team as shown in wflow
|
|
197
|
+
- `system` — true for a built-in team rather than one the organization created
|
|
198
|
+
"""
|
|
199
|
+
payload = await client.request("GET", f"/api/{organization}/documents/{path_segment(documentId)}/rights") or []
|
|
200
|
+
return [TeamBase.model_validate(item) for item in payload]
|
|
201
|
+
|
|
202
|
+
|
|
203
|
+
@operation
|
|
204
|
+
async def get_document_type(client: WflowClient, organization: OrgSlug, typeId: str) -> DocumentTypeFull:
|
|
205
|
+
"""One document type in full, including who has access to it.
|
|
206
|
+
|
|
207
|
+
`list_document_types` returns the summary; this adds the per-user permissions.
|
|
208
|
+
|
|
209
|
+
Fields: beyond those on the list summary —
|
|
210
|
+
|
|
211
|
+
- `users` — each user granted access, and their permission: All, OnlyAssigned
|
|
212
|
+
or FullAccess
|
|
213
|
+
"""
|
|
214
|
+
# The published path segment is literal, not a parameter; typeId is a query argument.
|
|
215
|
+
payload = await client.request(
|
|
216
|
+
"GET", f"/api/{organization}/documents/types/typeid:guid", params=query_params(typeId=typeId)
|
|
217
|
+
)
|
|
218
|
+
return DocumentTypeFull.model_validate(payload or {})
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
@operation
|
|
222
|
+
async def list_document_types(
|
|
223
|
+
client: WflowClient,
|
|
224
|
+
organization: OrgSlug,
|
|
225
|
+
search: Search = None,
|
|
226
|
+
sort: Sort = None,
|
|
227
|
+
query: Query = None,
|
|
228
|
+
pageSize: PageSize = None,
|
|
229
|
+
page: Page = None,
|
|
230
|
+
) -> Paged[DocumentType]:
|
|
231
|
+
"""Document types configured in the workspace — the kinds a document may be filed as.
|
|
232
|
+
|
|
233
|
+
Look here to learn which numbering series and sequence a type uses before assigning
|
|
234
|
+
it, or to resolve the `type` field seen on a document. For one type's full detail,
|
|
235
|
+
including who may use it, follow up with `get_document_type`.
|
|
236
|
+
|
|
237
|
+
Fields:
|
|
238
|
+
|
|
239
|
+
- `name`, `kind` — the type as shown in wflow, and the document kind it applies to
|
|
240
|
+
- `default` — used automatically when a document arrives with no type set
|
|
241
|
+
- `erpExclude` — excluded from standard integration into an ERP
|
|
242
|
+
- `docCreatingMethod` — Upload or Manually
|
|
243
|
+
- `autoStamp` — when wflow time-stamps a file of this type: None, New or Approved
|
|
244
|
+
- `serie`, `sequence` — the numbering series and counter this type draws on
|
|
245
|
+
- `invoiceType` — TaxInvoice, CreditNote, DebitNote, Proforma or TaxInvoicePayment
|
|
246
|
+
"""
|
|
247
|
+
payload = (
|
|
248
|
+
await client.request(
|
|
249
|
+
"GET",
|
|
250
|
+
f"/api/{organization}/documents/types",
|
|
251
|
+
params=query_params(search=search, sort=sort, query=query, pageSize=pageSize, page=page),
|
|
252
|
+
)
|
|
253
|
+
or {}
|
|
254
|
+
)
|
|
255
|
+
return Paged[DocumentType].model_validate(payload)
|
|
256
|
+
|
|
257
|
+
|
|
258
|
+
@operation
|
|
259
|
+
async def delete_document(client: WflowClient, organization: OrgSlug, documentId: str) -> WriteResult:
|
|
260
|
+
"""Delete one document, with everything attached to it.
|
|
261
|
+
|
|
262
|
+
Its files, comments, properties and approval history go with it, and wflow keeps no
|
|
263
|
+
version history to restore it from. Read `get_document` first if you are not certain
|
|
264
|
+
which document the id refers to.
|
|
265
|
+
|
|
266
|
+
Fields: on the result —
|
|
267
|
+
|
|
268
|
+
- `action` — "deleted"
|
|
269
|
+
- `resource` — "documents"
|
|
270
|
+
"""
|
|
271
|
+
await client.request("DELETE", f"/api/{organization}/documents/{path_segment(documentId)}")
|
|
272
|
+
return WriteResult(action="deleted", resource="documents")
|
|
273
|
+
|
|
274
|
+
|
|
275
|
+
@operation
|
|
276
|
+
async def unlink_document(
|
|
277
|
+
client: WflowClient, organization: OrgSlug, documentId: str, linkedDocumentId: str
|
|
278
|
+
) -> WriteResult:
|
|
279
|
+
"""Remove the link between two documents, leaving both documents in place.
|
|
280
|
+
|
|
281
|
+
Only the association goes. `list_document_links` returns the documents currently
|
|
282
|
+
linked to `documentId`, each as a full summary, so take `linkedDocumentId` from its
|
|
283
|
+
`id`.
|
|
284
|
+
|
|
285
|
+
Fields: on the result —
|
|
286
|
+
|
|
287
|
+
- `action` — "deleted"
|
|
288
|
+
- `resource` — "documents/links"
|
|
289
|
+
"""
|
|
290
|
+
await client.request(
|
|
291
|
+
"DELETE", f"/api/{organization}/documents/{path_segment(documentId)}/links/{path_segment(linkedDocumentId)}"
|
|
292
|
+
)
|
|
293
|
+
return WriteResult(action="deleted", resource="documents/links")
|
|
294
|
+
|
|
295
|
+
|
|
296
|
+
@operation
|
|
297
|
+
async def delete_document_type(client: WflowClient, organization: OrgSlug, typeId: str) -> WriteResult:
|
|
298
|
+
"""Delete one of the workspace's document types.
|
|
299
|
+
|
|
300
|
+
A type is workspace configuration shared by every document filed as it, not a
|
|
301
|
+
property of one document, so this reaches further than the id suggests. Get the id
|
|
302
|
+
from `list_document_types`.
|
|
303
|
+
|
|
304
|
+
Fields: on the result —
|
|
305
|
+
|
|
306
|
+
- `action` — "deleted"
|
|
307
|
+
- `resource` — "documents/types"
|
|
308
|
+
"""
|
|
309
|
+
# The published path segment is literal, not a parameter; typeId is a query argument.
|
|
310
|
+
await client.request(
|
|
311
|
+
"DELETE", f"/api/{organization}/documents/types/typeid:guid", params=query_params(typeId=typeId)
|
|
312
|
+
)
|
|
313
|
+
return WriteResult(action="deleted", resource="documents/types")
|
|
314
|
+
|
|
315
|
+
|
|
316
|
+
@operation
|
|
317
|
+
async def lock_document(client: WflowClient, organization: OrgSlug, documentId: str, value: bool) -> WriteResult:
|
|
318
|
+
"""Lock or unlock a document, so it cannot be changed while someone works on it.
|
|
319
|
+
|
|
320
|
+
Pass `value` true to lock, false to release. A locked document rejects writes until
|
|
321
|
+
it is unlocked; `update_document` can override that with `ignoreLock`.
|
|
322
|
+
`list_documents` reports the current state as `locked`.
|
|
323
|
+
|
|
324
|
+
Fields: on the result —
|
|
325
|
+
|
|
326
|
+
- `action` — "locked" or "unlocked"
|
|
327
|
+
- `resource` — "documents/lock"
|
|
328
|
+
"""
|
|
329
|
+
await client.request("PUT", f"/api/{organization}/documents/{path_segment(documentId)}/lock/{str(value).lower()}")
|
|
330
|
+
return WriteResult(action="locked" if value else "unlocked", resource="documents/lock")
|
|
331
|
+
|
|
332
|
+
|
|
333
|
+
@operation
|
|
334
|
+
async def link_document(
|
|
335
|
+
client: WflowClient, organization: OrgSlug, documentId: str, linkedDocumentId: str
|
|
336
|
+
) -> WriteResult:
|
|
337
|
+
"""Link one document to another, e.g. an order to the invoice it produced.
|
|
338
|
+
|
|
339
|
+
Only the association is created; both documents stay as they are.
|
|
340
|
+
`list_document_links` then returns the linked document among `documentId`'s links,
|
|
341
|
+
and `unlink_document` takes the link off again.
|
|
342
|
+
|
|
343
|
+
Fields: on the result —
|
|
344
|
+
|
|
345
|
+
- `action` — "linked"
|
|
346
|
+
- `resource` — "documents/links"
|
|
347
|
+
"""
|
|
348
|
+
await client.request(
|
|
349
|
+
"PUT", f"/api/{organization}/documents/{path_segment(documentId)}/links/{path_segment(linkedDocumentId)}"
|
|
350
|
+
)
|
|
351
|
+
return WriteResult(action="linked", resource="documents/links")
|
|
352
|
+
|
|
353
|
+
|
|
354
|
+
@operation
|
|
355
|
+
async def create_document_task(client: WflowClient, organization: OrgSlug, documentId: str, type: str) -> WriteResult:
|
|
356
|
+
"""Queue work on a document — extracting its data, or exporting it onward.
|
|
357
|
+
|
|
358
|
+
`type` is "Extract" or "Export"; another value is rejected outright. The task is
|
|
359
|
+
queued rather than run here — `list_documents_to_extract` and
|
|
360
|
+
`list_documents_to_export` list the documents waiting, and whatever performs the
|
|
361
|
+
work closes the task with `set_document_task_processed`. An Export task closed with
|
|
362
|
+
`success` true moves the document on in its workflow (e.g. from SentToReview to
|
|
363
|
+
SentToERP), which is permanent: nothing moves it back.
|
|
364
|
+
|
|
365
|
+
Fields: on the result —
|
|
366
|
+
|
|
367
|
+
- `action` — "created"
|
|
368
|
+
- `resource` — "documents/task"
|
|
369
|
+
"""
|
|
370
|
+
await client.request("POST", f"/api/{organization}/documents/{path_segment(documentId)}/task/{path_segment(type)}")
|
|
371
|
+
return WriteResult(action="created", resource="documents/task")
|
|
372
|
+
|
|
373
|
+
|
|
374
|
+
@operation
|
|
375
|
+
async def set_document_task_processed(
|
|
376
|
+
client: WflowClient, organization: OrgSlug, documentId: str, taskType: str, success: bool
|
|
377
|
+
) -> WriteResult:
|
|
378
|
+
"""Record that a document task has been dealt with, and whether it worked.
|
|
379
|
+
|
|
380
|
+
This is the other half of `create_document_task`: `taskType` is "Extract" or
|
|
381
|
+
"Export", and `success` false records a failed attempt rather than leaving the
|
|
382
|
+
document queued. Send it from whatever performed the work. Closing an Export task
|
|
383
|
+
with `success` true moves the document on in its workflow (e.g. from SentToReview to
|
|
384
|
+
SentToERP), which is permanent: nothing moves it back.
|
|
385
|
+
|
|
386
|
+
Fields: on the result —
|
|
387
|
+
|
|
388
|
+
- `action` — "processed"
|
|
389
|
+
- `resource` — "documents/task"
|
|
390
|
+
"""
|
|
391
|
+
await client.request(
|
|
392
|
+
"PUT",
|
|
393
|
+
f"/api/{organization}/documents/{path_segment(documentId)}/task/{path_segment(taskType)}/processed",
|
|
394
|
+
params=query_params(success=success),
|
|
395
|
+
)
|
|
396
|
+
return WriteResult(action="processed", resource="documents/task")
|
|
397
|
+
|
|
398
|
+
|
|
399
|
+
@operation
|
|
400
|
+
async def update_document(
|
|
401
|
+
client: WflowClient,
|
|
402
|
+
organization: OrgSlug,
|
|
403
|
+
document: DocumentUpdate,
|
|
404
|
+
externalId: Annotated[
|
|
405
|
+
str | None, Field(default=None, description="Match an existing document by your ERP's id")
|
|
406
|
+
] = None,
|
|
407
|
+
ignoreLock: Annotated[bool | None, Field(default=None, description="Write even if the document is locked")] = None,
|
|
408
|
+
setAsFilled: Annotated[bool | None, Field(default=None, description="Mark the document as fully filled in")] = None,
|
|
409
|
+
) -> WriteResult:
|
|
410
|
+
"""Create a document, or replace an existing one's contents.
|
|
411
|
+
|
|
412
|
+
Matched by the `id` inside `document`, or by the `externalId` argument when
|
|
413
|
+
reconciling against an ERP. Send the full record: do not rely on a field you leave
|
|
414
|
+
out being kept, and `lines` and `vaTs` are whole lists regardless, so a line you omit
|
|
415
|
+
is gone. `get_document` returns the record in full — read it first when
|
|
416
|
+
changing a document that exists, and send back the fields this operation declares rather
|
|
417
|
+
than the whole read, which also carries the status, timestamps and resolved register
|
|
418
|
+
records that only a read has. `ignoreLock` overrides a lock set by `lock_document`.
|
|
419
|
+
|
|
420
|
+
Fields: on the result —
|
|
421
|
+
|
|
422
|
+
- `action` — "updated"
|
|
423
|
+
- `resource` — "documents"
|
|
424
|
+
- `id` — the document's id, which wflow returns for this endpoint
|
|
425
|
+
"""
|
|
426
|
+
created = await client.request(
|
|
427
|
+
"PUT",
|
|
428
|
+
f"/api/{organization}/documents",
|
|
429
|
+
params=query_params(externalId=externalId, ignoreLock=ignoreLock, setAsFilled=setAsFilled),
|
|
430
|
+
json=write_json(document),
|
|
431
|
+
)
|
|
432
|
+
return WriteResult(action="updated", resource="documents", id=created)
|
|
433
|
+
|
|
434
|
+
|
|
435
|
+
@operation
|
|
436
|
+
async def update_document_metadata(
|
|
437
|
+
client: WflowClient, organization: OrgSlug, documentId: str, metadata: str
|
|
438
|
+
) -> WriteResult:
|
|
439
|
+
"""Replace the extraction metadata wflow holds for one document.
|
|
440
|
+
|
|
441
|
+
`metadata` is a string, not an object: it travels as a JSON string body, so pass JSON
|
|
442
|
+
already encoded and wflow stores the text you gave. It replaces the whole blob rather
|
|
443
|
+
than merging into it, and wflow keeps no version history, so read
|
|
444
|
+
`get_document_metadata` first if any of what is there matters.
|
|
445
|
+
|
|
446
|
+
Fields: on the result —
|
|
447
|
+
|
|
448
|
+
- `action` — "updated"
|
|
449
|
+
- `resource` — "documents/metadata"
|
|
450
|
+
"""
|
|
451
|
+
await client.request("PUT", f"/api/{organization}/documents/{path_segment(documentId)}/metadata", json=metadata)
|
|
452
|
+
return WriteResult(action="updated", resource="documents/metadata")
|
|
453
|
+
|
|
454
|
+
|
|
455
|
+
@operation
|
|
456
|
+
async def update_document_payments(
|
|
457
|
+
client: WflowClient, organization: OrgSlug, documentId: str, payments: list[PaymentCreate]
|
|
458
|
+
) -> WriteResult:
|
|
459
|
+
"""Replace the payments recorded against one document.
|
|
460
|
+
|
|
461
|
+
The list you send becomes the document's payments, so a payment you leave out is
|
|
462
|
+
gone. wflow publishes no read for the individual payments — `get_document`'s
|
|
463
|
+
`payment` is a rollup of paid amount, date and status — so nothing can reconstruct
|
|
464
|
+
what a partial payload dropped. Send every payment you mean to keep.
|
|
465
|
+
|
|
466
|
+
Fields: on the result —
|
|
467
|
+
|
|
468
|
+
- `action` — "updated"
|
|
469
|
+
- `resource` — "documents/payments"
|
|
470
|
+
"""
|
|
471
|
+
await client.request(
|
|
472
|
+
"PUT",
|
|
473
|
+
f"/api/{organization}/documents/{path_segment(documentId)}/payments",
|
|
474
|
+
json=write_json_list(payments),
|
|
475
|
+
)
|
|
476
|
+
return WriteResult(action="updated", resource="documents/payments")
|
|
477
|
+
|
|
478
|
+
|
|
479
|
+
@operation
|
|
480
|
+
async def update_document_type(
|
|
481
|
+
client: WflowClient, organization: OrgSlug, documentType: DocumentTypeFull
|
|
482
|
+
) -> WriteResult:
|
|
483
|
+
"""Create a document type, or replace an existing one's configuration.
|
|
484
|
+
|
|
485
|
+
A type is workspace configuration shared by every document filed as it, not a
|
|
486
|
+
property of one document. Matched by the `id` inside `documentType`; the submitted
|
|
487
|
+
object replaces the stored type, so a field you leave out can be cleared, and `users`
|
|
488
|
+
is a whole set — a user you omit loses access to the type and to every document filed
|
|
489
|
+
as it. That includes you: leave the caller (`id` from `get_me`) out of `users`
|
|
490
|
+
and `create_document_with_files` refuses to file anything as this type, because the
|
|
491
|
+
caller no longer has access to it. `get_document_type` returns it in full,
|
|
492
|
+
`users` included; read it first when changing a type that exists.
|
|
493
|
+
|
|
494
|
+
Fields: on the result —
|
|
495
|
+
|
|
496
|
+
- `action` — "updated"
|
|
497
|
+
- `resource` — "documents/types"
|
|
498
|
+
- `id` — the document type's id
|
|
499
|
+
"""
|
|
500
|
+
created = await client.request(
|
|
501
|
+
"PUT",
|
|
502
|
+
f"/api/{organization}/documents/types",
|
|
503
|
+
json=write_json(documentType),
|
|
504
|
+
)
|
|
505
|
+
return WriteResult(action="updated", resource="documents/types", id=created)
|
|
506
|
+
|
|
507
|
+
|
|
508
|
+
@operation
|
|
509
|
+
async def set_document_rights(
|
|
510
|
+
client: WflowClient, organization: OrgSlug, documentId: str, teams: list[TeamBase]
|
|
511
|
+
) -> WriteResult:
|
|
512
|
+
"""Replace the set of teams allowed to see and act on one document.
|
|
513
|
+
|
|
514
|
+
The list you send becomes the document's rights, so a team you leave out loses
|
|
515
|
+
access, and an empty list leaves the document visible to nobody but full-access
|
|
516
|
+
users. `get_document_rights` returns every team currently allowed, in one array —
|
|
517
|
+
read it first and send its records straight back, minus the ones you are removing.
|
|
518
|
+
A team is matched by `id`, which `list_teams` also returns.
|
|
519
|
+
|
|
520
|
+
Fields: on the result —
|
|
521
|
+
|
|
522
|
+
- `action` — "updated"
|
|
523
|
+
- `resource` — "documents/rights"
|
|
524
|
+
"""
|
|
525
|
+
await client.request(
|
|
526
|
+
"PUT",
|
|
527
|
+
f"/api/{organization}/documents/{path_segment(documentId)}/rights",
|
|
528
|
+
json=write_json_list(teams, allow_empty=True),
|
|
529
|
+
)
|
|
530
|
+
return WriteResult(action="updated", resource="documents/rights")
|
|
531
|
+
|
|
532
|
+
|
|
533
|
+
@operation
|
|
534
|
+
async def create_document_with_files(
|
|
535
|
+
client: WflowClient,
|
|
536
|
+
organization: OrgSlug,
|
|
537
|
+
filename: str,
|
|
538
|
+
content: bytes,
|
|
539
|
+
typeId: Annotated[str | None, Field(default=None, description="Document type to file it under")] = None,
|
|
540
|
+
invoiceType: Annotated[
|
|
541
|
+
str | None,
|
|
542
|
+
Field(default=None, description="TaxInvoice, CreditNote, DebitNote, Proforma or TaxInvoicePayment"),
|
|
543
|
+
] = None,
|
|
544
|
+
) -> WriteResult:
|
|
545
|
+
"""Create a document from a file: its bytes, and the `filename` wflow should store it under.
|
|
546
|
+
|
|
547
|
+
This is how a scan becomes a document: wflow files it under `typeId`, which
|
|
548
|
+
`list_document_types` names, and reads what it can out of the file itself — an ISDOC,
|
|
549
|
+
or the QR receipt on a Slovak one — into the new document's fields. It sends one file
|
|
550
|
+
per call and hands back no document id, so to attach anything further, find the new
|
|
551
|
+
document with `list_documents` — `sort` of "created desc" puts it first — and pass its
|
|
552
|
+
id to `upload_document_file`. A refusal for lack of access to the document type means
|
|
553
|
+
the caller is not in that type's `users`, which `get_document_type` lists.
|
|
554
|
+
|
|
555
|
+
Fields: on the result —
|
|
556
|
+
|
|
557
|
+
- `action` — "created"
|
|
558
|
+
- `resource` — "documents/withfiles"
|
|
559
|
+
"""
|
|
560
|
+
await client.upload(
|
|
561
|
+
"POST",
|
|
562
|
+
f"/api/{organization}/documents/withfiles",
|
|
563
|
+
filename,
|
|
564
|
+
content,
|
|
565
|
+
params=query_params(typeId=typeId, invoiceType=invoiceType),
|
|
566
|
+
field="uploadedFiles",
|
|
567
|
+
)
|
|
568
|
+
return WriteResult(action="created", resource="documents/withfiles")
|
|
569
|
+
|
|
570
|
+
|
|
571
|
+
@operation
|
|
572
|
+
async def export_documents(
|
|
573
|
+
client: WflowClient,
|
|
574
|
+
organization: OrgSlug,
|
|
575
|
+
format: str,
|
|
576
|
+
filter: StructuredFilter,
|
|
577
|
+
*,
|
|
578
|
+
max_bytes: int | None = None,
|
|
579
|
+
) -> FileContent:
|
|
580
|
+
"""Export a set of documents as one file, in an accounting system's own format.
|
|
581
|
+
|
|
582
|
+
`format` is one of "byznyssolitea", "datev", "excel", "generic", "isdoc", "kros",
|
|
583
|
+
"moneyerp", "moneys3", "mrp", "premier" or "xml"; another value is rejected outright.
|
|
584
|
+
`filter` chooses which documents go in — `filters` per column, `propertyFilters` per
|
|
585
|
+
custom property, `search` as free text — and **`sort` is required**: pass something
|
|
586
|
+
like "number asc", because wflow fails the export without it, an empty `filter`
|
|
587
|
+
object included. The other three are optional and default to no restriction.
|
|
588
|
+
|
|
589
|
+
wflow streams the export file itself, whatever the format, and it comes back as its own
|
|
590
|
+
bytes. With `max_bytes` set, a larger export is refused rather than truncated.
|
|
591
|
+
|
|
592
|
+
Fields:
|
|
593
|
+
|
|
594
|
+
- `filename` — whatever wflow's Content-Disposition names, when it sends one
|
|
595
|
+
- `content_type` — the MIME type wflow gave the export
|
|
596
|
+
- `content` — the export's bytes
|
|
597
|
+
"""
|
|
598
|
+
return await client.download(
|
|
599
|
+
f"/api/{organization}/documents/export/{path_segment(format)}",
|
|
600
|
+
"POST",
|
|
601
|
+
json=write_json(filter.with_empty_restrictions()),
|
|
602
|
+
max_bytes=max_bytes,
|
|
603
|
+
)
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
"""Integrations tag: minting an API client, and what one is allowed to do in a workspace."""
|
|
2
|
+
|
|
3
|
+
from typing import Annotated
|
|
4
|
+
|
|
5
|
+
from pydantic import Field
|
|
6
|
+
|
|
7
|
+
from wflow_api.client import WflowClient
|
|
8
|
+
from wflow_api.guards import query_params
|
|
9
|
+
from wflow_api.models import ApiClientResult, OrgSlug, WriteResult
|
|
10
|
+
from wflow_api.operation import operation
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
@operation
|
|
14
|
+
async def allow_integration(client: WflowClient, organization: OrgSlug) -> WriteResult:
|
|
15
|
+
"""Allow the calling client to integrate with this workspace.
|
|
16
|
+
|
|
17
|
+
wflow applies it to the client the request is authenticated as: there is nothing to
|
|
18
|
+
name, and it cannot grant access to a different one. `organization` is the only
|
|
19
|
+
choice being made here, so check it is the workspace you mean.
|
|
20
|
+
|
|
21
|
+
Fields: on the result —
|
|
22
|
+
|
|
23
|
+
- `action` — "allowed"
|
|
24
|
+
- `resource` — "integrations/allow"
|
|
25
|
+
"""
|
|
26
|
+
await client.request("PUT", f"/api/{organization}/integrations/allow")
|
|
27
|
+
return WriteResult(action="allowed", resource="integrations/allow")
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
@operation
|
|
31
|
+
async def create_api_client(
|
|
32
|
+
client: WflowClient,
|
|
33
|
+
organization: OrgSlug,
|
|
34
|
+
name: str,
|
|
35
|
+
sufix: Annotated[
|
|
36
|
+
str | None, Field(default=None, description="Suffix appended to the generated client name")
|
|
37
|
+
] = None,
|
|
38
|
+
alwaysAllow: Annotated[
|
|
39
|
+
bool | None,
|
|
40
|
+
Field(default=None, description="Create it already allowed, so it needs no allow_integration call"),
|
|
41
|
+
] = None,
|
|
42
|
+
) -> ApiClientResult:
|
|
43
|
+
"""Mint a machine-to-machine API client for this workspace.
|
|
44
|
+
|
|
45
|
+
**The result contains a client secret, shown once and never again.** Hand it to the
|
|
46
|
+
person who asked for it and do not repeat it in a summary, a commit message or a
|
|
47
|
+
file. If it is lost, the client has to be created again.
|
|
48
|
+
|
|
49
|
+
This is a `client_credentials` pair for a customer's own integration. It is not an
|
|
50
|
+
`authorization_code` client for an interactive application — those have to be
|
|
51
|
+
requested from the wflow identity administrators.
|
|
52
|
+
|
|
53
|
+
Fields: on the result —
|
|
54
|
+
|
|
55
|
+
- `id` — the generated client id
|
|
56
|
+
- `secret` — the client secret, shown only here
|
|
57
|
+
"""
|
|
58
|
+
payload = await client.request(
|
|
59
|
+
"POST",
|
|
60
|
+
f"/api/{organization}/integrations/apiclient",
|
|
61
|
+
params=query_params(name=name, sufix=sufix, alwaysAllow=alwaysAllow),
|
|
62
|
+
)
|
|
63
|
+
return ApiClientResult.model_validate(payload or {})
|