@epilot/cli 0.1.66 → 0.1.67
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 +1 -1
- package/definitions/billing.json +1571 -198
- package/dist/bin/epilot.js +6 -6
- package/dist/{chunk-BI57DDAE.js → chunk-6TKZSKWB.js} +5 -1
- package/dist/{completion-3GW2YDYA.js → completion-BZQQTKHB.js} +1 -1
- package/dist/{upgrade-XPAZQL23.js → upgrade-3AUH2MLE.js} +1 -1
- package/package.json +1 -1
package/definitions/billing.json
CHANGED
|
@@ -2,21 +2,58 @@
|
|
|
2
2
|
"openapi": "3.0.3",
|
|
3
3
|
"info": {
|
|
4
4
|
"title": "Billing API",
|
|
5
|
-
"description": "API to manage billing data for epilot contracts and orders",
|
|
5
|
+
"description": "API to manage billing data for epilot contracts and orders.\n\nThis API provides endpoints for managing financial transactions (Buchungssätze) related to\ncustomer contracts (Verträge) including installments (Abschlagszahlungen), payments (Zahlungseingänge),\nreimbursements (Rückerstattungen), and other billing events.\n\n## Key Concepts\n\n- **Billing Event (Buchungssatz)**: A single financial transaction entry in the billing ledger\n- **Contract (Vertrag)**: A customer agreement linked to billing events\n- **Balance (Kontostand)**: The current financial standing of a customer across all contracts\n",
|
|
6
6
|
"version": "1.0.0"
|
|
7
7
|
},
|
|
8
8
|
"tags": [
|
|
9
9
|
{
|
|
10
10
|
"name": "Billing Events",
|
|
11
|
-
"description": "Manage installments,
|
|
11
|
+
"description": "Manage billing events (Buchungssätze) such as installments (Abschlagszahlungen),\npayments (Zahlungseingänge), reimbursements (Rückerstattungen), dunning fees (Mahngebühren),\nand other financial transactions.\n\nBilling events follow double-entry accounting principles where each entry is either\na debit (Soll) or credit (Haben) transaction.\n"
|
|
12
12
|
},
|
|
13
13
|
{
|
|
14
14
|
"name": "Contracts",
|
|
15
|
-
"description": "Manage
|
|
15
|
+
"description": "Manage contract entities (Verträge) within epilot 360.\n\nContracts represent customer agreements and serve as the parent entity for billing events.\nEach contract has associated billing settings such as billing period (Abrechnungszeitraum),\ninstallment amounts (Abschlagsbeträge), and balance tracking.\n"
|
|
16
16
|
},
|
|
17
17
|
{
|
|
18
18
|
"name": "Balance",
|
|
19
|
-
"description": "
|
|
19
|
+
"description": "Retrieve customer balance information (Kontostand).\n\nThe balance represents the total financial standing of a customer across all their\ncontracts and orders, calculated from the sum of all billing events.\n"
|
|
20
|
+
},
|
|
21
|
+
{
|
|
22
|
+
"name": "Pricing Information",
|
|
23
|
+
"description": "Read contract and billing account pricing information"
|
|
24
|
+
},
|
|
25
|
+
{
|
|
26
|
+
"name": "Configuration History",
|
|
27
|
+
"description": "Read billing configuration change history"
|
|
28
|
+
},
|
|
29
|
+
{
|
|
30
|
+
"name": "billing_event_schema",
|
|
31
|
+
"x-displayName": "Billing Event",
|
|
32
|
+
"description": "<SchemaDefinition schemaRef=\"#/components/schemas/BillingEvent\" />\n"
|
|
33
|
+
},
|
|
34
|
+
{
|
|
35
|
+
"name": "contract_schema",
|
|
36
|
+
"x-displayName": "Contract",
|
|
37
|
+
"description": "<SchemaDefinition schemaRef=\"#/components/schemas/Contract\" />\n"
|
|
38
|
+
}
|
|
39
|
+
],
|
|
40
|
+
"x-tagGroups": [
|
|
41
|
+
{
|
|
42
|
+
"name": "APIs",
|
|
43
|
+
"tags": [
|
|
44
|
+
"Billing Events",
|
|
45
|
+
"Contracts",
|
|
46
|
+
"Balance",
|
|
47
|
+
"Pricing Information",
|
|
48
|
+
"Configuration History"
|
|
49
|
+
]
|
|
50
|
+
},
|
|
51
|
+
{
|
|
52
|
+
"name": "Schemas",
|
|
53
|
+
"tags": [
|
|
54
|
+
"billing_event_schema",
|
|
55
|
+
"contract_schema"
|
|
56
|
+
]
|
|
20
57
|
}
|
|
21
58
|
],
|
|
22
59
|
"security": [
|
|
@@ -29,29 +66,32 @@
|
|
|
29
66
|
"get": {
|
|
30
67
|
"operationId": "getBillingEvents",
|
|
31
68
|
"summary": "getBillingEvents",
|
|
32
|
-
"description": "
|
|
69
|
+
"description": "Retrieve and filter billing events (Buchungssätze) such as installments (Abschlagszahlungen),\npayments (Zahlungseingänge), and reimbursements (Rückerstattungen).\n\nResults are paginated and can be filtered by entity, contact, event type, or date range.\n",
|
|
33
70
|
"tags": [
|
|
34
71
|
"Billing Events"
|
|
35
72
|
],
|
|
36
73
|
"parameters": [
|
|
37
74
|
{
|
|
38
|
-
"in": "query",
|
|
39
75
|
"name": "from",
|
|
76
|
+
"in": "query",
|
|
40
77
|
"required": false,
|
|
78
|
+
"description": "Pagination offset - number of results to skip",
|
|
41
79
|
"schema": {
|
|
42
80
|
"type": "number",
|
|
43
|
-
"
|
|
81
|
+
"minimum": 0,
|
|
44
82
|
"example": 0,
|
|
45
83
|
"default": 0
|
|
46
84
|
}
|
|
47
85
|
},
|
|
48
86
|
{
|
|
49
|
-
"in": "query",
|
|
50
87
|
"name": "size",
|
|
88
|
+
"in": "query",
|
|
51
89
|
"required": false,
|
|
90
|
+
"description": "Maximum number of results to return per page",
|
|
52
91
|
"schema": {
|
|
53
92
|
"type": "number",
|
|
54
|
-
"
|
|
93
|
+
"minimum": 1,
|
|
94
|
+
"maximum": 1000,
|
|
55
95
|
"example": 100,
|
|
56
96
|
"default": 100
|
|
57
97
|
}
|
|
@@ -59,87 +99,158 @@
|
|
|
59
99
|
{
|
|
60
100
|
"name": "entity_id",
|
|
61
101
|
"in": "query",
|
|
62
|
-
"description": "Entity ID to filter billing events by",
|
|
63
102
|
"required": false,
|
|
103
|
+
"description": "Filter billing events by one or more entity IDs (e.g., contract or order IDs)",
|
|
64
104
|
"schema": {
|
|
65
105
|
"type": "array",
|
|
66
106
|
"items": {
|
|
67
|
-
"type": "string"
|
|
107
|
+
"type": "string",
|
|
108
|
+
"example": "5da0a718-c822-403d-9f5d-20d4584e0528"
|
|
68
109
|
}
|
|
110
|
+
},
|
|
111
|
+
"example": [
|
|
112
|
+
"5da0a718-c822-403d-9f5d-20d4584e0528"
|
|
113
|
+
]
|
|
114
|
+
},
|
|
115
|
+
{
|
|
116
|
+
"name": "contact_id",
|
|
117
|
+
"in": "query",
|
|
118
|
+
"required": false,
|
|
119
|
+
"description": "Filter billing events by customer contact ID (Kundennummer)",
|
|
120
|
+
"schema": {
|
|
121
|
+
"type": "string",
|
|
122
|
+
"example": "1e3f0d58-69d2-4dbb-9a43-3ee63d862e8e"
|
|
69
123
|
}
|
|
70
124
|
},
|
|
71
125
|
{
|
|
72
126
|
"name": "event_type",
|
|
73
127
|
"in": "query",
|
|
128
|
+
"description": "Filter by billing event type (Buchungsart):\n- `installment`: Abschlagszahlung (scheduled payment due)\n- `reimbursement`: Rückerstattung (refund to customer)\n",
|
|
74
129
|
"schema": {
|
|
75
130
|
"type": "string",
|
|
76
131
|
"enum": [
|
|
77
132
|
"installment",
|
|
78
133
|
"reimbursement"
|
|
79
134
|
],
|
|
80
|
-
"
|
|
135
|
+
"example": "installment"
|
|
81
136
|
}
|
|
82
137
|
},
|
|
83
138
|
{
|
|
84
139
|
"name": "date_after",
|
|
85
140
|
"in": "query",
|
|
141
|
+
"description": "Filter billing events with booking date (Buchungsdatum) after this timestamp",
|
|
86
142
|
"schema": {
|
|
87
143
|
"type": "string",
|
|
88
144
|
"format": "date-time",
|
|
89
|
-
"
|
|
145
|
+
"example": "2025-01-01T00:00:00Z"
|
|
90
146
|
}
|
|
91
147
|
},
|
|
92
148
|
{
|
|
93
149
|
"name": "date_before",
|
|
94
150
|
"in": "query",
|
|
151
|
+
"description": "Filter billing events with booking date (Buchungsdatum) before this timestamp",
|
|
95
152
|
"schema": {
|
|
96
153
|
"type": "string",
|
|
97
154
|
"format": "date-time",
|
|
98
|
-
"
|
|
155
|
+
"example": "2025-12-31T23:59:59Z"
|
|
99
156
|
}
|
|
100
157
|
}
|
|
101
158
|
],
|
|
102
159
|
"responses": {
|
|
103
160
|
"200": {
|
|
104
|
-
"description": "
|
|
161
|
+
"description": "Paginated list of billing events matching the filter criteria",
|
|
105
162
|
"content": {
|
|
106
163
|
"application/json": {
|
|
107
164
|
"schema": {
|
|
108
165
|
"type": "object",
|
|
109
166
|
"properties": {
|
|
110
167
|
"hits": {
|
|
111
|
-
"type": "integer"
|
|
168
|
+
"type": "integer",
|
|
169
|
+
"description": "Total number of billing events matching the query",
|
|
170
|
+
"example": 42
|
|
112
171
|
},
|
|
113
172
|
"results": {
|
|
114
173
|
"type": "array",
|
|
174
|
+
"description": "List of billing events for the current page",
|
|
115
175
|
"items": {
|
|
116
176
|
"$ref": "#/components/schemas/BillingEvent"
|
|
117
177
|
}
|
|
118
178
|
}
|
|
119
179
|
}
|
|
180
|
+
},
|
|
181
|
+
"example": {
|
|
182
|
+
"hits": 42,
|
|
183
|
+
"results": [
|
|
184
|
+
{
|
|
185
|
+
"_id": "5da0a718-c822-403d-9f5d-20d4584e0528",
|
|
186
|
+
"_schema": "billing_event",
|
|
187
|
+
"type": "installment",
|
|
188
|
+
"direction": "debit",
|
|
189
|
+
"billing_amount": 5000,
|
|
190
|
+
"billing_amount_decimal": "50.00",
|
|
191
|
+
"billing_currency": "EUR",
|
|
192
|
+
"booking_date": "2025-07-10",
|
|
193
|
+
"due_date": "2025-07-15",
|
|
194
|
+
"status": "open",
|
|
195
|
+
"contract": {
|
|
196
|
+
"$relation": [
|
|
197
|
+
{
|
|
198
|
+
"entity_id": "f589786b-3024-43cd-9cb3-5a3c953f2896"
|
|
199
|
+
}
|
|
200
|
+
]
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
]
|
|
120
204
|
}
|
|
121
205
|
}
|
|
122
206
|
}
|
|
207
|
+
},
|
|
208
|
+
"400": {
|
|
209
|
+
"$ref": "#/components/responses/BadRequest"
|
|
210
|
+
},
|
|
211
|
+
"401": {
|
|
212
|
+
"$ref": "#/components/responses/Unauthorized"
|
|
213
|
+
},
|
|
214
|
+
"403": {
|
|
215
|
+
"$ref": "#/components/responses/Forbidden"
|
|
216
|
+
},
|
|
217
|
+
"500": {
|
|
218
|
+
"$ref": "#/components/responses/InternalServerError"
|
|
123
219
|
}
|
|
124
220
|
}
|
|
125
221
|
},
|
|
126
222
|
"post": {
|
|
127
223
|
"operationId": "createBillingEvent",
|
|
128
224
|
"summary": "createBillingEvent",
|
|
129
|
-
"description": "Create a new billing event
|
|
225
|
+
"description": "Create a new billing event (Buchungssatz) such as an installment (Abschlagszahlung),\npayment (Zahlungseingang), or reimbursement (Rückerstattung).\n\nThe billing event will be linked to a contract and will affect the customer's balance.\n",
|
|
130
226
|
"tags": [
|
|
131
227
|
"Billing Events"
|
|
132
228
|
],
|
|
133
229
|
"requestBody": {
|
|
134
230
|
"required": true,
|
|
231
|
+
"description": "Billing event data to create",
|
|
135
232
|
"content": {
|
|
136
233
|
"application/json": {
|
|
137
234
|
"schema": {
|
|
138
|
-
"
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
235
|
+
"$ref": "#/components/schemas/BillingEvent"
|
|
236
|
+
},
|
|
237
|
+
"example": {
|
|
238
|
+
"type": "installment",
|
|
239
|
+
"direction": "debit",
|
|
240
|
+
"billing_amount": 5000,
|
|
241
|
+
"billing_amount_decimal": "50.00",
|
|
242
|
+
"billing_currency": "EUR",
|
|
243
|
+
"booking_date": "2025-07-10",
|
|
244
|
+
"due_date": "2025-07-15",
|
|
245
|
+
"status": "open",
|
|
246
|
+
"note": "Monthly installment for July",
|
|
247
|
+
"contract": {
|
|
248
|
+
"$relation": [
|
|
249
|
+
{
|
|
250
|
+
"entity_id": "f589786b-3024-43cd-9cb3-5a3c953f2896"
|
|
251
|
+
}
|
|
252
|
+
]
|
|
253
|
+
}
|
|
143
254
|
}
|
|
144
255
|
}
|
|
145
256
|
}
|
|
@@ -150,14 +261,25 @@
|
|
|
150
261
|
"content": {
|
|
151
262
|
"application/json": {
|
|
152
263
|
"schema": {
|
|
153
|
-
"
|
|
154
|
-
{
|
|
155
|
-
"$ref": "#/components/schemas/BillingEvent"
|
|
156
|
-
}
|
|
157
|
-
]
|
|
264
|
+
"$ref": "#/components/schemas/BillingEvent"
|
|
158
265
|
}
|
|
159
266
|
}
|
|
160
267
|
}
|
|
268
|
+
},
|
|
269
|
+
"400": {
|
|
270
|
+
"$ref": "#/components/responses/BadRequest"
|
|
271
|
+
},
|
|
272
|
+
"401": {
|
|
273
|
+
"$ref": "#/components/responses/Unauthorized"
|
|
274
|
+
},
|
|
275
|
+
"403": {
|
|
276
|
+
"$ref": "#/components/responses/Forbidden"
|
|
277
|
+
},
|
|
278
|
+
"422": {
|
|
279
|
+
"$ref": "#/components/responses/UnprocessableEntity"
|
|
280
|
+
},
|
|
281
|
+
"500": {
|
|
282
|
+
"$ref": "#/components/responses/InternalServerError"
|
|
161
283
|
}
|
|
162
284
|
}
|
|
163
285
|
}
|
|
@@ -166,7 +288,7 @@
|
|
|
166
288
|
"get": {
|
|
167
289
|
"operationId": "getBillingEvent",
|
|
168
290
|
"summary": "getBillingEvent",
|
|
169
|
-
"description": "
|
|
291
|
+
"description": "Retrieve a single billing event (Buchungssatz) by its unique ID.\n",
|
|
170
292
|
"tags": [
|
|
171
293
|
"Billing Events"
|
|
172
294
|
],
|
|
@@ -175,15 +297,16 @@
|
|
|
175
297
|
"name": "id",
|
|
176
298
|
"in": "path",
|
|
177
299
|
"required": true,
|
|
178
|
-
"description": "
|
|
300
|
+
"description": "Unique identifier of the billing event (Buchungssatz-ID)",
|
|
179
301
|
"schema": {
|
|
180
|
-
"type": "string"
|
|
302
|
+
"type": "string",
|
|
303
|
+
"example": "5da0a718-c822-403d-9f5d-20d4584e0528"
|
|
181
304
|
}
|
|
182
305
|
}
|
|
183
306
|
],
|
|
184
307
|
"responses": {
|
|
185
308
|
"200": {
|
|
186
|
-
"description": "Billing
|
|
309
|
+
"description": "Billing event details",
|
|
187
310
|
"content": {
|
|
188
311
|
"application/json": {
|
|
189
312
|
"schema": {
|
|
@@ -191,13 +314,25 @@
|
|
|
191
314
|
}
|
|
192
315
|
}
|
|
193
316
|
}
|
|
317
|
+
},
|
|
318
|
+
"401": {
|
|
319
|
+
"$ref": "#/components/responses/Unauthorized"
|
|
320
|
+
},
|
|
321
|
+
"403": {
|
|
322
|
+
"$ref": "#/components/responses/Forbidden"
|
|
323
|
+
},
|
|
324
|
+
"404": {
|
|
325
|
+
"$ref": "#/components/responses/NotFound"
|
|
326
|
+
},
|
|
327
|
+
"500": {
|
|
328
|
+
"$ref": "#/components/responses/InternalServerError"
|
|
194
329
|
}
|
|
195
330
|
}
|
|
196
331
|
},
|
|
197
332
|
"patch": {
|
|
198
333
|
"operationId": "updateBillingEvent",
|
|
199
334
|
"summary": "updateBillingEvent",
|
|
200
|
-
"description": "Update an existing billing event
|
|
335
|
+
"description": "Update an existing billing event (Buchungssatz).\n\nOnly the fields provided in the request body will be updated.\nCommon use cases include updating status from \"open\" to \"closed\" after payment,\nor correcting billing amounts.\n",
|
|
201
336
|
"tags": [
|
|
202
337
|
"Billing Events"
|
|
203
338
|
],
|
|
@@ -206,25 +341,32 @@
|
|
|
206
341
|
"name": "id",
|
|
207
342
|
"in": "path",
|
|
208
343
|
"required": true,
|
|
209
|
-
"description": "
|
|
344
|
+
"description": "Unique identifier of the billing event to update",
|
|
210
345
|
"schema": {
|
|
211
|
-
"type": "string"
|
|
346
|
+
"type": "string",
|
|
347
|
+
"example": "5da0a718-c822-403d-9f5d-20d4584e0528"
|
|
212
348
|
}
|
|
213
349
|
}
|
|
214
350
|
],
|
|
215
351
|
"requestBody": {
|
|
216
352
|
"required": true,
|
|
353
|
+
"description": "Fields to update on the billing event",
|
|
217
354
|
"content": {
|
|
218
355
|
"application/json": {
|
|
219
356
|
"schema": {
|
|
220
|
-
"$ref": "#/components/schemas/
|
|
357
|
+
"$ref": "#/components/schemas/BillingEventUpdate"
|
|
358
|
+
},
|
|
359
|
+
"example": {
|
|
360
|
+
"status": "closed",
|
|
361
|
+
"paid_date": "2025-07-12T14:30:00Z",
|
|
362
|
+
"note": "Payment received via bank transfer"
|
|
221
363
|
}
|
|
222
364
|
}
|
|
223
365
|
}
|
|
224
366
|
},
|
|
225
367
|
"responses": {
|
|
226
368
|
"200": {
|
|
227
|
-
"description": "Billing
|
|
369
|
+
"description": "Billing event updated successfully",
|
|
228
370
|
"content": {
|
|
229
371
|
"application/json": {
|
|
230
372
|
"schema": {
|
|
@@ -232,13 +374,31 @@
|
|
|
232
374
|
}
|
|
233
375
|
}
|
|
234
376
|
}
|
|
377
|
+
},
|
|
378
|
+
"400": {
|
|
379
|
+
"$ref": "#/components/responses/BadRequest"
|
|
380
|
+
},
|
|
381
|
+
"401": {
|
|
382
|
+
"$ref": "#/components/responses/Unauthorized"
|
|
383
|
+
},
|
|
384
|
+
"403": {
|
|
385
|
+
"$ref": "#/components/responses/Forbidden"
|
|
386
|
+
},
|
|
387
|
+
"404": {
|
|
388
|
+
"$ref": "#/components/responses/NotFound"
|
|
389
|
+
},
|
|
390
|
+
"422": {
|
|
391
|
+
"$ref": "#/components/responses/UnprocessableEntity"
|
|
392
|
+
},
|
|
393
|
+
"500": {
|
|
394
|
+
"$ref": "#/components/responses/InternalServerError"
|
|
235
395
|
}
|
|
236
396
|
}
|
|
237
397
|
},
|
|
238
398
|
"delete": {
|
|
239
399
|
"operationId": "deleteBillingEvent",
|
|
240
400
|
"summary": "deleteBillingEvent",
|
|
241
|
-
"description": "Delete an existing billing event
|
|
401
|
+
"description": "Delete an existing billing event (Buchungssatz).\n\n**Warning**: Deleting billing events affects the customer's balance calculation.\nConsider using a correction event (Korrekturbuchung) instead for audit purposes.\n",
|
|
242
402
|
"tags": [
|
|
243
403
|
"Billing Events"
|
|
244
404
|
],
|
|
@@ -247,15 +407,28 @@
|
|
|
247
407
|
"name": "id",
|
|
248
408
|
"in": "path",
|
|
249
409
|
"required": true,
|
|
250
|
-
"description": "
|
|
410
|
+
"description": "Unique identifier of the billing event to delete",
|
|
251
411
|
"schema": {
|
|
252
|
-
"type": "string"
|
|
412
|
+
"type": "string",
|
|
413
|
+
"example": "5da0a718-c822-403d-9f5d-20d4584e0528"
|
|
253
414
|
}
|
|
254
415
|
}
|
|
255
416
|
],
|
|
256
417
|
"responses": {
|
|
257
418
|
"204": {
|
|
258
|
-
"description": "Billing
|
|
419
|
+
"description": "Billing event deleted successfully"
|
|
420
|
+
},
|
|
421
|
+
"401": {
|
|
422
|
+
"$ref": "#/components/responses/Unauthorized"
|
|
423
|
+
},
|
|
424
|
+
"403": {
|
|
425
|
+
"$ref": "#/components/responses/Forbidden"
|
|
426
|
+
},
|
|
427
|
+
"404": {
|
|
428
|
+
"$ref": "#/components/responses/NotFound"
|
|
429
|
+
},
|
|
430
|
+
"500": {
|
|
431
|
+
"$ref": "#/components/responses/InternalServerError"
|
|
259
432
|
}
|
|
260
433
|
}
|
|
261
434
|
}
|
|
@@ -264,7 +437,7 @@
|
|
|
264
437
|
"get": {
|
|
265
438
|
"operationId": "getBillingEventByExternalId",
|
|
266
439
|
"summary": "getBillingEventByExternalId",
|
|
267
|
-
"description": "
|
|
440
|
+
"description": "Retrieve a billing event (Buchungssatz) by its external system identifier.\n\nThis endpoint is useful for integrations with external systems such as SAP FI/CA,\nERP systems, or payment processors that maintain their own reference IDs.\n",
|
|
268
441
|
"tags": [
|
|
269
442
|
"Billing Events"
|
|
270
443
|
],
|
|
@@ -273,15 +446,16 @@
|
|
|
273
446
|
"name": "external_id",
|
|
274
447
|
"in": "path",
|
|
275
448
|
"required": true,
|
|
276
|
-
"description": "
|
|
449
|
+
"description": "External system identifier for the billing event.\nFor example, a SAP document number or payment processor reference ID.\n",
|
|
277
450
|
"schema": {
|
|
278
|
-
"type": "string"
|
|
451
|
+
"type": "string",
|
|
452
|
+
"example": "SAP-54321"
|
|
279
453
|
}
|
|
280
454
|
}
|
|
281
455
|
],
|
|
282
456
|
"responses": {
|
|
283
457
|
"200": {
|
|
284
|
-
"description": "Billing
|
|
458
|
+
"description": "Billing event details",
|
|
285
459
|
"content": {
|
|
286
460
|
"application/json": {
|
|
287
461
|
"schema": {
|
|
@@ -289,6 +463,18 @@
|
|
|
289
463
|
}
|
|
290
464
|
}
|
|
291
465
|
}
|
|
466
|
+
},
|
|
467
|
+
"401": {
|
|
468
|
+
"$ref": "#/components/responses/Unauthorized"
|
|
469
|
+
},
|
|
470
|
+
"403": {
|
|
471
|
+
"$ref": "#/components/responses/Forbidden"
|
|
472
|
+
},
|
|
473
|
+
"404": {
|
|
474
|
+
"$ref": "#/components/responses/NotFound"
|
|
475
|
+
},
|
|
476
|
+
"500": {
|
|
477
|
+
"$ref": "#/components/responses/InternalServerError"
|
|
292
478
|
}
|
|
293
479
|
}
|
|
294
480
|
}
|
|
@@ -297,16 +483,28 @@
|
|
|
297
483
|
"post": {
|
|
298
484
|
"operationId": "createContractEntity",
|
|
299
485
|
"summary": "createContractEntity",
|
|
300
|
-
"description": "Create a new contract entity
|
|
486
|
+
"description": "Create a new contract entity (Vertrag) for billing purposes.\n\nContracts serve as the parent entity for billing events and contain billing\nsettings such as installment amounts (Abschlagsbeträge), billing periods\n(Abrechnungszeiträume), and customer addresses.\n",
|
|
301
487
|
"tags": [
|
|
302
488
|
"Contracts"
|
|
303
489
|
],
|
|
304
490
|
"requestBody": {
|
|
305
491
|
"required": true,
|
|
492
|
+
"description": "Contract data to create",
|
|
306
493
|
"content": {
|
|
307
494
|
"application/json": {
|
|
308
495
|
"schema": {
|
|
309
496
|
"$ref": "#/components/schemas/Contract"
|
|
497
|
+
},
|
|
498
|
+
"example": {
|
|
499
|
+
"contract_name": "Stromvertrag Haushalt",
|
|
500
|
+
"contract_number": "STR-2025-001234",
|
|
501
|
+
"status": "active",
|
|
502
|
+
"branch": "power",
|
|
503
|
+
"billing_period": "monthly",
|
|
504
|
+
"installment_amount": 8500,
|
|
505
|
+
"billing_due_day": 15,
|
|
506
|
+
"start_date": "2025-01-01",
|
|
507
|
+
"billing_address": "Musterstraße 123, 50667 Köln"
|
|
310
508
|
}
|
|
311
509
|
}
|
|
312
510
|
}
|
|
@@ -321,6 +519,21 @@
|
|
|
321
519
|
}
|
|
322
520
|
}
|
|
323
521
|
}
|
|
522
|
+
},
|
|
523
|
+
"400": {
|
|
524
|
+
"$ref": "#/components/responses/BadRequest"
|
|
525
|
+
},
|
|
526
|
+
"401": {
|
|
527
|
+
"$ref": "#/components/responses/Unauthorized"
|
|
528
|
+
},
|
|
529
|
+
"403": {
|
|
530
|
+
"$ref": "#/components/responses/Forbidden"
|
|
531
|
+
},
|
|
532
|
+
"422": {
|
|
533
|
+
"$ref": "#/components/responses/UnprocessableEntity"
|
|
534
|
+
},
|
|
535
|
+
"500": {
|
|
536
|
+
"$ref": "#/components/responses/InternalServerError"
|
|
324
537
|
}
|
|
325
538
|
}
|
|
326
539
|
}
|
|
@@ -329,7 +542,7 @@
|
|
|
329
542
|
"patch": {
|
|
330
543
|
"operationId": "updateContractEntity",
|
|
331
544
|
"summary": "updateContractEntity",
|
|
332
|
-
"description": "Update an existing contract entity
|
|
545
|
+
"description": "Update an existing contract entity (Vertrag).\n\nOnly the fields provided in the request body will be updated.\nCommon use cases include updating billing settings, changing status,\nor recording termination details.\n",
|
|
333
546
|
"tags": [
|
|
334
547
|
"Contracts"
|
|
335
548
|
],
|
|
@@ -338,18 +551,25 @@
|
|
|
338
551
|
"name": "id",
|
|
339
552
|
"in": "path",
|
|
340
553
|
"required": true,
|
|
341
|
-
"description": "
|
|
554
|
+
"description": "Unique identifier of the contract (Vertragsnummer)",
|
|
342
555
|
"schema": {
|
|
343
|
-
"type": "string"
|
|
556
|
+
"type": "string",
|
|
557
|
+
"example": "f589786b-3024-43cd-9cb3-5a3c953f2896"
|
|
344
558
|
}
|
|
345
559
|
}
|
|
346
560
|
],
|
|
347
561
|
"requestBody": {
|
|
348
562
|
"required": true,
|
|
563
|
+
"description": "Fields to update on the contract",
|
|
349
564
|
"content": {
|
|
350
565
|
"application/json": {
|
|
351
566
|
"schema": {
|
|
352
567
|
"$ref": "#/components/schemas/Contract"
|
|
568
|
+
},
|
|
569
|
+
"example": {
|
|
570
|
+
"status": "terminated",
|
|
571
|
+
"termination_date": "2025-06-30",
|
|
572
|
+
"termination_reason": "Kundenkündigung"
|
|
353
573
|
}
|
|
354
574
|
}
|
|
355
575
|
}
|
|
@@ -364,13 +584,31 @@
|
|
|
364
584
|
}
|
|
365
585
|
}
|
|
366
586
|
}
|
|
587
|
+
},
|
|
588
|
+
"400": {
|
|
589
|
+
"$ref": "#/components/responses/BadRequest"
|
|
590
|
+
},
|
|
591
|
+
"401": {
|
|
592
|
+
"$ref": "#/components/responses/Unauthorized"
|
|
593
|
+
},
|
|
594
|
+
"403": {
|
|
595
|
+
"$ref": "#/components/responses/Forbidden"
|
|
596
|
+
},
|
|
597
|
+
"404": {
|
|
598
|
+
"$ref": "#/components/responses/NotFound"
|
|
599
|
+
},
|
|
600
|
+
"422": {
|
|
601
|
+
"$ref": "#/components/responses/UnprocessableEntity"
|
|
602
|
+
},
|
|
603
|
+
"500": {
|
|
604
|
+
"$ref": "#/components/responses/InternalServerError"
|
|
367
605
|
}
|
|
368
606
|
}
|
|
369
607
|
},
|
|
370
608
|
"delete": {
|
|
371
609
|
"operationId": "deleteContractEntity",
|
|
372
610
|
"summary": "deleteContractEntity",
|
|
373
|
-
"description": "Delete an existing contract entity
|
|
611
|
+
"description": "Delete an existing contract entity (Vertrag).\n\n**Warning**: Deleting a contract will affect all associated billing events.\nConsider setting the contract status to \"terminated\" instead for audit purposes.\n",
|
|
374
612
|
"tags": [
|
|
375
613
|
"Contracts"
|
|
376
614
|
],
|
|
@@ -379,19 +617,175 @@
|
|
|
379
617
|
"name": "id",
|
|
380
618
|
"in": "path",
|
|
381
619
|
"required": true,
|
|
382
|
-
"description": "
|
|
620
|
+
"description": "Unique identifier of the contract to delete",
|
|
383
621
|
"schema": {
|
|
384
|
-
"type": "string"
|
|
622
|
+
"type": "string",
|
|
623
|
+
"example": "f589786b-3024-43cd-9cb3-5a3c953f2896"
|
|
385
624
|
}
|
|
386
625
|
}
|
|
387
626
|
],
|
|
388
627
|
"responses": {
|
|
389
628
|
"204": {
|
|
390
|
-
"description": "Contract deleted successfully"
|
|
629
|
+
"description": "Contract deleted successfully"
|
|
630
|
+
},
|
|
631
|
+
"401": {
|
|
632
|
+
"$ref": "#/components/responses/Unauthorized"
|
|
633
|
+
},
|
|
634
|
+
"403": {
|
|
635
|
+
"$ref": "#/components/responses/Forbidden"
|
|
636
|
+
},
|
|
637
|
+
"404": {
|
|
638
|
+
"$ref": "#/components/responses/NotFound"
|
|
639
|
+
},
|
|
640
|
+
"500": {
|
|
641
|
+
"$ref": "#/components/responses/InternalServerError"
|
|
642
|
+
}
|
|
643
|
+
}
|
|
644
|
+
}
|
|
645
|
+
},
|
|
646
|
+
"/v1/billing/contracts/{id}/pricing_information": {
|
|
647
|
+
"get": {
|
|
648
|
+
"operationId": "getContractPricingInformation",
|
|
649
|
+
"summary": "getContractPricingInformation",
|
|
650
|
+
"description": "Get current pricing information and recent configuration history for a Contract.",
|
|
651
|
+
"tags": [
|
|
652
|
+
"Pricing Information"
|
|
653
|
+
],
|
|
654
|
+
"parameters": [
|
|
655
|
+
{
|
|
656
|
+
"name": "id",
|
|
657
|
+
"in": "path",
|
|
658
|
+
"required": true,
|
|
659
|
+
"description": "ID of the Contract entity",
|
|
660
|
+
"schema": {
|
|
661
|
+
"type": "string"
|
|
662
|
+
}
|
|
663
|
+
}
|
|
664
|
+
],
|
|
665
|
+
"responses": {
|
|
666
|
+
"200": {
|
|
667
|
+
"description": "Contract pricing information",
|
|
391
668
|
"content": {
|
|
392
669
|
"application/json": {
|
|
393
670
|
"schema": {
|
|
394
|
-
"$ref": "#/components/schemas/
|
|
671
|
+
"$ref": "#/components/schemas/ContractPricingInformation"
|
|
672
|
+
}
|
|
673
|
+
}
|
|
674
|
+
}
|
|
675
|
+
}
|
|
676
|
+
}
|
|
677
|
+
}
|
|
678
|
+
},
|
|
679
|
+
"/v1/billing/billing_accounts/{id}/pricing_information": {
|
|
680
|
+
"get": {
|
|
681
|
+
"operationId": "getBillingAccountPricingInformation",
|
|
682
|
+
"summary": "getBillingAccountPricingInformation",
|
|
683
|
+
"description": "Get current pricing information for the active Contracts linked to a Billing Account.",
|
|
684
|
+
"tags": [
|
|
685
|
+
"Pricing Information"
|
|
686
|
+
],
|
|
687
|
+
"parameters": [
|
|
688
|
+
{
|
|
689
|
+
"name": "id",
|
|
690
|
+
"in": "path",
|
|
691
|
+
"required": true,
|
|
692
|
+
"description": "ID of the Billing Account entity",
|
|
693
|
+
"schema": {
|
|
694
|
+
"type": "string"
|
|
695
|
+
}
|
|
696
|
+
}
|
|
697
|
+
],
|
|
698
|
+
"responses": {
|
|
699
|
+
"200": {
|
|
700
|
+
"description": "Billing Account pricing information",
|
|
701
|
+
"content": {
|
|
702
|
+
"application/json": {
|
|
703
|
+
"schema": {
|
|
704
|
+
"$ref": "#/components/schemas/BillingAccountPricingInformation"
|
|
705
|
+
}
|
|
706
|
+
}
|
|
707
|
+
}
|
|
708
|
+
}
|
|
709
|
+
}
|
|
710
|
+
}
|
|
711
|
+
},
|
|
712
|
+
"/v1/billing/contracts/{id}/configuration_history": {
|
|
713
|
+
"get": {
|
|
714
|
+
"operationId": "getContractConfigurationHistory",
|
|
715
|
+
"summary": "getContractConfigurationHistory",
|
|
716
|
+
"description": "Get billing configuration history for a Contract.",
|
|
717
|
+
"tags": [
|
|
718
|
+
"Configuration History"
|
|
719
|
+
],
|
|
720
|
+
"parameters": [
|
|
721
|
+
{
|
|
722
|
+
"name": "id",
|
|
723
|
+
"in": "path",
|
|
724
|
+
"required": true,
|
|
725
|
+
"description": "ID of the Contract entity",
|
|
726
|
+
"schema": {
|
|
727
|
+
"type": "string"
|
|
728
|
+
}
|
|
729
|
+
},
|
|
730
|
+
{
|
|
731
|
+
"$ref": "#/components/parameters/ConfigurationHistoryChangeType"
|
|
732
|
+
},
|
|
733
|
+
{
|
|
734
|
+
"$ref": "#/components/parameters/From"
|
|
735
|
+
},
|
|
736
|
+
{
|
|
737
|
+
"$ref": "#/components/parameters/Size"
|
|
738
|
+
}
|
|
739
|
+
],
|
|
740
|
+
"responses": {
|
|
741
|
+
"200": {
|
|
742
|
+
"description": "Contract configuration history",
|
|
743
|
+
"content": {
|
|
744
|
+
"application/json": {
|
|
745
|
+
"schema": {
|
|
746
|
+
"$ref": "#/components/schemas/ConfigurationHistoryResponse"
|
|
747
|
+
}
|
|
748
|
+
}
|
|
749
|
+
}
|
|
750
|
+
}
|
|
751
|
+
}
|
|
752
|
+
}
|
|
753
|
+
},
|
|
754
|
+
"/v1/billing/billing_accounts/{id}/configuration_history": {
|
|
755
|
+
"get": {
|
|
756
|
+
"operationId": "getBillingAccountConfigurationHistory",
|
|
757
|
+
"summary": "getBillingAccountConfigurationHistory",
|
|
758
|
+
"description": "Get merged billing configuration history for active Contracts linked to a Billing Account.",
|
|
759
|
+
"tags": [
|
|
760
|
+
"Configuration History"
|
|
761
|
+
],
|
|
762
|
+
"parameters": [
|
|
763
|
+
{
|
|
764
|
+
"name": "id",
|
|
765
|
+
"in": "path",
|
|
766
|
+
"required": true,
|
|
767
|
+
"description": "ID of the Billing Account entity",
|
|
768
|
+
"schema": {
|
|
769
|
+
"type": "string"
|
|
770
|
+
}
|
|
771
|
+
},
|
|
772
|
+
{
|
|
773
|
+
"$ref": "#/components/parameters/ConfigurationHistoryChangeType"
|
|
774
|
+
},
|
|
775
|
+
{
|
|
776
|
+
"$ref": "#/components/parameters/From"
|
|
777
|
+
},
|
|
778
|
+
{
|
|
779
|
+
"$ref": "#/components/parameters/Size"
|
|
780
|
+
}
|
|
781
|
+
],
|
|
782
|
+
"responses": {
|
|
783
|
+
"200": {
|
|
784
|
+
"description": "Billing Account configuration history",
|
|
785
|
+
"content": {
|
|
786
|
+
"application/json": {
|
|
787
|
+
"schema": {
|
|
788
|
+
"$ref": "#/components/schemas/ConfigurationHistoryResponse"
|
|
395
789
|
}
|
|
396
790
|
}
|
|
397
791
|
}
|
|
@@ -403,7 +797,7 @@
|
|
|
403
797
|
"get": {
|
|
404
798
|
"operationId": "getCustomerBalance",
|
|
405
799
|
"summary": "getCustomerBalance",
|
|
406
|
-
"description": "
|
|
800
|
+
"description": "Retrieve the total balance (Kontostand) across all contracts and orders for a customer.\n\nThe balance is calculated from the sum of all billing events (Buchungssätze) associated\nwith the customer's contracts. A positive balance indicates the customer owes money;\na negative balance indicates a credit (Guthaben) in the customer's favor.\n",
|
|
407
801
|
"tags": [
|
|
408
802
|
"Balance"
|
|
409
803
|
],
|
|
@@ -411,7 +805,7 @@
|
|
|
411
805
|
{
|
|
412
806
|
"name": "id",
|
|
413
807
|
"in": "path",
|
|
414
|
-
"description": "Customer entity ID
|
|
808
|
+
"description": "Customer entity ID. This can be either a contact ID (Kontakt-ID) or\nan account ID (Kundenkonto-ID).\n",
|
|
415
809
|
"required": true,
|
|
416
810
|
"schema": {
|
|
417
811
|
"type": "string",
|
|
@@ -421,20 +815,75 @@
|
|
|
421
815
|
],
|
|
422
816
|
"responses": {
|
|
423
817
|
"200": {
|
|
424
|
-
"description": "
|
|
818
|
+
"description": "Customer balance information",
|
|
425
819
|
"content": {
|
|
426
820
|
"application/json": {
|
|
427
821
|
"schema": {
|
|
428
822
|
"$ref": "#/components/schemas/Balance"
|
|
823
|
+
},
|
|
824
|
+
"example": {
|
|
825
|
+
"balance": 8990,
|
|
826
|
+
"balance_decimal": "89.90",
|
|
827
|
+
"balance_currency": "EUR"
|
|
429
828
|
}
|
|
430
829
|
}
|
|
431
830
|
}
|
|
831
|
+
},
|
|
832
|
+
"401": {
|
|
833
|
+
"$ref": "#/components/responses/Unauthorized"
|
|
834
|
+
},
|
|
835
|
+
"403": {
|
|
836
|
+
"$ref": "#/components/responses/Forbidden"
|
|
837
|
+
},
|
|
838
|
+
"404": {
|
|
839
|
+
"$ref": "#/components/responses/NotFound"
|
|
840
|
+
},
|
|
841
|
+
"500": {
|
|
842
|
+
"$ref": "#/components/responses/InternalServerError"
|
|
432
843
|
}
|
|
433
844
|
}
|
|
434
845
|
}
|
|
435
846
|
}
|
|
436
847
|
},
|
|
437
848
|
"components": {
|
|
849
|
+
"parameters": {
|
|
850
|
+
"From": {
|
|
851
|
+
"name": "from",
|
|
852
|
+
"in": "query",
|
|
853
|
+
"required": false,
|
|
854
|
+
"schema": {
|
|
855
|
+
"type": "integer",
|
|
856
|
+
"minimum": 0,
|
|
857
|
+
"default": 0
|
|
858
|
+
},
|
|
859
|
+
"description": "Initial offset for paginated results."
|
|
860
|
+
},
|
|
861
|
+
"Size": {
|
|
862
|
+
"name": "size",
|
|
863
|
+
"in": "query",
|
|
864
|
+
"required": false,
|
|
865
|
+
"schema": {
|
|
866
|
+
"type": "integer",
|
|
867
|
+
"minimum": 1,
|
|
868
|
+
"maximum": 100,
|
|
869
|
+
"default": 25
|
|
870
|
+
},
|
|
871
|
+
"description": "Maximum number of results to return."
|
|
872
|
+
},
|
|
873
|
+
"ConfigurationHistoryChangeType": {
|
|
874
|
+
"name": "change_type",
|
|
875
|
+
"in": "query",
|
|
876
|
+
"required": false,
|
|
877
|
+
"schema": {
|
|
878
|
+
"type": "string",
|
|
879
|
+
"enum": [
|
|
880
|
+
"installment_amount_changed"
|
|
881
|
+
],
|
|
882
|
+
"default": "installment_amount_changed"
|
|
883
|
+
},
|
|
884
|
+
"description": "Billing configuration change type to return."
|
|
885
|
+
}
|
|
886
|
+
},
|
|
438
887
|
"securitySchemes": {
|
|
439
888
|
"EpilotAuth": {
|
|
440
889
|
"type": "http",
|
|
@@ -443,121 +892,668 @@
|
|
|
443
892
|
"bearerFormat": "JWT"
|
|
444
893
|
}
|
|
445
894
|
},
|
|
446
|
-
"
|
|
447
|
-
"
|
|
448
|
-
"
|
|
449
|
-
"
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
},
|
|
458
|
-
"_org": {
|
|
459
|
-
"type": "string",
|
|
460
|
-
"description": "Organization Id the entity belongs to"
|
|
461
|
-
},
|
|
462
|
-
"_schema": {
|
|
463
|
-
"$ref": "#/components/schemas/EntitySlug"
|
|
464
|
-
},
|
|
465
|
-
"_tags": {
|
|
466
|
-
"type": "array",
|
|
467
|
-
"items": {
|
|
468
|
-
"type": "string"
|
|
895
|
+
"responses": {
|
|
896
|
+
"BadRequest": {
|
|
897
|
+
"description": "Bad Request - The request was malformed or contains invalid parameters.\nCheck the request body and query parameters for syntax errors.\n",
|
|
898
|
+
"content": {
|
|
899
|
+
"application/json": {
|
|
900
|
+
"schema": {
|
|
901
|
+
"$ref": "#/components/schemas/Error"
|
|
902
|
+
},
|
|
903
|
+
"example": {
|
|
904
|
+
"error": "Bad Request",
|
|
905
|
+
"message": "Invalid date format for 'due_date'. Expected ISO 8601 date format (YYYY-MM-DD)."
|
|
469
906
|
}
|
|
470
|
-
},
|
|
471
|
-
"_created_at": {
|
|
472
|
-
"type": "string"
|
|
473
|
-
},
|
|
474
|
-
"_updated_at": {
|
|
475
|
-
"type": "string"
|
|
476
907
|
}
|
|
477
908
|
}
|
|
478
909
|
},
|
|
479
|
-
"
|
|
480
|
-
"
|
|
481
|
-
"
|
|
482
|
-
|
|
910
|
+
"Unauthorized": {
|
|
911
|
+
"description": "Unauthorized - Authentication credentials are missing or invalid.\nEnsure a valid Bearer token is included in the Authorization header.\n",
|
|
912
|
+
"content": {
|
|
913
|
+
"application/json": {
|
|
914
|
+
"schema": {
|
|
915
|
+
"$ref": "#/components/schemas/Error"
|
|
916
|
+
},
|
|
917
|
+
"example": {
|
|
918
|
+
"error": "Unauthorized",
|
|
919
|
+
"message": "Missing or invalid authentication token."
|
|
920
|
+
}
|
|
921
|
+
}
|
|
922
|
+
}
|
|
923
|
+
},
|
|
924
|
+
"Forbidden": {
|
|
925
|
+
"description": "Forbidden - The authenticated user does not have permission to perform this action.\nContact your organization administrator to request access.\n",
|
|
926
|
+
"content": {
|
|
927
|
+
"application/json": {
|
|
928
|
+
"schema": {
|
|
929
|
+
"$ref": "#/components/schemas/Error"
|
|
930
|
+
},
|
|
931
|
+
"example": {
|
|
932
|
+
"error": "Forbidden",
|
|
933
|
+
"message": "You do not have permission to access this resource."
|
|
934
|
+
}
|
|
935
|
+
}
|
|
936
|
+
}
|
|
937
|
+
},
|
|
938
|
+
"NotFound": {
|
|
939
|
+
"description": "Not Found - The requested resource does not exist or has been deleted.\nVerify the ID is correct and the resource exists in your organization.\n",
|
|
940
|
+
"content": {
|
|
941
|
+
"application/json": {
|
|
942
|
+
"schema": {
|
|
943
|
+
"$ref": "#/components/schemas/Error"
|
|
944
|
+
},
|
|
945
|
+
"example": {
|
|
946
|
+
"error": "Not Found",
|
|
947
|
+
"message": "Billing event with ID '5da0a718-c822-403d-9f5d-20d4584e0528' not found."
|
|
948
|
+
}
|
|
949
|
+
}
|
|
950
|
+
}
|
|
951
|
+
},
|
|
952
|
+
"UnprocessableEntity": {
|
|
953
|
+
"description": "Unprocessable Entity - The request was well-formed but contains semantic errors.\nThis typically indicates validation failures such as missing required fields\nor invalid field values.\n",
|
|
954
|
+
"content": {
|
|
955
|
+
"application/json": {
|
|
956
|
+
"schema": {
|
|
957
|
+
"$ref": "#/components/schemas/Error"
|
|
958
|
+
},
|
|
959
|
+
"example": {
|
|
960
|
+
"error": "Unprocessable Entity",
|
|
961
|
+
"message": "Validation failed: 'billing_amount' must be a positive integer."
|
|
962
|
+
}
|
|
963
|
+
}
|
|
964
|
+
}
|
|
965
|
+
},
|
|
966
|
+
"InternalServerError": {
|
|
967
|
+
"description": "Internal Server Error - An unexpected error occurred on the server.\nPlease try again later or contact support if the issue persists.\n",
|
|
968
|
+
"content": {
|
|
969
|
+
"application/json": {
|
|
970
|
+
"schema": {
|
|
971
|
+
"$ref": "#/components/schemas/Error"
|
|
972
|
+
},
|
|
973
|
+
"example": {
|
|
974
|
+
"error": "Internal Server Error",
|
|
975
|
+
"message": "An unexpected error occurred. Please try again later."
|
|
976
|
+
}
|
|
977
|
+
}
|
|
978
|
+
}
|
|
979
|
+
}
|
|
980
|
+
},
|
|
981
|
+
"schemas": {
|
|
982
|
+
"Error": {
|
|
983
|
+
"type": "object",
|
|
984
|
+
"description": "Standard error response format",
|
|
985
|
+
"properties": {
|
|
986
|
+
"error": {
|
|
987
|
+
"type": "string",
|
|
988
|
+
"description": "Error type or HTTP status text",
|
|
989
|
+
"example": "Bad Request"
|
|
990
|
+
},
|
|
991
|
+
"message": {
|
|
992
|
+
"type": "string",
|
|
993
|
+
"description": "Human-readable error description",
|
|
994
|
+
"example": "Invalid request parameters."
|
|
995
|
+
}
|
|
996
|
+
},
|
|
997
|
+
"required": [
|
|
998
|
+
"error",
|
|
999
|
+
"message"
|
|
1000
|
+
]
|
|
1001
|
+
},
|
|
1002
|
+
"BaseEntity": {
|
|
1003
|
+
"type": "object",
|
|
1004
|
+
"description": "Base schema for all epilot entities with common system fields",
|
|
1005
|
+
"additionalProperties": true,
|
|
1006
|
+
"properties": {
|
|
1007
|
+
"_id": {
|
|
1008
|
+
"$ref": "#/components/schemas/EntityId"
|
|
1009
|
+
},
|
|
1010
|
+
"_title": {
|
|
1011
|
+
"type": "string",
|
|
1012
|
+
"description": "Display title of the entity (Anzeigetitel)",
|
|
1013
|
+
"example": "Abschlagszahlung Juli 2025"
|
|
1014
|
+
},
|
|
1015
|
+
"_org": {
|
|
1016
|
+
"type": "string",
|
|
1017
|
+
"description": "Organization ID the entity belongs to (Organisations-ID)",
|
|
1018
|
+
"example": "123456"
|
|
1019
|
+
},
|
|
1020
|
+
"_schema": {
|
|
1021
|
+
"$ref": "#/components/schemas/EntitySlug"
|
|
1022
|
+
},
|
|
1023
|
+
"_tags": {
|
|
1024
|
+
"type": "array",
|
|
1025
|
+
"description": "Tags for categorization and filtering (Schlagwörter)",
|
|
1026
|
+
"items": {
|
|
1027
|
+
"type": "string"
|
|
1028
|
+
},
|
|
1029
|
+
"example": [
|
|
1030
|
+
"billing",
|
|
1031
|
+
"energy"
|
|
1032
|
+
]
|
|
1033
|
+
},
|
|
1034
|
+
"_created_at": {
|
|
1035
|
+
"type": "string",
|
|
1036
|
+
"format": "date-time",
|
|
1037
|
+
"description": "Timestamp when the entity was created (Erstellungszeitpunkt)",
|
|
1038
|
+
"example": "2025-06-15T10:30:00Z"
|
|
1039
|
+
},
|
|
1040
|
+
"_updated_at": {
|
|
1041
|
+
"type": "string",
|
|
1042
|
+
"format": "date-time",
|
|
1043
|
+
"description": "Timestamp when the entity was last updated (Aktualisierungszeitpunkt)",
|
|
1044
|
+
"example": "2025-06-15T14:45:00Z"
|
|
1045
|
+
}
|
|
1046
|
+
}
|
|
1047
|
+
},
|
|
1048
|
+
"EntityId": {
|
|
1049
|
+
"type": "string",
|
|
1050
|
+
"description": "Unique entity identifier (UUID format)",
|
|
1051
|
+
"example": "5da0a718-c822-403d-9f5d-20d4584e0528"
|
|
483
1052
|
},
|
|
484
1053
|
"EntitySlug": {
|
|
485
|
-
"description": "URL-friendly identifier for the entity schema",
|
|
486
1054
|
"type": "string",
|
|
487
|
-
"
|
|
488
|
-
|
|
489
|
-
"contract",
|
|
490
|
-
"file",
|
|
491
|
-
"order",
|
|
492
|
-
"opportunity",
|
|
493
|
-
"product",
|
|
494
|
-
"price",
|
|
495
|
-
"meter",
|
|
496
|
-
"meter_counter",
|
|
497
|
-
"billing_event"
|
|
498
|
-
],
|
|
499
|
-
"example": "contact"
|
|
1055
|
+
"description": "URL-friendly identifier for the entity schema (Schema-Slug)",
|
|
1056
|
+
"example": "billing_event"
|
|
500
1057
|
},
|
|
501
1058
|
"EntityRelationItem": {
|
|
502
1059
|
"type": "object",
|
|
1060
|
+
"description": "Reference to a related entity",
|
|
503
1061
|
"properties": {
|
|
504
1062
|
"entity_id": {
|
|
505
1063
|
"type": "string",
|
|
506
|
-
"description": "Entity ID for the related contract
|
|
1064
|
+
"description": "Entity ID for the related entity (e.g., contract or order)",
|
|
507
1065
|
"example": "f589786b-3024-43cd-9cb3-5a3c953f2896"
|
|
508
1066
|
}
|
|
509
1067
|
}
|
|
510
1068
|
},
|
|
511
1069
|
"BaseBillingEvent": {
|
|
1070
|
+
"description": "Represents a single financial transaction entry (Buchungssatz) in the billing ledger.\nEach entry is either a debit or a credit, following double-entry accounting principles.\nCommon types include Abschlagszahlung (installment), Zahlungseingang (payment), Rückerstattung (reimbursement), etc.\n",
|
|
512
1071
|
"allOf": [
|
|
513
1072
|
{
|
|
514
1073
|
"$ref": "#/components/schemas/BaseEntity"
|
|
1074
|
+
},
|
|
1075
|
+
{
|
|
1076
|
+
"type": "object",
|
|
1077
|
+
"required": [
|
|
1078
|
+
"type",
|
|
1079
|
+
"billing_amount",
|
|
1080
|
+
"billing_amount_decimal",
|
|
1081
|
+
"billing_currency",
|
|
1082
|
+
"booking_date",
|
|
1083
|
+
"contract"
|
|
1084
|
+
],
|
|
1085
|
+
"properties": {
|
|
1086
|
+
"type": {
|
|
1087
|
+
"type": "string",
|
|
1088
|
+
"description": "The classification of the billing transaction.\nThis field is used to group financial events for reporting or reconciliation.\nCommon examples:\n - installment (Abschlagszahlung)\n - payment (Zahlungseingang)\n - reimbursement (Rückerstattung)\n - dunning_fee (Mahngebühr)\n - chargeback (Lastschrift-Rückgabe)\n - final_bill (Endabrechnung)\n - bonus (Gutschrift)\n - correction (Korrekturbuchung)\n",
|
|
1089
|
+
"example": "installment"
|
|
1090
|
+
},
|
|
1091
|
+
"direction": {
|
|
1092
|
+
"type": "string",
|
|
1093
|
+
"enum": [
|
|
1094
|
+
"debit",
|
|
1095
|
+
"credit"
|
|
1096
|
+
],
|
|
1097
|
+
"description": "The accounting direction of the transaction:\n- debit (Soll): increases the customer’s liability (e.g. invoice issued)\n- credit (Haben): reduces the liability (e.g. payment received)\n\nAutomatically inferred based on event type if not specified.\n",
|
|
1098
|
+
"example": "debit"
|
|
1099
|
+
},
|
|
1100
|
+
"billing_amount": {
|
|
1101
|
+
"type": "integer",
|
|
1102
|
+
"description": "Betrag in Cent (net or gross depending on context)",
|
|
1103
|
+
"example": 10000
|
|
1104
|
+
},
|
|
1105
|
+
"billing_amount_decimal": {
|
|
1106
|
+
"type": "string",
|
|
1107
|
+
"description": "Decimal representation of billing_amount for display or reporting",
|
|
1108
|
+
"example": "100.00"
|
|
1109
|
+
},
|
|
1110
|
+
"billing_currency": {
|
|
1111
|
+
"$ref": "#/components/schemas/Currency"
|
|
1112
|
+
},
|
|
1113
|
+
"external_id": {
|
|
1114
|
+
"type": "string",
|
|
1115
|
+
"description": "External system identifier (e.g. SAP FI/CA document number, Zahlungsavis ID)",
|
|
1116
|
+
"example": "SAP-54321"
|
|
1117
|
+
},
|
|
1118
|
+
"contract": {
|
|
1119
|
+
"type": "object",
|
|
1120
|
+
"description": "Link to the associated Vertragskonto or contract object",
|
|
1121
|
+
"properties": {
|
|
1122
|
+
"$relation": {
|
|
1123
|
+
"type": "array",
|
|
1124
|
+
"items": {
|
|
1125
|
+
"$ref": "#/components/schemas/EntityRelationItem"
|
|
1126
|
+
}
|
|
1127
|
+
}
|
|
1128
|
+
}
|
|
1129
|
+
},
|
|
1130
|
+
"booking_date": {
|
|
1131
|
+
"type": "string",
|
|
1132
|
+
"format": "date",
|
|
1133
|
+
"description": "General ledger booking date (Buchungsdatum) for the billing event.\nUsed to determine when the entry was accounted for in the system.\nApplies to all event types (debits and credits).\nCan be used together with due_date or paid_date\n",
|
|
1134
|
+
"example": "2025-06-15"
|
|
1135
|
+
},
|
|
1136
|
+
"due_date": {
|
|
1137
|
+
"type": "string",
|
|
1138
|
+
"format": "date",
|
|
1139
|
+
"description": "Due date of the invoice or charge (Fälligkeitsdatum)",
|
|
1140
|
+
"example": "2025-06-30"
|
|
1141
|
+
},
|
|
1142
|
+
"paid_date": {
|
|
1143
|
+
"type": "string",
|
|
1144
|
+
"format": "date-time",
|
|
1145
|
+
"description": "Booking date (Zahlungseingang, Wertstellung)",
|
|
1146
|
+
"example": "2025-06-15T10:00:00Z"
|
|
1147
|
+
},
|
|
1148
|
+
"status": {
|
|
1149
|
+
"type": "string",
|
|
1150
|
+
"description": "Status of the billing event. Defaults to closed.",
|
|
1151
|
+
"enum": [
|
|
1152
|
+
"closed",
|
|
1153
|
+
"open"
|
|
1154
|
+
]
|
|
1155
|
+
},
|
|
1156
|
+
"related_event": {
|
|
1157
|
+
"type": "string",
|
|
1158
|
+
"description": "Optional reference to a previous event e.g. a chargeback or a correction to a previous installment",
|
|
1159
|
+
"example": "d4fb2a4e-3f74-4fc4-8fba-6fdaaaa3b08e",
|
|
1160
|
+
"properties": {
|
|
1161
|
+
"$relation": {
|
|
1162
|
+
"type": "array",
|
|
1163
|
+
"items": {
|
|
1164
|
+
"$ref": "#/components/schemas/EntityRelationItem"
|
|
1165
|
+
}
|
|
1166
|
+
}
|
|
1167
|
+
}
|
|
1168
|
+
},
|
|
1169
|
+
"external_link": {
|
|
1170
|
+
"type": "object",
|
|
1171
|
+
"description": "Optional link to an external resource e.g. an invoice in a customer portal",
|
|
1172
|
+
"properties": {
|
|
1173
|
+
"href": {
|
|
1174
|
+
"type": "string",
|
|
1175
|
+
"format": "uri",
|
|
1176
|
+
"description": "URL of the external resource",
|
|
1177
|
+
"example": "https://billing.example.com/invoices/12345"
|
|
1178
|
+
},
|
|
1179
|
+
"title": {
|
|
1180
|
+
"type": "string",
|
|
1181
|
+
"description": "Title of the external resource",
|
|
1182
|
+
"example": "Invoice 12345"
|
|
1183
|
+
}
|
|
1184
|
+
},
|
|
1185
|
+
"required": [
|
|
1186
|
+
"url"
|
|
1187
|
+
]
|
|
1188
|
+
},
|
|
1189
|
+
"attachments": {
|
|
1190
|
+
"type": "object",
|
|
1191
|
+
"description": "Optional reference to e.g. an invoice file associated with the billing event",
|
|
1192
|
+
"properties": {
|
|
1193
|
+
"$relation": {
|
|
1194
|
+
"type": "array",
|
|
1195
|
+
"items": {
|
|
1196
|
+
"$ref": "#/components/schemas/EntityRelationItem"
|
|
1197
|
+
}
|
|
1198
|
+
}
|
|
1199
|
+
}
|
|
1200
|
+
},
|
|
1201
|
+
"note": {
|
|
1202
|
+
"type": "string",
|
|
1203
|
+
"description": "Öffentliche Notiz sichtbar für den Kunden, z.B. auf der Rechnung oder im Kundenportal",
|
|
1204
|
+
"example": "Teilzahlung für Abschlag Juni"
|
|
1205
|
+
},
|
|
1206
|
+
"internal_note": {
|
|
1207
|
+
"type": "string",
|
|
1208
|
+
"description": "Interne Notiz, nur sichtbar für Sachbearbeiter (nicht für Kunden sichtbar)",
|
|
1209
|
+
"example": "Rückmeldung von SAP: Betrag aus Zahlungsavis 2025-06-14 übernommen"
|
|
1210
|
+
}
|
|
1211
|
+
}
|
|
515
1212
|
}
|
|
516
|
-
]
|
|
517
|
-
|
|
1213
|
+
]
|
|
1214
|
+
},
|
|
1215
|
+
"BillingEvent": {
|
|
1216
|
+
"description": "Collection of supported billing event types (Buchungsarten).\nEach type represents a different kind of financial transaction\nthat affects the customer's balance.\n",
|
|
1217
|
+
"oneOf": [
|
|
1218
|
+
{
|
|
1219
|
+
"$ref": "#/components/schemas/InstallmentEvent"
|
|
1220
|
+
},
|
|
1221
|
+
{
|
|
1222
|
+
"$ref": "#/components/schemas/PaymentEvent"
|
|
1223
|
+
},
|
|
1224
|
+
{
|
|
1225
|
+
"$ref": "#/components/schemas/ReimbursementEvent"
|
|
1226
|
+
},
|
|
1227
|
+
{
|
|
1228
|
+
"$ref": "#/components/schemas/DunningFeeEvent"
|
|
1229
|
+
},
|
|
1230
|
+
{
|
|
1231
|
+
"$ref": "#/components/schemas/InvoiceEvent"
|
|
1232
|
+
},
|
|
1233
|
+
{
|
|
1234
|
+
"$ref": "#/components/schemas/FinalBillEvent"
|
|
1235
|
+
},
|
|
1236
|
+
{
|
|
1237
|
+
"$ref": "#/components/schemas/BonusEvent"
|
|
1238
|
+
},
|
|
1239
|
+
{
|
|
1240
|
+
"$ref": "#/components/schemas/CorrectionEvent"
|
|
1241
|
+
},
|
|
1242
|
+
{
|
|
1243
|
+
"$ref": "#/components/schemas/CustomEvent"
|
|
1244
|
+
}
|
|
1245
|
+
]
|
|
1246
|
+
},
|
|
1247
|
+
"BillingEventUpdate": {
|
|
1248
|
+
"description": "Fields to update on an existing billing event.",
|
|
518
1249
|
"type": "object",
|
|
519
|
-
"
|
|
520
|
-
"type",
|
|
521
|
-
"contract",
|
|
522
|
-
"billing_amount",
|
|
523
|
-
"billing_amount_decimal",
|
|
524
|
-
"billing_currency"
|
|
525
|
-
],
|
|
526
|
-
"additionalProperties": true,
|
|
1250
|
+
"minProperties": 1,
|
|
527
1251
|
"properties": {
|
|
1252
|
+
"type": {
|
|
1253
|
+
"type": "string",
|
|
1254
|
+
"description": "Updated billing event type.",
|
|
1255
|
+
"example": "installment"
|
|
1256
|
+
},
|
|
1257
|
+
"direction": {
|
|
1258
|
+
"type": "string",
|
|
1259
|
+
"enum": [
|
|
1260
|
+
"debit",
|
|
1261
|
+
"credit"
|
|
1262
|
+
],
|
|
1263
|
+
"description": "Updated accounting direction.",
|
|
1264
|
+
"example": "debit"
|
|
1265
|
+
},
|
|
528
1266
|
"billing_amount": {
|
|
529
1267
|
"type": "integer",
|
|
530
|
-
"description": "
|
|
531
|
-
"example":
|
|
1268
|
+
"description": "Updated amount in cents.",
|
|
1269
|
+
"example": 10000
|
|
532
1270
|
},
|
|
533
1271
|
"billing_amount_decimal": {
|
|
534
1272
|
"type": "string",
|
|
535
|
-
"description": "
|
|
536
|
-
"example": "100.
|
|
1273
|
+
"description": "Updated decimal representation of billing_amount.",
|
|
1274
|
+
"example": "100.00"
|
|
537
1275
|
},
|
|
538
1276
|
"billing_currency": {
|
|
539
1277
|
"$ref": "#/components/schemas/Currency"
|
|
540
1278
|
},
|
|
541
1279
|
"external_id": {
|
|
542
1280
|
"type": "string",
|
|
543
|
-
"description": "
|
|
1281
|
+
"description": "Updated external system identifier.",
|
|
1282
|
+
"example": "SAP-54321"
|
|
1283
|
+
},
|
|
1284
|
+
"contract": {
|
|
1285
|
+
"type": "object",
|
|
1286
|
+
"description": "Updated link to the associated contract object.",
|
|
1287
|
+
"properties": {
|
|
1288
|
+
"$relation": {
|
|
1289
|
+
"type": "array",
|
|
1290
|
+
"items": {
|
|
1291
|
+
"$ref": "#/components/schemas/EntityRelationItem"
|
|
1292
|
+
}
|
|
1293
|
+
}
|
|
1294
|
+
}
|
|
1295
|
+
},
|
|
1296
|
+
"booking_date": {
|
|
1297
|
+
"type": "string",
|
|
1298
|
+
"format": "date",
|
|
1299
|
+
"description": "Updated general ledger booking date.",
|
|
1300
|
+
"example": "2025-06-15"
|
|
1301
|
+
},
|
|
1302
|
+
"due_date": {
|
|
1303
|
+
"type": "string",
|
|
1304
|
+
"format": "date",
|
|
1305
|
+
"description": "Updated due date.",
|
|
1306
|
+
"example": "2025-06-30"
|
|
1307
|
+
},
|
|
1308
|
+
"paid_date": {
|
|
1309
|
+
"type": "string",
|
|
1310
|
+
"format": "date-time",
|
|
1311
|
+
"description": "Updated payment date.",
|
|
1312
|
+
"example": "2025-06-15T10:00:00Z"
|
|
1313
|
+
},
|
|
1314
|
+
"status": {
|
|
1315
|
+
"type": "string",
|
|
1316
|
+
"enum": [
|
|
1317
|
+
"closed",
|
|
1318
|
+
"open"
|
|
1319
|
+
],
|
|
1320
|
+
"description": "Updated billing event status."
|
|
1321
|
+
},
|
|
1322
|
+
"related_event": {
|
|
1323
|
+
"type": "string",
|
|
1324
|
+
"description": "Updated reference to a previous event.",
|
|
544
1325
|
"example": "d4fb2a4e-3f74-4fc4-8fba-6fdaaaa3b08e"
|
|
545
1326
|
},
|
|
546
|
-
"
|
|
1327
|
+
"external_link": {
|
|
1328
|
+
"type": "object",
|
|
1329
|
+
"description": "Updated link to an external resource.",
|
|
1330
|
+
"properties": {
|
|
1331
|
+
"href": {
|
|
1332
|
+
"type": "string",
|
|
1333
|
+
"format": "uri",
|
|
1334
|
+
"description": "URL of the external resource",
|
|
1335
|
+
"example": "https://billing.example.com/invoices/12345"
|
|
1336
|
+
},
|
|
1337
|
+
"title": {
|
|
1338
|
+
"type": "string",
|
|
1339
|
+
"description": "Title of the external resource",
|
|
1340
|
+
"example": "Invoice 12345"
|
|
1341
|
+
}
|
|
1342
|
+
}
|
|
1343
|
+
},
|
|
1344
|
+
"attachments": {
|
|
1345
|
+
"type": "object",
|
|
1346
|
+
"description": "Updated invoice file relations associated with the billing event.",
|
|
1347
|
+
"properties": {
|
|
1348
|
+
"$relation": {
|
|
1349
|
+
"type": "array",
|
|
1350
|
+
"items": {
|
|
1351
|
+
"$ref": "#/components/schemas/EntityRelationItem"
|
|
1352
|
+
}
|
|
1353
|
+
}
|
|
1354
|
+
}
|
|
1355
|
+
},
|
|
1356
|
+
"note": {
|
|
1357
|
+
"type": "string",
|
|
1358
|
+
"description": "Updated public note visible to the customer.",
|
|
1359
|
+
"example": "Teilzahlung für Abschlag Juni"
|
|
1360
|
+
},
|
|
1361
|
+
"internal_note": {
|
|
1362
|
+
"type": "string",
|
|
1363
|
+
"description": "Updated internal note visible to agents only.",
|
|
1364
|
+
"example": "Rückmeldung von SAP: Betrag aus Zahlungsavis 2025-06-14 übernommen"
|
|
1365
|
+
}
|
|
1366
|
+
}
|
|
1367
|
+
},
|
|
1368
|
+
"InstallmentEvent": {
|
|
1369
|
+
"description": "Installment billing event (Abschlagszahlung).\nRepresents a scheduled partial payment that the customer owes,\ntypically billed monthly for utilities like electricity or gas.\n",
|
|
1370
|
+
"allOf": [
|
|
1371
|
+
{
|
|
1372
|
+
"$ref": "#/components/schemas/BaseBillingEvent"
|
|
1373
|
+
},
|
|
1374
|
+
{
|
|
1375
|
+
"type": "object",
|
|
1376
|
+
"properties": {
|
|
1377
|
+
"type": {
|
|
1378
|
+
"type": "string",
|
|
1379
|
+
"enum": [
|
|
1380
|
+
"installment"
|
|
1381
|
+
],
|
|
1382
|
+
"description": "Event type identifier"
|
|
1383
|
+
}
|
|
1384
|
+
},
|
|
1385
|
+
"example": {
|
|
1386
|
+
"type": "installment",
|
|
1387
|
+
"direction": "debit",
|
|
1388
|
+
"note": "July power & gas installment payment",
|
|
1389
|
+
"status": "open",
|
|
1390
|
+
"booking_date": "2025-07-10",
|
|
1391
|
+
"due_date": "2025-07-10",
|
|
1392
|
+
"billing_amount": 5000,
|
|
1393
|
+
"billing_amount_decimal": "50.00",
|
|
1394
|
+
"billing_currency": "EUR"
|
|
1395
|
+
},
|
|
1396
|
+
"required": [
|
|
1397
|
+
"due_date"
|
|
1398
|
+
]
|
|
1399
|
+
}
|
|
1400
|
+
]
|
|
1401
|
+
},
|
|
1402
|
+
"PaymentEvent": {
|
|
1403
|
+
"description": "Payment received event (Zahlungseingang).\nRepresents money received from the customer, reducing their balance.\nThis is a credit transaction.\n",
|
|
1404
|
+
"allOf": [
|
|
1405
|
+
{
|
|
1406
|
+
"$ref": "#/components/schemas/BaseBillingEvent"
|
|
1407
|
+
},
|
|
1408
|
+
{
|
|
1409
|
+
"type": "object",
|
|
1410
|
+
"properties": {
|
|
1411
|
+
"type": {
|
|
1412
|
+
"type": "string",
|
|
1413
|
+
"enum": [
|
|
1414
|
+
"payment"
|
|
1415
|
+
],
|
|
1416
|
+
"description": "Event type identifier"
|
|
1417
|
+
}
|
|
1418
|
+
},
|
|
1419
|
+
"example": {
|
|
1420
|
+
"type": "payment",
|
|
1421
|
+
"direction": "credit",
|
|
1422
|
+
"note": "Payment reference 001234567",
|
|
1423
|
+
"status": "closed",
|
|
1424
|
+
"booking_date": "2025-06-15",
|
|
1425
|
+
"due_date": "2025-06-15",
|
|
1426
|
+
"paid_date": "2025-06-09T10:00:00Z",
|
|
1427
|
+
"billing_amount": 5000,
|
|
1428
|
+
"billing_amount_decimal": "50.00",
|
|
1429
|
+
"billing_currency": "EUR"
|
|
1430
|
+
}
|
|
1431
|
+
}
|
|
1432
|
+
]
|
|
1433
|
+
},
|
|
1434
|
+
"ReimbursementEvent": {
|
|
1435
|
+
"description": "Reimbursement event (Rückerstattung).\nRepresents a refund to the customer, typically after overpayment\nor billing correction. This is a credit transaction.\n",
|
|
1436
|
+
"allOf": [
|
|
1437
|
+
{
|
|
1438
|
+
"$ref": "#/components/schemas/BaseBillingEvent"
|
|
1439
|
+
},
|
|
1440
|
+
{
|
|
1441
|
+
"type": "object",
|
|
1442
|
+
"properties": {
|
|
1443
|
+
"type": {
|
|
1444
|
+
"type": "string",
|
|
1445
|
+
"enum": [
|
|
1446
|
+
"reimbursement"
|
|
1447
|
+
],
|
|
1448
|
+
"description": "Event type identifier"
|
|
1449
|
+
}
|
|
1450
|
+
},
|
|
1451
|
+
"example": {
|
|
1452
|
+
"type": "reimbursement",
|
|
1453
|
+
"direction": "credit",
|
|
1454
|
+
"billing_amount": 10000,
|
|
1455
|
+
"billing_amount_decimal": "100.00",
|
|
1456
|
+
"billing_currency": "EUR",
|
|
1457
|
+
"note": "Refund due to meter correction",
|
|
1458
|
+
"booking_date": "2025-06-16",
|
|
1459
|
+
"paid_date": "2025-06-18T14:00:00Z"
|
|
1460
|
+
}
|
|
1461
|
+
}
|
|
1462
|
+
]
|
|
1463
|
+
},
|
|
1464
|
+
"DunningFeeEvent": {
|
|
1465
|
+
"description": "Dunning fee event (Mahngebühr).\nRepresents a late payment fee charged to the customer\nafter a payment reminder has been sent. This is a debit transaction.\n",
|
|
1466
|
+
"allOf": [
|
|
1467
|
+
{
|
|
1468
|
+
"$ref": "#/components/schemas/BaseBillingEvent"
|
|
1469
|
+
},
|
|
1470
|
+
{
|
|
1471
|
+
"type": "object",
|
|
1472
|
+
"properties": {
|
|
1473
|
+
"type": {
|
|
1474
|
+
"type": "string",
|
|
1475
|
+
"enum": [
|
|
1476
|
+
"dunning_fee"
|
|
1477
|
+
],
|
|
1478
|
+
"description": "Event type identifier"
|
|
1479
|
+
}
|
|
1480
|
+
},
|
|
1481
|
+
"example": {
|
|
1482
|
+
"type": "dunning_fee",
|
|
1483
|
+
"direction": "debit",
|
|
1484
|
+
"note": "Late fee for April invoice",
|
|
1485
|
+
"status": "open",
|
|
1486
|
+
"booking_date": "2025-06-10",
|
|
1487
|
+
"due_date": "2025-06-10",
|
|
1488
|
+
"billing_amount": 1500,
|
|
1489
|
+
"billing_amount_decimal": "15.00",
|
|
1490
|
+
"billing_currency": "EUR"
|
|
1491
|
+
}
|
|
1492
|
+
}
|
|
1493
|
+
]
|
|
1494
|
+
},
|
|
1495
|
+
"InvoiceEvent": {
|
|
1496
|
+
"allOf": [
|
|
1497
|
+
{
|
|
1498
|
+
"$ref": "#/components/schemas/BaseBillingEvent"
|
|
1499
|
+
},
|
|
1500
|
+
{
|
|
1501
|
+
"type": "object",
|
|
1502
|
+
"properties": {
|
|
1503
|
+
"type": {
|
|
1504
|
+
"type": "string",
|
|
1505
|
+
"enum": [
|
|
1506
|
+
"invoice"
|
|
1507
|
+
]
|
|
1508
|
+
}
|
|
1509
|
+
},
|
|
1510
|
+
"example": {
|
|
1511
|
+
"type": "invoice",
|
|
1512
|
+
"direction": "debit",
|
|
1513
|
+
"billing_amount": 8500,
|
|
1514
|
+
"billing_amount_decimal": "85.00",
|
|
1515
|
+
"billing_currency": "EUR",
|
|
1516
|
+
"note": "Einmalige Rechnung für Zusatzleistung",
|
|
1517
|
+
"booking_date": "2025-06-25",
|
|
1518
|
+
"due_date": "2025-07-01"
|
|
1519
|
+
},
|
|
1520
|
+
"required": [
|
|
1521
|
+
"due_date"
|
|
1522
|
+
]
|
|
1523
|
+
}
|
|
1524
|
+
]
|
|
1525
|
+
},
|
|
1526
|
+
"FinalBillEvent": {
|
|
1527
|
+
"description": "Final bill event (Endabrechnung/Schlussrechnung).\nRepresents the final settlement when a contract ends,\naccounting for actual consumption vs. paid installments.\nCan be either debit (customer owes more) or credit (customer overpaid).\n",
|
|
1528
|
+
"allOf": [
|
|
1529
|
+
{
|
|
1530
|
+
"$ref": "#/components/schemas/BaseBillingEvent"
|
|
1531
|
+
},
|
|
1532
|
+
{
|
|
547
1533
|
"type": "object",
|
|
548
1534
|
"properties": {
|
|
549
|
-
"
|
|
550
|
-
"type": "
|
|
551
|
-
"
|
|
552
|
-
"
|
|
553
|
-
|
|
1535
|
+
"type": {
|
|
1536
|
+
"type": "string",
|
|
1537
|
+
"enum": [
|
|
1538
|
+
"final_bill"
|
|
1539
|
+
],
|
|
1540
|
+
"description": "Event type identifier"
|
|
554
1541
|
}
|
|
1542
|
+
},
|
|
1543
|
+
"example": {
|
|
1544
|
+
"type": "final_bill",
|
|
1545
|
+
"direction": "debit",
|
|
1546
|
+
"billing_amount": 12000,
|
|
1547
|
+
"billing_amount_decimal": "120.00",
|
|
1548
|
+
"billing_currency": "EUR",
|
|
1549
|
+
"note": "Final invoice after contract termination",
|
|
1550
|
+
"booking_date": "2025-06-30"
|
|
555
1551
|
}
|
|
556
1552
|
}
|
|
557
|
-
|
|
1553
|
+
]
|
|
558
1554
|
},
|
|
559
|
-
"
|
|
560
|
-
"description": "
|
|
1555
|
+
"BonusEvent": {
|
|
1556
|
+
"description": "Bonus/credit event (Gutschrift/Bonus).\nRepresents a promotional credit or bonus applied to the customer's account,\nsuch as welcome bonuses or loyalty rewards. This is a credit transaction.\n",
|
|
561
1557
|
"allOf": [
|
|
562
1558
|
{
|
|
563
1559
|
"$ref": "#/components/schemas/BaseBillingEvent"
|
|
@@ -568,30 +1564,25 @@
|
|
|
568
1564
|
"type": {
|
|
569
1565
|
"type": "string",
|
|
570
1566
|
"enum": [
|
|
571
|
-
"
|
|
1567
|
+
"bonus"
|
|
572
1568
|
],
|
|
573
|
-
"description": "
|
|
574
|
-
"example": "installment"
|
|
575
|
-
},
|
|
576
|
-
"due_date": {
|
|
577
|
-
"type": "string",
|
|
578
|
-
"format": "date-time",
|
|
579
|
-
"description": "Date on which the installment is due."
|
|
580
|
-
},
|
|
581
|
-
"paid_date": {
|
|
582
|
-
"type": "string",
|
|
583
|
-
"format": "date-time",
|
|
584
|
-
"description": "Date on which the installment is paid by the customer."
|
|
1569
|
+
"description": "Event type identifier"
|
|
585
1570
|
}
|
|
586
1571
|
},
|
|
587
|
-
"
|
|
588
|
-
"
|
|
589
|
-
|
|
1572
|
+
"example": {
|
|
1573
|
+
"type": "bonus",
|
|
1574
|
+
"direction": "credit",
|
|
1575
|
+
"billing_amount": 1500,
|
|
1576
|
+
"billing_amount_decimal": "15.00",
|
|
1577
|
+
"billing_currency": "EUR",
|
|
1578
|
+
"note": "Welcome bonus",
|
|
1579
|
+
"booking_date": "2025-06-15"
|
|
1580
|
+
}
|
|
590
1581
|
}
|
|
591
1582
|
]
|
|
592
1583
|
},
|
|
593
|
-
"
|
|
594
|
-
"description": "
|
|
1584
|
+
"CorrectionEvent": {
|
|
1585
|
+
"description": "Correction event (Korrekturbuchung).\nRepresents an adjustment to a previous billing entry,\nsuch as correcting an overcharge or undercharge.\nCan be either debit or credit depending on the correction.\n",
|
|
595
1586
|
"allOf": [
|
|
596
1587
|
{
|
|
597
1588
|
"$ref": "#/components/schemas/BaseBillingEvent"
|
|
@@ -602,32 +1593,63 @@
|
|
|
602
1593
|
"type": {
|
|
603
1594
|
"type": "string",
|
|
604
1595
|
"enum": [
|
|
605
|
-
"
|
|
1596
|
+
"correction"
|
|
606
1597
|
],
|
|
607
|
-
"description": "
|
|
608
|
-
"example": "reimbursement"
|
|
609
|
-
},
|
|
610
|
-
"paid_date": {
|
|
611
|
-
"type": "string",
|
|
612
|
-
"format": "date-time",
|
|
613
|
-
"description": "Date on which the customer is reimbursed."
|
|
1598
|
+
"description": "Event type identifier"
|
|
614
1599
|
}
|
|
1600
|
+
},
|
|
1601
|
+
"example": {
|
|
1602
|
+
"type": "correction",
|
|
1603
|
+
"direction": "credit",
|
|
1604
|
+
"billing_amount": 200,
|
|
1605
|
+
"billing_amount_decimal": "2.00",
|
|
1606
|
+
"billing_currency": "EUR",
|
|
1607
|
+
"note": "Corrected previous overcharge",
|
|
1608
|
+
"booking_date": "2025-06-22"
|
|
615
1609
|
}
|
|
616
1610
|
}
|
|
617
1611
|
]
|
|
618
1612
|
},
|
|
619
|
-
"
|
|
620
|
-
"description": "
|
|
621
|
-
"
|
|
1613
|
+
"CustomEvent": {
|
|
1614
|
+
"description": "Custom billing event (Benutzerdefinierte Buchung).\nAllows for organization-specific billing event types not covered\nby the standard types. Use a descriptive type name.\n",
|
|
1615
|
+
"allOf": [
|
|
622
1616
|
{
|
|
623
|
-
"$ref": "#/components/schemas/
|
|
1617
|
+
"$ref": "#/components/schemas/BaseBillingEvent"
|
|
624
1618
|
},
|
|
625
1619
|
{
|
|
626
|
-
"
|
|
1620
|
+
"type": "object",
|
|
1621
|
+
"properties": {
|
|
1622
|
+
"type": {
|
|
1623
|
+
"type": "string",
|
|
1624
|
+
"not": {
|
|
1625
|
+
"enum": [
|
|
1626
|
+
"installment",
|
|
1627
|
+
"payment",
|
|
1628
|
+
"reimbursement",
|
|
1629
|
+
"dunning_fee",
|
|
1630
|
+
"invoice",
|
|
1631
|
+
"final_bill",
|
|
1632
|
+
"bonus",
|
|
1633
|
+
"correction"
|
|
1634
|
+
]
|
|
1635
|
+
},
|
|
1636
|
+
"description": "Custom billing event type (Freitext).\nUse a descriptive identifier for your custom event type.\nExamples: grid_fee_adjustment, meter_rental, special_charge\n"
|
|
1637
|
+
}
|
|
1638
|
+
},
|
|
1639
|
+
"example": {
|
|
1640
|
+
"type": "grid_fee_adjustment",
|
|
1641
|
+
"direction": "debit",
|
|
1642
|
+
"billing_amount": 3200,
|
|
1643
|
+
"billing_amount_decimal": "32.00",
|
|
1644
|
+
"billing_currency": "EUR",
|
|
1645
|
+
"note": "Netznachberechnung für Mai",
|
|
1646
|
+
"booking_date": "2025-06-11"
|
|
1647
|
+
}
|
|
627
1648
|
}
|
|
628
1649
|
]
|
|
629
1650
|
},
|
|
630
1651
|
"Contract": {
|
|
1652
|
+
"description": "Represents a customer contract (Vertrag) for billing purposes.\nContracts are the parent entities for billing events and contain\nbilling configuration such as installment amounts and billing cycles.\n",
|
|
631
1653
|
"allOf": [
|
|
632
1654
|
{
|
|
633
1655
|
"$ref": "#/components/schemas/BaseEntity"
|
|
@@ -637,13 +1659,13 @@
|
|
|
637
1659
|
"properties": {
|
|
638
1660
|
"contract_name": {
|
|
639
1661
|
"type": "string",
|
|
640
|
-
"description": "
|
|
641
|
-
"example": "
|
|
1662
|
+
"description": "Display name of the contract (Vertragsname)",
|
|
1663
|
+
"example": "Stromvertrag Haushalt"
|
|
642
1664
|
},
|
|
643
1665
|
"contract_number": {
|
|
644
1666
|
"type": "string",
|
|
645
|
-
"description": "
|
|
646
|
-
"example": "
|
|
1667
|
+
"description": "Unique contract identifier/number (Vertragsnummer)",
|
|
1668
|
+
"example": "STR-2025-001234"
|
|
647
1669
|
},
|
|
648
1670
|
"status": {
|
|
649
1671
|
"type": "string",
|
|
@@ -658,18 +1680,18 @@
|
|
|
658
1680
|
"expired"
|
|
659
1681
|
],
|
|
660
1682
|
"default": "draft",
|
|
661
|
-
"description": "
|
|
662
|
-
"example": "
|
|
1683
|
+
"description": "Current status of the contract (Vertragsstatus):\n- draft (Entwurf): Contract is being prepared\n- in_approval_process (In Prüfung): Awaiting approval\n- approved (Genehmigt): Approved but not yet active\n- active (Aktiv): Contract is currently active\n- deactivated (Deaktiviert): Temporarily suspended\n- revoked (Widerrufen): Cancelled by customer within cooling-off period\n- terminated (Gekündigt): Contract has been terminated\n- expired (Abgelaufen): Contract term has ended\n",
|
|
1684
|
+
"example": "active"
|
|
663
1685
|
},
|
|
664
1686
|
"description": {
|
|
665
1687
|
"type": "string",
|
|
666
|
-
"description": "
|
|
667
|
-
"example": "
|
|
1688
|
+
"description": "Brief description of the contract terms (Vertragsbeschreibung)",
|
|
1689
|
+
"example": "Haushaltsstrom-Tarif mit 24 Monaten Preisgarantie"
|
|
668
1690
|
},
|
|
669
1691
|
"account_number": {
|
|
670
1692
|
"type": "string",
|
|
671
|
-
"description": "
|
|
672
|
-
"example": "67890"
|
|
1693
|
+
"description": "Customer account number (Kundennummer/Vertragskonto)",
|
|
1694
|
+
"example": "KD-67890"
|
|
673
1695
|
},
|
|
674
1696
|
"branch": {
|
|
675
1697
|
"type": "string",
|
|
@@ -680,33 +1702,34 @@
|
|
|
680
1702
|
"waste_water",
|
|
681
1703
|
"district_heating"
|
|
682
1704
|
],
|
|
683
|
-
"description": "
|
|
1705
|
+
"description": "Utility branch/commodity type (Sparte):\n- power (Strom)\n- gas (Gas)\n- water (Wasser)\n- waste_water (Abwasser)\n- district_heating (Fernwärme)\n",
|
|
684
1706
|
"example": "power"
|
|
685
1707
|
},
|
|
686
1708
|
"billing_address": {
|
|
687
1709
|
"type": "string",
|
|
688
|
-
"description": "
|
|
689
|
-
"example": "123
|
|
1710
|
+
"description": "Billing/invoice address (Rechnungsadresse)",
|
|
1711
|
+
"example": "Musterstraße 123, 50667 Köln"
|
|
690
1712
|
},
|
|
691
1713
|
"delivery_address": {
|
|
692
1714
|
"type": "string",
|
|
693
|
-
"description": "
|
|
694
|
-
"example": "
|
|
1715
|
+
"description": "Delivery/supply point address (Lieferadresse/Verbrauchsstelle)",
|
|
1716
|
+
"example": "Musterstraße 123, 50667 Köln"
|
|
695
1717
|
},
|
|
696
1718
|
"additional_addresses": {
|
|
697
1719
|
"type": "string",
|
|
698
|
-
"description": "
|
|
699
|
-
"example": "
|
|
1720
|
+
"description": "Additional addresses associated with the contract (Weitere Adressen)",
|
|
1721
|
+
"example": "Postfach 456, 50668 Köln"
|
|
700
1722
|
},
|
|
701
1723
|
"termination_date": {
|
|
702
1724
|
"type": "string",
|
|
703
|
-
"
|
|
704
|
-
"
|
|
1725
|
+
"format": "date",
|
|
1726
|
+
"description": "Date when the contract was/will be terminated (Kündigungsdatum)",
|
|
1727
|
+
"example": "2025-12-31"
|
|
705
1728
|
},
|
|
706
1729
|
"termination_reason": {
|
|
707
1730
|
"type": "string",
|
|
708
|
-
"description": "
|
|
709
|
-
"example": "
|
|
1731
|
+
"description": "Reason for contract termination (Kündigungsgrund)",
|
|
1732
|
+
"example": "Kundenkündigung"
|
|
710
1733
|
},
|
|
711
1734
|
"billing_period": {
|
|
712
1735
|
"type": "string",
|
|
@@ -718,20 +1741,20 @@
|
|
|
718
1741
|
"yearly"
|
|
719
1742
|
],
|
|
720
1743
|
"default": "weekly",
|
|
721
|
-
"description": "
|
|
1744
|
+
"description": "Billing cycle frequency (Abrechnungszeitraum):\n- weekly (Wöchentlich)\n- monthly (Monatlich)\n- every_quarter (Vierteljährlich)\n- every_6_months (Halbjährlich)\n- yearly (Jährlich)\n",
|
|
722
1745
|
"example": "monthly"
|
|
723
1746
|
},
|
|
724
1747
|
"billing_duration_amount": {
|
|
725
1748
|
"type": "number",
|
|
726
1749
|
"minimum": 0,
|
|
727
|
-
"description": "
|
|
1750
|
+
"description": "Duration amount for billing period calculation (Abrechnungsdauer)",
|
|
728
1751
|
"example": 30
|
|
729
1752
|
},
|
|
730
1753
|
"renewal_duration_amount": {
|
|
731
1754
|
"type": "number",
|
|
732
1755
|
"minimum": 0,
|
|
733
|
-
"description": "
|
|
734
|
-
"example":
|
|
1756
|
+
"description": "Duration of automatic contract renewal (Verlängerungsdauer)",
|
|
1757
|
+
"example": 12
|
|
735
1758
|
},
|
|
736
1759
|
"renewal_duration_unit": {
|
|
737
1760
|
"type": "string",
|
|
@@ -741,8 +1764,8 @@
|
|
|
741
1764
|
"years"
|
|
742
1765
|
],
|
|
743
1766
|
"default": "months",
|
|
744
|
-
"description": "
|
|
745
|
-
"example": "
|
|
1767
|
+
"description": "Unit for renewal duration (Verlängerungseinheit)",
|
|
1768
|
+
"example": "months"
|
|
746
1769
|
},
|
|
747
1770
|
"notice_time_amount": {
|
|
748
1771
|
"type": "number",
|
|
@@ -758,29 +1781,30 @@
|
|
|
758
1781
|
"years"
|
|
759
1782
|
],
|
|
760
1783
|
"default": "months",
|
|
761
|
-
"description": "
|
|
1784
|
+
"description": "Unit for notice period (Kündigungsfrist-Einheit)",
|
|
762
1785
|
"example": "months"
|
|
763
1786
|
},
|
|
764
1787
|
"start_date": {
|
|
765
1788
|
"type": "string",
|
|
766
|
-
"
|
|
767
|
-
"
|
|
1789
|
+
"format": "date",
|
|
1790
|
+
"description": "Contract start date (Vertragsbeginn)",
|
|
1791
|
+
"example": "2025-01-01"
|
|
768
1792
|
},
|
|
769
1793
|
"billing_due_day": {
|
|
770
1794
|
"type": "integer",
|
|
771
|
-
"description": "
|
|
772
|
-
"minimum":
|
|
1795
|
+
"description": "Day of the month when installments are due (Fälligkeitstag). 0 means no fixed billing day is configured.",
|
|
1796
|
+
"minimum": 0,
|
|
773
1797
|
"maximum": 31,
|
|
774
|
-
"example":
|
|
1798
|
+
"example": 15
|
|
775
1799
|
},
|
|
776
1800
|
"installment_amount": {
|
|
777
1801
|
"type": "integer",
|
|
778
|
-
"description": "
|
|
779
|
-
"example":
|
|
1802
|
+
"description": "Fixed installment amount in cents (Abschlagsbetrag in Cent).\nUses integer representation with 2 decimal precision.\nExample: 10050 = 100.50 EUR\n",
|
|
1803
|
+
"example": 8500
|
|
780
1804
|
},
|
|
781
1805
|
"balance": {
|
|
782
1806
|
"type": "integer",
|
|
783
|
-
"description": "Current balance
|
|
1807
|
+
"description": "Current contract balance in cents (Kontostand in Cent).\nPositive value = customer owes money (Forderung).\nNegative value = customer has credit (Guthaben).\n",
|
|
784
1808
|
"example": 8990
|
|
785
1809
|
},
|
|
786
1810
|
"balance_currency": {
|
|
@@ -791,6 +1815,7 @@
|
|
|
791
1815
|
]
|
|
792
1816
|
},
|
|
793
1817
|
"ContractItem": {
|
|
1818
|
+
"description": "Contract entity with all required system fields populated",
|
|
794
1819
|
"allOf": [
|
|
795
1820
|
{
|
|
796
1821
|
"$ref": "#/components/schemas/Contract"
|
|
@@ -804,17 +1829,365 @@
|
|
|
804
1829
|
"_updated_at"
|
|
805
1830
|
]
|
|
806
1831
|
},
|
|
1832
|
+
"InstallmentAmountValue": {
|
|
1833
|
+
"type": "object",
|
|
1834
|
+
"properties": {
|
|
1835
|
+
"amount": {
|
|
1836
|
+
"type": "integer",
|
|
1837
|
+
"description": "Amount in cents when available or derivable.",
|
|
1838
|
+
"example": 10050
|
|
1839
|
+
},
|
|
1840
|
+
"amount_decimal": {
|
|
1841
|
+
"type": "string",
|
|
1842
|
+
"description": "Decimal amount string when available or derivable.",
|
|
1843
|
+
"example": "100.50"
|
|
1844
|
+
},
|
|
1845
|
+
"currency": {
|
|
1846
|
+
"$ref": "#/components/schemas/Currency"
|
|
1847
|
+
}
|
|
1848
|
+
}
|
|
1849
|
+
},
|
|
1850
|
+
"PriceContext": {
|
|
1851
|
+
"type": "object",
|
|
1852
|
+
"properties": {
|
|
1853
|
+
"price_id": {
|
|
1854
|
+
"type": "string"
|
|
1855
|
+
},
|
|
1856
|
+
"price_title": {
|
|
1857
|
+
"type": "string"
|
|
1858
|
+
},
|
|
1859
|
+
"pricing_model": {
|
|
1860
|
+
"type": "string"
|
|
1861
|
+
},
|
|
1862
|
+
"unit_amount_gross_decimal": {
|
|
1863
|
+
"type": "string"
|
|
1864
|
+
},
|
|
1865
|
+
"unit_amount_net_decimal": {
|
|
1866
|
+
"type": "string"
|
|
1867
|
+
},
|
|
1868
|
+
"before_discount_unit_amount_gross_decimal": {
|
|
1869
|
+
"type": "string"
|
|
1870
|
+
},
|
|
1871
|
+
"before_discount_unit_amount_net_decimal": {
|
|
1872
|
+
"type": "string"
|
|
1873
|
+
},
|
|
1874
|
+
"unit_discount_amount_decimal": {
|
|
1875
|
+
"type": "string"
|
|
1876
|
+
},
|
|
1877
|
+
"unit_discount_amount_net_decimal": {
|
|
1878
|
+
"type": "string"
|
|
1879
|
+
},
|
|
1880
|
+
"currency": {
|
|
1881
|
+
"$ref": "#/components/schemas/Currency"
|
|
1882
|
+
},
|
|
1883
|
+
"billing_period": {
|
|
1884
|
+
"type": "string"
|
|
1885
|
+
},
|
|
1886
|
+
"unit": {
|
|
1887
|
+
"type": "string"
|
|
1888
|
+
},
|
|
1889
|
+
"has_discount": {
|
|
1890
|
+
"type": "boolean"
|
|
1891
|
+
},
|
|
1892
|
+
"is_dynamic_tariff": {
|
|
1893
|
+
"type": "boolean"
|
|
1894
|
+
},
|
|
1895
|
+
"dynamic_tariff": {
|
|
1896
|
+
"$ref": "#/components/schemas/DynamicTariffPriceContext"
|
|
1897
|
+
}
|
|
1898
|
+
}
|
|
1899
|
+
},
|
|
1900
|
+
"DynamicTariffPriceContext": {
|
|
1901
|
+
"type": "object",
|
|
1902
|
+
"properties": {
|
|
1903
|
+
"mode": {
|
|
1904
|
+
"type": "string"
|
|
1905
|
+
},
|
|
1906
|
+
"interval": {
|
|
1907
|
+
"type": "string"
|
|
1908
|
+
},
|
|
1909
|
+
"average_price_decimal": {
|
|
1910
|
+
"type": "string"
|
|
1911
|
+
},
|
|
1912
|
+
"markup_amount_decimal": {
|
|
1913
|
+
"type": "string"
|
|
1914
|
+
},
|
|
1915
|
+
"markup_amount_net_decimal": {
|
|
1916
|
+
"type": "string"
|
|
1917
|
+
},
|
|
1918
|
+
"markup_amount_gross_decimal": {
|
|
1919
|
+
"type": "string"
|
|
1920
|
+
},
|
|
1921
|
+
"market_price_decimal": {
|
|
1922
|
+
"type": "string"
|
|
1923
|
+
},
|
|
1924
|
+
"market_price_currency": {
|
|
1925
|
+
"$ref": "#/components/schemas/Currency"
|
|
1926
|
+
},
|
|
1927
|
+
"market": {
|
|
1928
|
+
"type": "string"
|
|
1929
|
+
},
|
|
1930
|
+
"bidding_zone": {
|
|
1931
|
+
"type": "string"
|
|
1932
|
+
},
|
|
1933
|
+
"timestamp": {
|
|
1934
|
+
"type": "string"
|
|
1935
|
+
}
|
|
1936
|
+
}
|
|
1937
|
+
},
|
|
1938
|
+
"ConfigurationHistoryContext": {
|
|
1939
|
+
"type": "object",
|
|
1940
|
+
"properties": {
|
|
1941
|
+
"base_price": {
|
|
1942
|
+
"$ref": "#/components/schemas/PriceContext"
|
|
1943
|
+
},
|
|
1944
|
+
"working_price": {
|
|
1945
|
+
"$ref": "#/components/schemas/PriceContext"
|
|
1946
|
+
}
|
|
1947
|
+
}
|
|
1948
|
+
},
|
|
1949
|
+
"ConfigurationHistoryRow": {
|
|
1950
|
+
"type": "object",
|
|
1951
|
+
"required": [
|
|
1952
|
+
"event_id",
|
|
1953
|
+
"org_id",
|
|
1954
|
+
"entity_type",
|
|
1955
|
+
"entity_id",
|
|
1956
|
+
"change_type",
|
|
1957
|
+
"schema_version",
|
|
1958
|
+
"changed_at",
|
|
1959
|
+
"created_at",
|
|
1960
|
+
"source",
|
|
1961
|
+
"new_value"
|
|
1962
|
+
],
|
|
1963
|
+
"properties": {
|
|
1964
|
+
"event_id": {
|
|
1965
|
+
"type": "string"
|
|
1966
|
+
},
|
|
1967
|
+
"org_id": {
|
|
1968
|
+
"type": "string"
|
|
1969
|
+
},
|
|
1970
|
+
"entity_type": {
|
|
1971
|
+
"type": "string",
|
|
1972
|
+
"enum": [
|
|
1973
|
+
"contract",
|
|
1974
|
+
"billing_account"
|
|
1975
|
+
]
|
|
1976
|
+
},
|
|
1977
|
+
"entity_id": {
|
|
1978
|
+
"type": "string"
|
|
1979
|
+
},
|
|
1980
|
+
"change_type": {
|
|
1981
|
+
"type": "string",
|
|
1982
|
+
"enum": [
|
|
1983
|
+
"installment_amount_changed"
|
|
1984
|
+
]
|
|
1985
|
+
},
|
|
1986
|
+
"schema_version": {
|
|
1987
|
+
"type": "integer",
|
|
1988
|
+
"example": 1
|
|
1989
|
+
},
|
|
1990
|
+
"effective_at": {
|
|
1991
|
+
"type": "string",
|
|
1992
|
+
"format": "date-time"
|
|
1993
|
+
},
|
|
1994
|
+
"changed_at": {
|
|
1995
|
+
"type": "string",
|
|
1996
|
+
"format": "date-time"
|
|
1997
|
+
},
|
|
1998
|
+
"created_at": {
|
|
1999
|
+
"type": "string",
|
|
2000
|
+
"format": "date-time"
|
|
2001
|
+
},
|
|
2002
|
+
"source": {
|
|
2003
|
+
"type": "string",
|
|
2004
|
+
"enum": [
|
|
2005
|
+
"portal",
|
|
2006
|
+
"epilot",
|
|
2007
|
+
"erp",
|
|
2008
|
+
"system",
|
|
2009
|
+
"api",
|
|
2010
|
+
"external",
|
|
2011
|
+
"journey",
|
|
2012
|
+
"automation",
|
|
2013
|
+
"unknown"
|
|
2014
|
+
]
|
|
2015
|
+
},
|
|
2016
|
+
"source_label": {
|
|
2017
|
+
"type": "string"
|
|
2018
|
+
},
|
|
2019
|
+
"source_system": {
|
|
2020
|
+
"type": "string"
|
|
2021
|
+
},
|
|
2022
|
+
"source_reference": {
|
|
2023
|
+
"type": "string"
|
|
2024
|
+
},
|
|
2025
|
+
"previous_value": {
|
|
2026
|
+
"nullable": true,
|
|
2027
|
+
"allOf": [
|
|
2028
|
+
{
|
|
2029
|
+
"$ref": "#/components/schemas/InstallmentAmountValue"
|
|
2030
|
+
}
|
|
2031
|
+
]
|
|
2032
|
+
},
|
|
2033
|
+
"new_value": {
|
|
2034
|
+
"$ref": "#/components/schemas/InstallmentAmountValue"
|
|
2035
|
+
},
|
|
2036
|
+
"context": {
|
|
2037
|
+
"$ref": "#/components/schemas/ConfigurationHistoryContext"
|
|
2038
|
+
}
|
|
2039
|
+
}
|
|
2040
|
+
},
|
|
2041
|
+
"ConfigurationHistoryResponse": {
|
|
2042
|
+
"type": "object",
|
|
2043
|
+
"required": [
|
|
2044
|
+
"history",
|
|
2045
|
+
"total"
|
|
2046
|
+
],
|
|
2047
|
+
"properties": {
|
|
2048
|
+
"history": {
|
|
2049
|
+
"type": "array",
|
|
2050
|
+
"items": {
|
|
2051
|
+
"$ref": "#/components/schemas/ConfigurationHistoryRow"
|
|
2052
|
+
}
|
|
2053
|
+
},
|
|
2054
|
+
"total": {
|
|
2055
|
+
"type": "integer"
|
|
2056
|
+
}
|
|
2057
|
+
}
|
|
2058
|
+
},
|
|
2059
|
+
"PricingInformationBalance": {
|
|
2060
|
+
"type": "object",
|
|
2061
|
+
"properties": {
|
|
2062
|
+
"amount": {
|
|
2063
|
+
"type": "integer",
|
|
2064
|
+
"example": 8990
|
|
2065
|
+
},
|
|
2066
|
+
"amount_decimal": {
|
|
2067
|
+
"type": "string",
|
|
2068
|
+
"example": "89.90"
|
|
2069
|
+
},
|
|
2070
|
+
"currency": {
|
|
2071
|
+
"$ref": "#/components/schemas/Currency"
|
|
2072
|
+
}
|
|
2073
|
+
}
|
|
2074
|
+
},
|
|
2075
|
+
"ContractPricingSchedule": {
|
|
2076
|
+
"type": "object",
|
|
2077
|
+
"required": [
|
|
2078
|
+
"inferred"
|
|
2079
|
+
],
|
|
2080
|
+
"properties": {
|
|
2081
|
+
"billing_due_day": {
|
|
2082
|
+
"type": "integer",
|
|
2083
|
+
"description": "Day of the month when installments are due. 0 means no fixed billing day is configured.",
|
|
2084
|
+
"minimum": 0,
|
|
2085
|
+
"maximum": 31
|
|
2086
|
+
},
|
|
2087
|
+
"billing_period": {
|
|
2088
|
+
"type": "string",
|
|
2089
|
+
"enum": [
|
|
2090
|
+
"weekly",
|
|
2091
|
+
"monthly",
|
|
2092
|
+
"every_quarter",
|
|
2093
|
+
"every_6_months",
|
|
2094
|
+
"yearly"
|
|
2095
|
+
]
|
|
2096
|
+
},
|
|
2097
|
+
"installments_per_year": {
|
|
2098
|
+
"type": "integer"
|
|
2099
|
+
},
|
|
2100
|
+
"inferred": {
|
|
2101
|
+
"type": "boolean"
|
|
2102
|
+
}
|
|
2103
|
+
}
|
|
2104
|
+
},
|
|
2105
|
+
"ContractPricingInformation": {
|
|
2106
|
+
"type": "object",
|
|
2107
|
+
"required": [
|
|
2108
|
+
"entity_type",
|
|
2109
|
+
"entity_id",
|
|
2110
|
+
"history"
|
|
2111
|
+
],
|
|
2112
|
+
"properties": {
|
|
2113
|
+
"entity_type": {
|
|
2114
|
+
"type": "string",
|
|
2115
|
+
"enum": [
|
|
2116
|
+
"contract"
|
|
2117
|
+
]
|
|
2118
|
+
},
|
|
2119
|
+
"entity_id": {
|
|
2120
|
+
"type": "string"
|
|
2121
|
+
},
|
|
2122
|
+
"title": {
|
|
2123
|
+
"type": "string"
|
|
2124
|
+
},
|
|
2125
|
+
"current_installment_amount": {
|
|
2126
|
+
"$ref": "#/components/schemas/InstallmentAmountValue"
|
|
2127
|
+
},
|
|
2128
|
+
"context": {
|
|
2129
|
+
"$ref": "#/components/schemas/ConfigurationHistoryContext"
|
|
2130
|
+
},
|
|
2131
|
+
"balance": {
|
|
2132
|
+
"$ref": "#/components/schemas/PricingInformationBalance"
|
|
2133
|
+
},
|
|
2134
|
+
"schedule": {
|
|
2135
|
+
"$ref": "#/components/schemas/ContractPricingSchedule"
|
|
2136
|
+
},
|
|
2137
|
+
"pending_installment_change": {
|
|
2138
|
+
"type": "boolean"
|
|
2139
|
+
},
|
|
2140
|
+
"history": {
|
|
2141
|
+
"type": "array",
|
|
2142
|
+
"items": {
|
|
2143
|
+
"$ref": "#/components/schemas/ConfigurationHistoryRow"
|
|
2144
|
+
}
|
|
2145
|
+
}
|
|
2146
|
+
}
|
|
2147
|
+
},
|
|
2148
|
+
"BillingAccountPricingInformation": {
|
|
2149
|
+
"type": "object",
|
|
2150
|
+
"required": [
|
|
2151
|
+
"entity_type",
|
|
2152
|
+
"entity_id",
|
|
2153
|
+
"contracts"
|
|
2154
|
+
],
|
|
2155
|
+
"properties": {
|
|
2156
|
+
"entity_type": {
|
|
2157
|
+
"type": "string",
|
|
2158
|
+
"enum": [
|
|
2159
|
+
"billing_account"
|
|
2160
|
+
]
|
|
2161
|
+
},
|
|
2162
|
+
"entity_id": {
|
|
2163
|
+
"type": "string"
|
|
2164
|
+
},
|
|
2165
|
+
"title": {
|
|
2166
|
+
"type": "string"
|
|
2167
|
+
},
|
|
2168
|
+
"balance": {
|
|
2169
|
+
"$ref": "#/components/schemas/PricingInformationBalance"
|
|
2170
|
+
},
|
|
2171
|
+
"contracts": {
|
|
2172
|
+
"type": "array",
|
|
2173
|
+
"items": {
|
|
2174
|
+
"$ref": "#/components/schemas/ContractPricingInformation"
|
|
2175
|
+
}
|
|
2176
|
+
}
|
|
2177
|
+
}
|
|
2178
|
+
},
|
|
807
2179
|
"Balance": {
|
|
808
2180
|
"type": "object",
|
|
2181
|
+
"description": "Customer balance summary (Kontostandübersicht).\nRepresents the aggregated balance across all contracts and orders for a customer.\n",
|
|
809
2182
|
"properties": {
|
|
810
2183
|
"balance": {
|
|
811
2184
|
"type": "integer",
|
|
812
|
-
"description": "
|
|
2185
|
+
"description": "Total customer balance in cents (Gesamtkontostand in Cent).\nPositive = customer owes money (Offener Betrag).\nNegative = customer has credit (Guthaben).\n",
|
|
813
2186
|
"example": 8990
|
|
814
2187
|
},
|
|
815
2188
|
"balance_decimal": {
|
|
816
2189
|
"type": "string",
|
|
817
|
-
"description": "
|
|
2190
|
+
"description": "Balance as decimal string for display (Kontostand als Dezimalzahl).\nFormatted with 2 decimal places.\n",
|
|
818
2191
|
"example": "89.90"
|
|
819
2192
|
},
|
|
820
2193
|
"balance_currency": {
|
|
@@ -824,7 +2197,7 @@
|
|
|
824
2197
|
},
|
|
825
2198
|
"Currency": {
|
|
826
2199
|
"type": "string",
|
|
827
|
-
"description": "Currency code in ISO 4217 format",
|
|
2200
|
+
"description": "Currency code in ISO 4217 format (Währungscode).\nCommon values: EUR (Euro), CHF (Swiss Franc)\n",
|
|
828
2201
|
"example": "EUR"
|
|
829
2202
|
}
|
|
830
2203
|
}
|