generated from peter-evans/swagger-github-pages
-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathcrm-sync-api-doc.yaml
433 lines (424 loc) · 18 KB
/
crm-sync-api-doc.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
openapi: 3.0.0
info:
version: 4.4.3
title: goTom CRM Sync API
x-explorer-enabled: false # this disables the "try me" button for test requests on readme.com
paths:
/app-api/crm-sync-import-external-crm-id/update-customer:
post:
tags: [Customer]
summary: Create or update (Upsert) a customer with addresses and contact persons
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
responses:
'200':
description: Customer was created / updated
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/UpdateCustomerResponse'
- type: object
properties:
errorLogs:
type: object
example: null
'202':
description: Customer has not been processed yet (check /error-logs/ endpoint for status)
content:
application/json:
schema:
allOf:
- type: object
properties:
jobId:
example: 123
jobAlreadyFinished:
example: false
reason:
example: blocking_timeout
'400':
description: There was an issue with updating the customer
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/UpdateCustomerResponse"
- type: object
properties:
error:
type: object
properties:
msg:
description: If the customer data fails validation before further processing e.g. is more severely badly formatted like no data or customer sent at all or invalid JSON format.
type: string
example: Request had no body
reason:
description: Indication of what is the status of the processed job. 'data_error' means there was an error when processing data, please check logs. 'blocking_timeout' means job couldn't be processed before returning response. 'blocking_buried' and 'queue_internal' are more severe internal errors.
enum: ['data_error', 'blocking_timeout','blocking_buried','queue_internal']
type: string
example: 'data_error'
/app-api/crm-sync-import-external-crm-id/error-logs/{jobId}:
get:
tags: [Customer]
summary: Read customer import logs
description: Read customer import logs to see the current status of processing
parameters:
- in: path
name: jobId
schema:
type: integer
required: true
responses:
'200':
description: If there are found logs they have been returned
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerErrorLogResponse'
'404':
description: No job found for this jobId.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerErrorLogResponse'
components:
schemas:
CustomerErrorLogResponse:
description: The logs available when retrieving the customer
type: object
properties:
jobStatus:
description: The status of the job in the queue, where JOB_STATUS_FINISHED_OK means all ok
enum: ['NO_JOB_FOUND', 'JOB_STATUS_WAITING', 'JOB_STATUS_FINISHED_OK', 'JOB_STATUS_FINISHED_ERROR']
type: string
sentJobId:
description: job Id sent by you.
type: integer
example: 12
allOf:
- $ref: "#/components/schemas/CrmSyncErrorLogsMixin"
UpdateCustomerResponse:
description: Response for successful, failed and unfinished costumer update jobs.
type: object
properties:
jobId:
description: The job id. Currently this id can reset upon reboot of the server e.g. is not necessarily unique.
type: integer
example: 123
jobAlreadyFinished:
description: Whether or not the job was able to return synchronously e.g. if true means the job was processed before the response was returned and thus the logs are returned as well in the response. False means the job still awaits processing.
type: boolean
example: true
allOf:
- $ref: "#/components/schemas/CrmSyncErrorLogsMixin"
CrmSyncErrorLogsMixin:
description: used internally to keep DRY
type: object
properties:
errorLogs:
type: object
nullable: true
properties:
api_error:
description: The logs that show what lead to an error when processing the request e.g. missing externalCrmId on data.
type: string
example: Class AppBundle\Entity\CustomerAddress expects the key externalCrmId to be present in data. Only "title,firm,softDeleted,externalId" received
warningLogs:
description: The log that shows what lead to a warning when processing the request e.g. providing not all possible fields with their values or providing fields with values that are not configured and thus not read.
nullable: true
type: array
example: ['Data key contactPersons provided for type AppBundle\Entity\Customer, but is not a configured attribute. contactPersons will be ignored. Let the client know, that this attribute should be removed from his request.','Data key id not provided for type AppBundle\Entity\Customer, but is a configured attribute. Did the client forget to send it?']
items:
type: string
Customer: # if you update this, be sure to update as well the other yaml files
properties:
customer:
description: Customer Object
type: object
required: [externalCrmId, firm, status, statusEc, language, mainAddress]
properties:
externalCrmId:
description: External CRM Id for referencing the customer, the important ID of the CRM sync API.
type: string
externalId:
description: Not to be confused with externalCrmId, externalId is not important for the CRM sync API. It could be used to reference again something else.
type: string
firm:
description: Name of the customer
type: string
mwst:
description: VAT Number
type: string
note:
description: Note on the client
type: string
status:
description: States if the customer is active or inactive. 1 = active, 0 = inactive
type: integer
enum: [1, 0]
statusEc:
description: Customer type. 1 = Customer, 2 = Intermediator, 3 = Agency, 5 = Publisher (Only available with marketer module activated)
type: integer
enum: [1, 2, 3, 5]
language:
description: Preferred language for this customer
type: string
enum: [de, en, fr, it]
bankAccountNumber:
description: Bank Account Number for this customer
type: string
bankIBANNumber:
description: IBAN for this customer
type: string
bankClearingNumber:
description: Bank Clearing for this customer
type: string
bankName:
description: Bank name for this customer
type: string
searchstring:
description: Search help to find this customer easier with other name(s)
type: string
vatType:
description: VAT Type (0 = Standard, 2 = VAT exempt, 3 = VAT reduced, 7 = VAT exempt embassy)
type: integer
default: 0
enum: [0, 2, 3, 7]
softDeleted:
description: If this customer should be treated as deleted.
example: false
type: boolean
default: false
commission:
description: Defines the default commissions for an agency or intermediator. Has no effect on statusEc != 2 or 3.
type: object
required: [bkCommission, vmkCommission, type]
properties:
bkCommission:
description: Agency Commission aka BK (Beraterkommission) aka AP (Agenturprovision) in percent
type: number
vmkCommission:
description: Intermediator Commission aka VMK (Vermittlerkommission) aka DBE (Direktbuchungsentschädigung) aka 2. Provision aka 2. Agentur-Provision in percent
type: number
type:
description: |
Type of commission.
0 = Standard (default) = bkCommission direct / vmkCommission direct
2 = bkCommission direct / vmkCommission indirect (Accrual / Rückstellung)
3 = bkCommission separate / vmkCommission indirect (Accrual / Rückstellung)
4 = vmkCommission separate
type: integer
enum: [0, 2, 3, 4]
industry:
description: Customer industry
type: object
required: [externalCrmId]
properties:
externalCrmId:
description: External CRM Id for referencing the industry
type: string
name:
description: Name of the industry. Will update the industry name for every customer that uses the same industry.
type: string
addresses:
description: Customer addresses. Addresses added through this endpoint are merged with existing ones (upsert). Deleting existing addresses is not supported.
type: array
items:
type: object
required: [externalCrmId, title, firm, zip, place, country]
properties:
externalCrmId:
description: External CRM Id for referencing the address
type: string
title:
description: Name/Label
type: string
firm:
description: Company
type: string
department:
description: Departement
type: string
street:
description: Street
type: string
number:
description: Street number
type: string
adresstext:
description: Addition
type: string
zip:
description: Zip code
type: string
place:
description: City/Place
type: string
country:
description: |
Country (ISO 3166-1 alpha-2 Code) like "CH" / "DE" / "AT"
https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
type: string
externalId:
description: External Id
type: integer
sendingRule:
description: Invoice sending rule. Default is defined via admin center setting
type: string
enum: ['email', 'post']
sendingRuleAddresses:
description: E-Mail addresses for invoice sending. Only useful with sendingRule "email".
type: array
items:
type: string
softDeleted:
description: If this address should be treated as deleted.
example: false
type: boolean
default: false
mainAddress:
description: Reference to the main address for this customer
type: object
required: [externalCrmId]
properties:
externalCrmId:
description: External CRM Id for referencing the address. If a record with this externalCrmId does not exist, an empty one will be created.
type: string
contacts:
description: Customer contacts. Contacts added through this endpoint are merged with existing ones (upsert). Deleting existing contacts is not supported, as they may already be referenced elsewhere, which could cause errors. This functionality replaces the deprecated <s>contactPersons</s> property.
type: array
items:
type: object
required: [externalCrmId, peopleGender, peopleLastname, peopleName]
properties:
externalCrmId:
description: External CRM Id for referencing the contact
type: string
peopleGender:
description: Gender. "M" = male, "F" = female, "D" = divers
type: string
enum: ['M', 'F', 'D']
peopleLastname:
description: Lastname
type: string
peopleName:
description: Surname
type: string
peoplePhone:
description: Phone Number
type: string
peopleNatel:
description: Mobile Number
type: string
peopleEmail:
description: E-Mail
type: string
peopleStatus:
description: Status active/inactive. "A" = active. "N" = not active.
type: string
default: A
enum: ['A', 'N']
lead:
description: |
Mark contact as lead.
* `true`: contact is marked as lead.
* `false`: contact is not marked as lead.
type: boolean
default: false
jobFunctions:
description: Function name
type: array
items:
type: object
required: [lang, function]
properties:
lang:
description: Language in which the function is saved (deprecated). Use "de" always
type: string
enum: ['de']
function:
description: The function name
type: string
tags:
description: Customer tags
type: array
items:
type: object
required: [externalCrmId]
properties:
externalCrmId:
description: External CRM Id for referencing the tag
type: string
name:
description: Name of the tag (if this property is set, it will update the name of the tag for every customer)
type: string
references:
description: Customer references
type: array
items:
type: object
required: [externalCrmId]
properties:
externalCrmId:
description: External CRM Id for referencing the customer reference
type: string
referenceType:
description: Type of the reference
type: string
referenceValue:
description: Value of the reference
type: string
consultants:
description: Customer consultants
type: array
items:
type: object
required: [email]
properties:
email:
description: E-Mail address of consultant
type: string
paymentTerm:
description: Payment term for customer
type: object
required: [externalCrmId]
properties:
externalCrmId:
description: External CRM Id for referencing the payment term
type: string
days:
description: Amount of days until the invoice has to be paid
type: integer
name:
description: Name of the payment term
type: string
cashDiscountDays:
description: How many days that a cash discount (skonto) can be applied
type: integer
cashDiscountPercent:
description: Percentage of cash discount (skonto) that can be applied
type: number
billingPhrases:
description: Text to print on invoice in different languages
type: object
properties:
de:
description: German text
type: string
en:
description: English text
type: string
fr:
description: French text
type: string
it:
description: Italian text
type: string
parameters:
{}
responses:
{}