@epostak/sdk 1.0.0
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.
- package/README.md +632 -0
- package/dist/client.d.ts +61 -0
- package/dist/client.d.ts.map +1 -0
- package/dist/client.js +67 -0
- package/dist/client.js.map +1 -0
- package/dist/index.d.ts +12 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +13 -0
- package/dist/index.js.map +1 -0
- package/dist/resources/account.d.ts +6 -0
- package/dist/resources/account.d.ts.map +1 -0
- package/dist/resources/account.js +7 -0
- package/dist/resources/account.js.map +1 -0
- package/dist/resources/documents.d.ts +26 -0
- package/dist/resources/documents.d.ts.map +1 -0
- package/dist/resources/documents.js +70 -0
- package/dist/resources/documents.js.map +1 -0
- package/dist/resources/extract.d.ts +11 -0
- package/dist/resources/extract.d.ts.map +1 -0
- package/dist/resources/extract.js +18 -0
- package/dist/resources/extract.js.map +1 -0
- package/dist/resources/firms.d.ts +14 -0
- package/dist/resources/firms.d.ts.map +1 -0
- package/dist/resources/firms.js +27 -0
- package/dist/resources/firms.js.map +1 -0
- package/dist/resources/peppol.d.ts +14 -0
- package/dist/resources/peppol.d.ts.map +1 -0
- package/dist/resources/peppol.js +26 -0
- package/dist/resources/peppol.js.map +1 -0
- package/dist/resources/reporting.d.ts +6 -0
- package/dist/resources/reporting.d.ts.map +1 -0
- package/dist/resources/reporting.js +10 -0
- package/dist/resources/reporting.js.map +1 -0
- package/dist/resources/webhooks.d.ts +25 -0
- package/dist/resources/webhooks.d.ts.map +1 -0
- package/dist/resources/webhooks.js +49 -0
- package/dist/resources/webhooks.js.map +1 -0
- package/dist/types.d.ts +473 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +5 -0
- package/dist/types.js.map +1 -0
- package/dist/utils/errors.d.ts +13 -0
- package/dist/utils/errors.d.ts.map +1 -0
- package/dist/utils/errors.js +32 -0
- package/dist/utils/errors.js.map +1 -0
- package/dist/utils/request.d.ts +28 -0
- package/dist/utils/request.d.ts.map +1 -0
- package/dist/utils/request.js +79 -0
- package/dist/utils/request.js.map +1 -0
- package/package.json +38 -0
package/README.md
ADDED
|
@@ -0,0 +1,632 @@
|
|
|
1
|
+
# @epostak/sdk
|
|
2
|
+
|
|
3
|
+
Official Node.js / TypeScript SDK for the [ePošťák Enterprise API](https://epostak.sk/api/docs/enterprise) — Peppol e-invoicing for Slovakia and the EU.
|
|
4
|
+
|
|
5
|
+
Zero runtime dependencies. Requires Node.js 18+.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Installation
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install @epostak/sdk
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## Quick start
|
|
18
|
+
|
|
19
|
+
```typescript
|
|
20
|
+
import { EPostak } from "@epostak/sdk";
|
|
21
|
+
|
|
22
|
+
const client = new EPostak({ apiKey: "sk_live_xxxxx" });
|
|
23
|
+
|
|
24
|
+
// Send an invoice
|
|
25
|
+
const result = await client.documents.send({
|
|
26
|
+
receiverPeppolId: "0191:12345678",
|
|
27
|
+
invoiceNumber: "FV-2026-001",
|
|
28
|
+
issueDate: "2026-04-04",
|
|
29
|
+
dueDate: "2026-04-18",
|
|
30
|
+
items: [
|
|
31
|
+
{ description: "Konzultácia", quantity: 10, unitPrice: 50, vatRate: 23 },
|
|
32
|
+
],
|
|
33
|
+
});
|
|
34
|
+
console.log(result.documentId, result.messageId);
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## Authentication
|
|
40
|
+
|
|
41
|
+
| Key prefix | Use case |
|
|
42
|
+
| ----------- | -------------------------------------------------- |
|
|
43
|
+
| `sk_live_*` | Direct access — acts on behalf of your own firm |
|
|
44
|
+
| `sk_int_*` | Integrator access — acts on behalf of client firms |
|
|
45
|
+
|
|
46
|
+
Generate keys in your ePošťák firm settings or via the dashboard.
|
|
47
|
+
|
|
48
|
+
### Constructor options
|
|
49
|
+
|
|
50
|
+
```typescript
|
|
51
|
+
const client = new EPostak({
|
|
52
|
+
apiKey: "sk_live_xxxxx", // Required
|
|
53
|
+
baseUrl: "https://...", // Optional, defaults to https://epostak.sk/api/enterprise
|
|
54
|
+
firmId: "uuid", // Optional, required for integrator keys
|
|
55
|
+
});
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## API Reference
|
|
61
|
+
|
|
62
|
+
### Documents
|
|
63
|
+
|
|
64
|
+
#### `documents.send(body)` — Send a document via Peppol
|
|
65
|
+
|
|
66
|
+
**JSON mode** — structured data, UBL XML is auto-generated:
|
|
67
|
+
|
|
68
|
+
```typescript
|
|
69
|
+
const result = await client.documents.send({
|
|
70
|
+
receiverPeppolId: "0191:12345678",
|
|
71
|
+
receiverName: "Firma s.r.o.",
|
|
72
|
+
receiverIco: "12345678",
|
|
73
|
+
receiverCountry: "SK",
|
|
74
|
+
invoiceNumber: "FV-2026-001",
|
|
75
|
+
issueDate: "2026-04-04",
|
|
76
|
+
dueDate: "2026-04-18",
|
|
77
|
+
currency: "EUR",
|
|
78
|
+
iban: "SK1234567890123456789012",
|
|
79
|
+
items: [
|
|
80
|
+
{ description: "Konzultácia", quantity: 10, unitPrice: 50, vatRate: 23 },
|
|
81
|
+
],
|
|
82
|
+
});
|
|
83
|
+
// → { documentId, messageId, status: 'SENT' }
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
**XML mode** — send a pre-built UBL XML document:
|
|
87
|
+
|
|
88
|
+
```typescript
|
|
89
|
+
await client.documents.send({
|
|
90
|
+
receiverPeppolId: "0191:12345678",
|
|
91
|
+
xml: '<?xml version="1.0" encoding="UTF-8"?>...',
|
|
92
|
+
});
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
#### `documents.get(id)` — Get a document by ID
|
|
96
|
+
|
|
97
|
+
```typescript
|
|
98
|
+
const doc = await client.documents.get("doc-uuid");
|
|
99
|
+
// → { id, number, status, direction, docType, issueDate, dueDate, currency,
|
|
100
|
+
// supplier, customer, lines, totals, peppolMessageId, createdAt, updatedAt }
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
#### `documents.update(id, body)` — Update a draft document
|
|
104
|
+
|
|
105
|
+
Only documents with status `draft` can be updated. All fields are optional.
|
|
106
|
+
|
|
107
|
+
```typescript
|
|
108
|
+
const updated = await client.documents.update("doc-uuid", {
|
|
109
|
+
invoiceNumber: "FV-2026-002",
|
|
110
|
+
dueDate: "2026-05-01",
|
|
111
|
+
items: [{ description: "Vývoj", quantity: 20, unitPrice: 75, vatRate: 23 }],
|
|
112
|
+
});
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
#### `documents.status(id)` — Full status with history
|
|
116
|
+
|
|
117
|
+
```typescript
|
|
118
|
+
const status = await client.documents.status("doc-uuid");
|
|
119
|
+
// → { id, status, documentType, senderPeppolId, receiverPeppolId,
|
|
120
|
+
// statusHistory: [{ status, timestamp, detail }],
|
|
121
|
+
// validationResult, deliveredAt, acknowledgedAt,
|
|
122
|
+
// invoiceResponseStatus, as4MessageId, createdAt, updatedAt }
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
#### `documents.evidence(id)` — Delivery evidence
|
|
126
|
+
|
|
127
|
+
```typescript
|
|
128
|
+
const evidence = await client.documents.evidence("doc-uuid");
|
|
129
|
+
// → { documentId, as4Receipt, mlrDocument,
|
|
130
|
+
// invoiceResponse: { status, document } | null,
|
|
131
|
+
// deliveredAt, sentAt }
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
#### `documents.pdf(id)` — Download PDF as Buffer
|
|
135
|
+
|
|
136
|
+
```typescript
|
|
137
|
+
const pdf = await client.documents.pdf("doc-uuid");
|
|
138
|
+
require("fs").writeFileSync("invoice.pdf", pdf);
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
#### `documents.ubl(id)` — Download UBL XML as string
|
|
142
|
+
|
|
143
|
+
```typescript
|
|
144
|
+
const ubl = await client.documents.ubl("doc-uuid");
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
#### `documents.respond(id, body)` — Send invoice response
|
|
148
|
+
|
|
149
|
+
Send an invoice response (accept, reject, or query) for a received document.
|
|
150
|
+
|
|
151
|
+
```typescript
|
|
152
|
+
await client.documents.respond("doc-uuid", {
|
|
153
|
+
status: "AP", // 'AP' = accepted, 'RE' = rejected, 'UQ' = under query
|
|
154
|
+
note: "Faktúra akceptovaná",
|
|
155
|
+
});
|
|
156
|
+
// → { documentId, responseStatus, respondedAt }
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
#### `documents.validate(body)` — Validate without sending
|
|
160
|
+
|
|
161
|
+
```typescript
|
|
162
|
+
const validation = await client.documents.validate({
|
|
163
|
+
receiverPeppolId: "0191:12345678",
|
|
164
|
+
items: [{ description: "Test", quantity: 1, unitPrice: 100, vatRate: 23 }],
|
|
165
|
+
});
|
|
166
|
+
// → { valid: boolean, warnings: string[], ubl: string | null }
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
#### `documents.preflight(body)` — Check receiver capability
|
|
170
|
+
|
|
171
|
+
```typescript
|
|
172
|
+
const check = await client.documents.preflight({
|
|
173
|
+
receiverPeppolId: "0191:12345678",
|
|
174
|
+
documentTypeId: "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2",
|
|
175
|
+
});
|
|
176
|
+
// → { receiverPeppolId, registered, supportsDocumentType, smpUrl }
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
#### `documents.convert(body)` — Convert between JSON and UBL
|
|
180
|
+
|
|
181
|
+
```typescript
|
|
182
|
+
// JSON → UBL
|
|
183
|
+
const result = await client.documents.convert({
|
|
184
|
+
direction: 'json_to_ubl',
|
|
185
|
+
data: { invoiceNumber: 'FV-001', items: [...] },
|
|
186
|
+
});
|
|
187
|
+
|
|
188
|
+
// UBL → JSON
|
|
189
|
+
const result = await client.documents.convert({
|
|
190
|
+
direction: 'ubl_to_json',
|
|
191
|
+
xml: '<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">...',
|
|
192
|
+
});
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
---
|
|
196
|
+
|
|
197
|
+
### Inbox
|
|
198
|
+
|
|
199
|
+
#### `documents.inbox.list(params?)` — List received documents
|
|
200
|
+
|
|
201
|
+
```typescript
|
|
202
|
+
const inbox = await client.documents.inbox.list({
|
|
203
|
+
limit: 20, // 1–100, default 20
|
|
204
|
+
offset: 0,
|
|
205
|
+
status: "RECEIVED", // 'RECEIVED' | 'ACKNOWLEDGED'
|
|
206
|
+
since: "2026-04-01T00:00:00Z", // ISO 8601
|
|
207
|
+
});
|
|
208
|
+
// → { documents: InboxDocument[], total, limit, offset }
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
#### `documents.inbox.get(id)` — Full detail with UBL XML
|
|
212
|
+
|
|
213
|
+
```typescript
|
|
214
|
+
const detail = await client.documents.inbox.get("doc-uuid");
|
|
215
|
+
console.log(detail.document); // InboxDocument
|
|
216
|
+
console.log(detail.payload); // UBL XML string or null
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
#### `documents.inbox.acknowledge(id)` — Mark as processed
|
|
220
|
+
|
|
221
|
+
```typescript
|
|
222
|
+
await client.documents.inbox.acknowledge("doc-uuid");
|
|
223
|
+
// → { documentId, status: 'ACKNOWLEDGED', acknowledgedAt }
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
#### `documents.inbox.listAll(params?)` — Cross-firm inbox (integrator)
|
|
227
|
+
|
|
228
|
+
List received documents across all firms linked to an integrator key.
|
|
229
|
+
|
|
230
|
+
```typescript
|
|
231
|
+
const all = await client.documents.inbox.listAll({
|
|
232
|
+
limit: 50, // 1–200, default 50
|
|
233
|
+
offset: 0,
|
|
234
|
+
status: "RECEIVED",
|
|
235
|
+
since: "2026-04-01T00:00:00Z",
|
|
236
|
+
firm_id: "specific-firm-uuid", // Optional filter
|
|
237
|
+
});
|
|
238
|
+
// → { documents: InboxAllDocument[], total, limit, offset }
|
|
239
|
+
// Each document includes firm_id and firm_name
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
---
|
|
243
|
+
|
|
244
|
+
### Peppol
|
|
245
|
+
|
|
246
|
+
#### `peppol.lookup(scheme, identifier)` — SMP participant lookup
|
|
247
|
+
|
|
248
|
+
```typescript
|
|
249
|
+
const participant = await client.peppol.lookup("0191", "12345678");
|
|
250
|
+
// → { peppolId, name, country, capabilities: [{ documentTypeId, processId, transportProfile }] }
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
#### `peppol.directory.search(params?)` — Business Card directory
|
|
254
|
+
|
|
255
|
+
```typescript
|
|
256
|
+
const results = await client.peppol.directory.search({
|
|
257
|
+
q: "Telekom",
|
|
258
|
+
country: "SK",
|
|
259
|
+
page: 0,
|
|
260
|
+
page_size: 20,
|
|
261
|
+
});
|
|
262
|
+
// → { results: DirectoryEntry[], total, page, page_size }
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
#### `peppol.companyLookup(ico)` — Slovak company lookup
|
|
266
|
+
|
|
267
|
+
```typescript
|
|
268
|
+
const company = await client.peppol.companyLookup("12345678");
|
|
269
|
+
// → { ico, name, dic, icDph, address, peppolId }
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
---
|
|
273
|
+
|
|
274
|
+
### Firms (integrator keys)
|
|
275
|
+
|
|
276
|
+
#### `firms.list()` — List all accessible firms
|
|
277
|
+
|
|
278
|
+
```typescript
|
|
279
|
+
const firms = await client.firms.list();
|
|
280
|
+
// → FirmSummary[] — [{ id, name, ico, peppolId, peppolStatus }]
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
#### `firms.get(id)` — Firm detail
|
|
284
|
+
|
|
285
|
+
```typescript
|
|
286
|
+
const firm = await client.firms.get("firm-uuid");
|
|
287
|
+
// → { id, name, ico, peppolId, peppolStatus, dic, icDph, address,
|
|
288
|
+
// peppolIdentifiers: [{ scheme, identifier }], createdAt }
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
#### `firms.documents(id, params?)` — List firm documents
|
|
292
|
+
|
|
293
|
+
```typescript
|
|
294
|
+
const docs = await client.firms.documents("firm-uuid", {
|
|
295
|
+
limit: 20,
|
|
296
|
+
direction: "inbound", // 'inbound' | 'outbound'
|
|
297
|
+
});
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
#### `firms.registerPeppolId(id, peppolId)` — Register Peppol ID
|
|
301
|
+
|
|
302
|
+
```typescript
|
|
303
|
+
await client.firms.registerPeppolId("firm-uuid", {
|
|
304
|
+
scheme: "0191",
|
|
305
|
+
identifier: "12345678",
|
|
306
|
+
});
|
|
307
|
+
// → { peppolId, scheme, identifier, registeredAt }
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
#### `firms.assign(body)` — Assign firm to integrator
|
|
311
|
+
|
|
312
|
+
Assign an existing ePošťák firm to this integrator by ICO. Requires `firm:manage` scope.
|
|
313
|
+
|
|
314
|
+
```typescript
|
|
315
|
+
const result = await client.firms.assign({ ico: "12345678" });
|
|
316
|
+
// → { firm: { id, name, ico, peppol_id, peppol_status }, status: 'active' }
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
#### `firms.assignBatch(body)` — Batch assign firms
|
|
320
|
+
|
|
321
|
+
Assign up to 50 firms in a single request.
|
|
322
|
+
|
|
323
|
+
```typescript
|
|
324
|
+
const result = await client.firms.assignBatch({
|
|
325
|
+
icos: ["12345678", "87654321", "11223344"],
|
|
326
|
+
});
|
|
327
|
+
// → { results: [{ ico, firm?, status?, error?, message? }] }
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
---
|
|
331
|
+
|
|
332
|
+
### Webhooks
|
|
333
|
+
|
|
334
|
+
#### `webhooks.create(body)` — Register a webhook
|
|
335
|
+
|
|
336
|
+
```typescript
|
|
337
|
+
const webhook = await client.webhooks.create({
|
|
338
|
+
url: "https://example.com/webhook",
|
|
339
|
+
events: ["document.received", "document.sent"],
|
|
340
|
+
});
|
|
341
|
+
// Store webhook.secret for HMAC-SHA256 signature verification
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
#### `webhooks.list()` — List webhooks
|
|
345
|
+
|
|
346
|
+
```typescript
|
|
347
|
+
const webhooks = await client.webhooks.list();
|
|
348
|
+
// → Webhook[]
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
#### `webhooks.get(id)` — Webhook detail with deliveries
|
|
352
|
+
|
|
353
|
+
```typescript
|
|
354
|
+
const detail = await client.webhooks.get("webhook-uuid");
|
|
355
|
+
// → { ...webhook, deliveries: WebhookDelivery[] }
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
#### `webhooks.update(id, body)` — Update webhook
|
|
359
|
+
|
|
360
|
+
```typescript
|
|
361
|
+
await client.webhooks.update("webhook-uuid", {
|
|
362
|
+
url: "https://example.com/new-webhook",
|
|
363
|
+
events: ["document.received"],
|
|
364
|
+
isActive: true,
|
|
365
|
+
});
|
|
366
|
+
```
|
|
367
|
+
|
|
368
|
+
#### `webhooks.delete(id)` — Delete webhook
|
|
369
|
+
|
|
370
|
+
```typescript
|
|
371
|
+
await client.webhooks.delete("webhook-uuid");
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
---
|
|
375
|
+
|
|
376
|
+
### Webhook Pull Queue
|
|
377
|
+
|
|
378
|
+
Alternative to push webhooks — poll for events.
|
|
379
|
+
|
|
380
|
+
#### `webhooks.queue.pull(params?)` — Fetch pending events
|
|
381
|
+
|
|
382
|
+
```typescript
|
|
383
|
+
const queue = await client.webhooks.queue.pull({
|
|
384
|
+
limit: 50, // 1–100, default 20
|
|
385
|
+
event_type: "document.received", // Optional filter
|
|
386
|
+
});
|
|
387
|
+
for (const item of queue.items) {
|
|
388
|
+
console.log(item.id, item.type, item.payload);
|
|
389
|
+
}
|
|
390
|
+
// → { items: [{ id, type, created_at, payload }], has_more: boolean }
|
|
391
|
+
```
|
|
392
|
+
|
|
393
|
+
#### `webhooks.queue.ack(eventId)` — Acknowledge single event
|
|
394
|
+
|
|
395
|
+
```typescript
|
|
396
|
+
await client.webhooks.queue.ack("event-uuid");
|
|
397
|
+
// Returns void (HTTP 204)
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
#### `webhooks.queue.batchAck(eventIds)` — Batch acknowledge
|
|
401
|
+
|
|
402
|
+
```typescript
|
|
403
|
+
const ids = queue.items.map((e) => e.id);
|
|
404
|
+
await client.webhooks.queue.batchAck(ids);
|
|
405
|
+
// Returns void (HTTP 204)
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
#### `webhooks.queue.pullAll(params?)` — Cross-firm queue (integrator)
|
|
409
|
+
|
|
410
|
+
Fetch events across all firms linked to an integrator key.
|
|
411
|
+
|
|
412
|
+
```typescript
|
|
413
|
+
const queue = await client.webhooks.queue.pullAll({
|
|
414
|
+
limit: 200, // 1–500, default 100
|
|
415
|
+
since: "2026-04-01T00:00:00Z",
|
|
416
|
+
});
|
|
417
|
+
for (const event of queue.events) {
|
|
418
|
+
console.log(event.firm_id, event.event, event.payload);
|
|
419
|
+
}
|
|
420
|
+
// → { events: [{ event_id, firm_id, event, payload, created_at }], count }
|
|
421
|
+
```
|
|
422
|
+
|
|
423
|
+
#### `webhooks.queue.batchAckAll(eventIds)` — Cross-firm batch ack (integrator)
|
|
424
|
+
|
|
425
|
+
```typescript
|
|
426
|
+
const ids = queue.events.map((e) => e.event_id);
|
|
427
|
+
const result = await client.webhooks.queue.batchAckAll(ids);
|
|
428
|
+
console.log(result.acknowledged); // number of events acknowledged
|
|
429
|
+
```
|
|
430
|
+
|
|
431
|
+
---
|
|
432
|
+
|
|
433
|
+
### Reporting
|
|
434
|
+
|
|
435
|
+
#### `reporting.statistics(params?)` — Aggregated stats
|
|
436
|
+
|
|
437
|
+
```typescript
|
|
438
|
+
const stats = await client.reporting.statistics({
|
|
439
|
+
from: "2026-01-01",
|
|
440
|
+
to: "2026-03-31",
|
|
441
|
+
});
|
|
442
|
+
// → { period: { from, to },
|
|
443
|
+
// outbound: { total, delivered, failed },
|
|
444
|
+
// inbound: { total, acknowledged, pending } }
|
|
445
|
+
```
|
|
446
|
+
|
|
447
|
+
---
|
|
448
|
+
|
|
449
|
+
### Account
|
|
450
|
+
|
|
451
|
+
#### `account.get()` — Account info
|
|
452
|
+
|
|
453
|
+
```typescript
|
|
454
|
+
const account = await client.account.get();
|
|
455
|
+
// → { firm: { name, ico, peppolId, peppolStatus },
|
|
456
|
+
// plan: { name, status },
|
|
457
|
+
// usage: { outbound, inbound } }
|
|
458
|
+
```
|
|
459
|
+
|
|
460
|
+
---
|
|
461
|
+
|
|
462
|
+
### Extract (AI OCR)
|
|
463
|
+
|
|
464
|
+
Requires Enterprise plan.
|
|
465
|
+
|
|
466
|
+
#### `extract.single(file, mimeType, fileName?)` — Single file
|
|
467
|
+
|
|
468
|
+
```typescript
|
|
469
|
+
import { readFileSync } from "fs";
|
|
470
|
+
|
|
471
|
+
const pdf = readFileSync("invoice.pdf");
|
|
472
|
+
const result = await client.extract.single(
|
|
473
|
+
pdf,
|
|
474
|
+
"application/pdf",
|
|
475
|
+
"invoice.pdf",
|
|
476
|
+
);
|
|
477
|
+
// → { extraction: {...}, ubl_xml: string, confidence: number, file_name: string }
|
|
478
|
+
```
|
|
479
|
+
|
|
480
|
+
Supported MIME types: `application/pdf`, `image/jpeg`, `image/png`, `image/webp`. Max 20 MB.
|
|
481
|
+
|
|
482
|
+
#### `extract.batch(files)` — Batch extraction (server-side)
|
|
483
|
+
|
|
484
|
+
Up to 10 files per request. Processed server-side in a single call.
|
|
485
|
+
|
|
486
|
+
```typescript
|
|
487
|
+
const result = await client.extract.batch([
|
|
488
|
+
{ file: pdfBuffer, mimeType: "application/pdf", fileName: "inv1.pdf" },
|
|
489
|
+
{ file: imageBuffer, mimeType: "image/png", fileName: "inv2.png" },
|
|
490
|
+
]);
|
|
491
|
+
// → { batch_id, total, successful, failed,
|
|
492
|
+
// results: [{ file_name, extraction?, ubl_xml?, confidence?, error? }] }
|
|
493
|
+
```
|
|
494
|
+
|
|
495
|
+
---
|
|
496
|
+
|
|
497
|
+
## Integrator Mode
|
|
498
|
+
|
|
499
|
+
Use `sk_int_*` keys to act on behalf of client firms. Integrator keys unlock multi-tenant endpoints.
|
|
500
|
+
|
|
501
|
+
```typescript
|
|
502
|
+
// Option 1: pass firmId in constructor
|
|
503
|
+
const client = new EPostak({ apiKey: 'sk_int_xxxxx', firmId: 'client-firm-uuid' });
|
|
504
|
+
|
|
505
|
+
// Option 2: scope at call time with withFirm()
|
|
506
|
+
const base = new EPostak({ apiKey: 'sk_int_xxxxx' });
|
|
507
|
+
const clientA = base.withFirm('firm-uuid-a');
|
|
508
|
+
const clientB = base.withFirm('firm-uuid-b');
|
|
509
|
+
|
|
510
|
+
await clientA.documents.send({ ... });
|
|
511
|
+
await clientB.documents.inbox.list();
|
|
512
|
+
```
|
|
513
|
+
|
|
514
|
+
### Integrator-only endpoints
|
|
515
|
+
|
|
516
|
+
These endpoints require an integrator key (`sk_int_*`) and operate across all linked firms:
|
|
517
|
+
|
|
518
|
+
| Method | Description |
|
|
519
|
+
| --------------------------------- | -------------------------------------- |
|
|
520
|
+
| `firms.assign({ ico })` | Link a firm to the integrator |
|
|
521
|
+
| `firms.assignBatch({ icos })` | Batch link firms (max 50) |
|
|
522
|
+
| `documents.inbox.listAll()` | Cross-firm inbox with `firm_id` filter |
|
|
523
|
+
| `webhooks.queue.pullAll()` | Cross-firm event queue |
|
|
524
|
+
| `webhooks.queue.batchAckAll(ids)` | Cross-firm batch acknowledge |
|
|
525
|
+
|
|
526
|
+
---
|
|
527
|
+
|
|
528
|
+
## Error Handling
|
|
529
|
+
|
|
530
|
+
All errors are thrown as `EPostakError`:
|
|
531
|
+
|
|
532
|
+
```typescript
|
|
533
|
+
import { EPostak, EPostakError } from '@epostak/sdk';
|
|
534
|
+
|
|
535
|
+
try {
|
|
536
|
+
await client.documents.send({ ... });
|
|
537
|
+
} catch (err) {
|
|
538
|
+
if (err instanceof EPostakError) {
|
|
539
|
+
console.error(err.status); // HTTP status code (0 for network errors)
|
|
540
|
+
console.error(err.code); // Machine-readable code, e.g. 'VALIDATION_FAILED'
|
|
541
|
+
console.error(err.message); // Human-readable message
|
|
542
|
+
console.error(err.details); // Validation details (for 422 errors)
|
|
543
|
+
}
|
|
544
|
+
}
|
|
545
|
+
```
|
|
546
|
+
|
|
547
|
+
### Common error codes
|
|
548
|
+
|
|
549
|
+
| Status | Code | Meaning |
|
|
550
|
+
| ------ | ---------------------- | ------------------------------------------------ |
|
|
551
|
+
| 400 | `BAD_REQUEST` | Invalid request body or parameters |
|
|
552
|
+
| 401 | `UNAUTHORIZED` | Missing or invalid API key |
|
|
553
|
+
| 403 | `FORBIDDEN` | Insufficient permissions or wrong plan |
|
|
554
|
+
| 404 | `NOT_FOUND` | Resource not found |
|
|
555
|
+
| 409 | `CONFLICT` | Duplicate operation (e.g. firm already assigned) |
|
|
556
|
+
| 422 | `UNPROCESSABLE_ENTITY` | Validation failed (check `err.details`) |
|
|
557
|
+
| 429 | `RATE_LIMITED` | Too many requests |
|
|
558
|
+
| 503 | `SERVICE_UNAVAILABLE` | Extraction service not configured |
|
|
559
|
+
|
|
560
|
+
---
|
|
561
|
+
|
|
562
|
+
## TypeScript Support
|
|
563
|
+
|
|
564
|
+
The SDK is written in TypeScript with strict mode. All request params and response shapes are fully typed:
|
|
565
|
+
|
|
566
|
+
```typescript
|
|
567
|
+
import type {
|
|
568
|
+
SendDocumentJsonRequest,
|
|
569
|
+
InboxDocument,
|
|
570
|
+
InboxAllDocument,
|
|
571
|
+
PeppolParticipant,
|
|
572
|
+
Webhook,
|
|
573
|
+
WebhookQueueItem,
|
|
574
|
+
Statistics,
|
|
575
|
+
Account,
|
|
576
|
+
ExtractResult,
|
|
577
|
+
BatchExtractResult,
|
|
578
|
+
} from "@epostak/sdk";
|
|
579
|
+
```
|
|
580
|
+
|
|
581
|
+
---
|
|
582
|
+
|
|
583
|
+
## Full API Endpoint Map
|
|
584
|
+
|
|
585
|
+
| SDK Method | HTTP | Path |
|
|
586
|
+
| ---------------------------------- | ------ | ------------------------------------ |
|
|
587
|
+
| `documents.get(id)` | GET | `/documents/{id}` |
|
|
588
|
+
| `documents.update(id, body)` | PATCH | `/documents/{id}` |
|
|
589
|
+
| `documents.send(body)` | POST | `/documents/send` |
|
|
590
|
+
| `documents.status(id)` | GET | `/documents/{id}/status` |
|
|
591
|
+
| `documents.evidence(id)` | GET | `/documents/{id}/evidence` |
|
|
592
|
+
| `documents.pdf(id)` | GET | `/documents/{id}/pdf` |
|
|
593
|
+
| `documents.ubl(id)` | GET | `/documents/{id}/ubl` |
|
|
594
|
+
| `documents.respond(id, body)` | POST | `/documents/{id}/respond` |
|
|
595
|
+
| `documents.validate(body)` | POST | `/documents/validate` |
|
|
596
|
+
| `documents.preflight(body)` | POST | `/documents/preflight` |
|
|
597
|
+
| `documents.convert(body)` | POST | `/documents/convert` |
|
|
598
|
+
| `documents.inbox.list(params?)` | GET | `/documents/inbox` |
|
|
599
|
+
| `documents.inbox.get(id)` | GET | `/documents/inbox/{id}` |
|
|
600
|
+
| `documents.inbox.acknowledge(id)` | POST | `/documents/inbox/{id}/acknowledge` |
|
|
601
|
+
| `documents.inbox.listAll(params?)` | GET | `/documents/inbox/all` |
|
|
602
|
+
| `peppol.lookup(scheme, id)` | GET | `/peppol/participants/{scheme}/{id}` |
|
|
603
|
+
| `peppol.directory.search(params?)` | GET | `/peppol/directory/search` |
|
|
604
|
+
| `peppol.companyLookup(ico)` | GET | `/company/lookup/{ico}` |
|
|
605
|
+
| `firms.list()` | GET | `/firms` |
|
|
606
|
+
| `firms.get(id)` | GET | `/firms/{id}` |
|
|
607
|
+
| `firms.documents(id, params?)` | GET | `/firms/{id}/documents` |
|
|
608
|
+
| `firms.registerPeppolId(id, body)` | POST | `/firms/{id}/peppol-identifiers` |
|
|
609
|
+
| `firms.assign(body)` | POST | `/firms/assign` |
|
|
610
|
+
| `firms.assignBatch(body)` | POST | `/firms/assign/batch` |
|
|
611
|
+
| `webhooks.create(body)` | POST | `/webhooks` |
|
|
612
|
+
| `webhooks.list()` | GET | `/webhooks` |
|
|
613
|
+
| `webhooks.get(id)` | GET | `/webhooks/{id}` |
|
|
614
|
+
| `webhooks.update(id, body)` | PATCH | `/webhooks/{id}` |
|
|
615
|
+
| `webhooks.delete(id)` | DELETE | `/webhooks/{id}` |
|
|
616
|
+
| `webhooks.queue.pull(params?)` | GET | `/webhook-queue` |
|
|
617
|
+
| `webhooks.queue.ack(eventId)` | DELETE | `/webhook-queue/{eventId}` |
|
|
618
|
+
| `webhooks.queue.batchAck(ids)` | POST | `/webhook-queue/batch-ack` |
|
|
619
|
+
| `webhooks.queue.pullAll(params?)` | GET | `/webhook-queue/all` |
|
|
620
|
+
| `webhooks.queue.batchAckAll(ids)` | POST | `/webhook-queue/all/batch-ack` |
|
|
621
|
+
| `reporting.statistics(params?)` | GET | `/reporting/statistics` |
|
|
622
|
+
| `account.get()` | GET | `/account` |
|
|
623
|
+
| `extract.single(file, mime)` | POST | `/extract` |
|
|
624
|
+
| `extract.batch(files)` | POST | `/extract/batch` |
|
|
625
|
+
|
|
626
|
+
All paths are relative to `https://epostak.sk/api/enterprise`.
|
|
627
|
+
|
|
628
|
+
---
|
|
629
|
+
|
|
630
|
+
## Full API Documentation
|
|
631
|
+
|
|
632
|
+
https://epostak.sk/api/docs/enterprise
|
package/dist/client.d.ts
ADDED
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
import { DocumentsResource } from './resources/documents.js';
|
|
2
|
+
import { FirmsResource } from './resources/firms.js';
|
|
3
|
+
import { PeppolResource } from './resources/peppol.js';
|
|
4
|
+
import { WebhooksResource } from './resources/webhooks.js';
|
|
5
|
+
import { ReportingResource } from './resources/reporting.js';
|
|
6
|
+
import { ExtractResource } from './resources/extract.js';
|
|
7
|
+
import { AccountResource } from './resources/account.js';
|
|
8
|
+
export interface EPostakConfig {
|
|
9
|
+
/**
|
|
10
|
+
* Your Enterprise API key. Use `sk_live_*` for direct access or
|
|
11
|
+
* `sk_int_*` for integrator (multi-tenant) access.
|
|
12
|
+
*/
|
|
13
|
+
apiKey: string;
|
|
14
|
+
/**
|
|
15
|
+
* Base URL for the API. Defaults to `https://epostak.sk/api/enterprise`.
|
|
16
|
+
* Override for staging or local testing.
|
|
17
|
+
*/
|
|
18
|
+
baseUrl?: string;
|
|
19
|
+
/**
|
|
20
|
+
* Firm UUID to act on behalf of. Required when using integrator keys
|
|
21
|
+
* (`sk_int_*`). Each API call will include `X-Firm-Id` header.
|
|
22
|
+
*/
|
|
23
|
+
firmId?: string;
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* ePošťák Enterprise API client.
|
|
27
|
+
*
|
|
28
|
+
* @example
|
|
29
|
+
* ```typescript
|
|
30
|
+
* import { EPostak } from '@epostak/sdk';
|
|
31
|
+
*
|
|
32
|
+
* const client = new EPostak({ apiKey: 'sk_live_xxxxx' });
|
|
33
|
+
* const result = await client.documents.send({ ... });
|
|
34
|
+
* ```
|
|
35
|
+
*/
|
|
36
|
+
export declare class EPostak {
|
|
37
|
+
private readonly clientConfig;
|
|
38
|
+
/** Send and receive documents via Peppol */
|
|
39
|
+
documents: DocumentsResource;
|
|
40
|
+
/** Manage client firms (integrator keys) */
|
|
41
|
+
firms: FirmsResource;
|
|
42
|
+
/** SMP lookup and Peppol directory search */
|
|
43
|
+
peppol: PeppolResource;
|
|
44
|
+
/** Manage webhook subscriptions and pull queue */
|
|
45
|
+
webhooks: WebhooksResource;
|
|
46
|
+
/** Document statistics and reports */
|
|
47
|
+
reporting: ReportingResource;
|
|
48
|
+
/** AI-powered OCR extraction from PDFs and images */
|
|
49
|
+
extract: ExtractResource;
|
|
50
|
+
/** Account and firm information */
|
|
51
|
+
account: AccountResource;
|
|
52
|
+
constructor(config: EPostakConfig);
|
|
53
|
+
/**
|
|
54
|
+
* Create a new client instance scoped to a specific firm.
|
|
55
|
+
* Useful when an integrator key needs to switch between clients.
|
|
56
|
+
*
|
|
57
|
+
* @param firmId - The firm UUID to scope subsequent requests to
|
|
58
|
+
*/
|
|
59
|
+
withFirm(firmId: string): EPostak;
|
|
60
|
+
}
|
|
61
|
+
//# sourceMappingURL=client.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAKzD,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAE5C,4CAA4C;IAC5C,SAAS,EAAE,iBAAiB,CAAC;IAC7B,4CAA4C;IAC5C,KAAK,EAAE,aAAa,CAAC;IACrB,6CAA6C;IAC7C,MAAM,EAAE,cAAc,CAAC;IACvB,kDAAkD;IAClD,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,sCAAsC;IACtC,SAAS,EAAE,iBAAiB,CAAC;IAC7B,qDAAqD;IACrD,OAAO,EAAE,eAAe,CAAC;IACzB,mCAAmC;IACnC,OAAO,EAAE,eAAe,CAAC;gBAEb,MAAM,EAAE,aAAa;IAoBjC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;CAOlC"}
|