# Validate & Update ## Adressprocessing Ablauf Der Batch-Prozess besteht aus den folgenden Schritten: {% stepper %} {% step %} :inbox-full: [Erstellung eines Batches](#create) {% endstep %} {% step %} Daten bereitstellen * :upload: [Variante A – FileUpload](#fileupload) * :file-circle-plus: [Variante B – AddRecords](#addrecords) {% endstep %} {% step %} :play: [Start der Verarbeitung](#start) {% endstep %} {% step %} :magnifying-glass: [Details abrufen](#detail) {% endstep %} {% step %} Download der Ergebnisse * :download: [Variante A – FileDownload](#filedownload) * :memo-circle-check: [Variante B – GetRecords](#getrecords) {% endstep %} {% endstepper %} ## Funktionen ### :inbox-full: Create Ein Batch ist die Hülle, die als Rahmen für die Verarbeitung dient. Für jeden Adresslauf muss ein neuer Batch erstellt werden.
Request-ParameterErklärung
orderNrBenutzerdefinierte Referenznummer, die zur eindeutigen Identifikation einer Bestellung vergeben werden kann, z. B. für spätere Rückfragen oder Abklärungen.
dataGroupCode

Eindeutige Identifikation der Data Group.

→ Wird bei der Erstellung der Data Group (/dataGroups/create) generiert. Muss hier referenziert werden.

userDescriptionName der Kampagne oder des Batches.
processId

Systemseitig vergebene ID für den Prozess.

→ Standardwert: 400

processingDateDefiniert, wann der Batch gestartet werden soll (z.B. Batch heute erstellen, Verarbeitung am Wochenende).
businessCase

Definiert den Prozessverlauf basierend auf vordefinierten Presets.

→ Standardwert: 0

product

Auswahl des gewünschten Produkts, z.B.:

  • 1 Enrich: Anreicherung bestehender Daten.
  • 2 Reference: Nur Analyse der Daten gegen die verfügbaren Datenquellen, keine Datenänderungen → Ergebnis: Analysebericht von multisource und gegebenenfalls der Schweizerischen Post.
  • 3 AdressUpdate: Aktualisierung bestehender Adressen.
notificationEmailE-Mail-Adresse für Benachrichtigungen. Falls keine spezifische E-Mail-Adresse hinterlegt ist, wird standardmässig die E-Mail-Adresse des aktuell eingeloggten Benutzers verwendet.
## POST /addressprocessing/Create > ```json {"openapi":"3.0.1","info":{"title":"multisource•api ","version":"v2"},"tags":[{"name":"Batch"}],"servers":[{"url":"https://api.multisource.ch/v2","description":"Production - v2"},{"url":"https://api.multisource.ch","description":"Production"},{"url":"https://apitep.multisource.ch","description":"Pre-Production Testing"}],"security":[{"auth-key":[]}],"components":{"securitySchemes":{"auth-key":{"type":"apiKey","description":"API Key required for authorized endpoints","name":"auth-key","in":"header"}},"schemas":{"BatchCreateRequest":{"required":["orderNr","userDescription","processId","product"],"type":"object","properties":{"orderNr":{"type":"string"},"dataGroupId":{"type":"integer","format":"int32"},"dataGroupCode":{"type":"string","nullable":true},"userDescription":{"type":"string","nullable":true},"processId":{"type":"integer","format":"int32"},"businessCase":{"type":"integer","format":"int32"},"product":{"$ref":"#/components/schemas/ProductCase"},"notificationEmail":{"type":"string"},"processingDate":{"type":"string","format":"date-time"},"runParallel":{"type":"boolean"},"settings":{"type":"object","additionalProperties":{"type":"string"}}}},"ProductCase":{"enum":["1 = Enrich","2 = Reference","3 = AddressUpdate"],"type":"integer"},"BatchDetail":{"type":"object","properties":{"batchId":{"type":"integer","format":"int32"},"batchUniqueId":{"type":"string","format":"uuid"},"processGroup":{"type":"integer","format":"int32"},"insertBy":{"type":"string","nullable":true},"insertAt":{"type":"string","format":"date-time","nullable":true},"description":{"type":"string","nullable":true},"userDescription":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date-time","nullable":true},"endDate":{"type":"string","format":"date-time","nullable":true},"processingDate":{"type":"string","format":"date-time","nullable":true},"duration":{"type":"integer","format":"int32","nullable":true},"errorCount":{"type":"integer","format":"int32","nullable":true},"warningCount":{"type":"integer","format":"int32","nullable":true},"warningRejectCount":{"type":"integer","format":"int32","nullable":true},"createTypeId":{"type":"integer","format":"int32"},"runSingle":{"type":"boolean","nullable":true},"agent":{"type":"string","nullable":true},"datagroupId":{"type":"integer","format":"int32","nullable":true},"orderNr":{"type":"string","nullable":true},"settings":{"type":"object","additionalProperties":{"type":"string"},"nullable":true},"files":{"type":"array","items":{"$ref":"#/components/schemas/BatchFile"}},"steps":{"type":"array","items":{"$ref":"#/components/schemas/BatchStep"}}}},"BatchFile":{"type":"object","properties":{"fileUniqueId":{"type":"string","format":"uuid"},"direction":{"type":"string","nullable":true},"fileName":{"type":"string","nullable":true},"processFileDetection":{"type":"string","nullable":true},"description":{"type":"string","nullable":true}}},"BatchStep":{"type":"object","properties":{"stepId":{"type":"integer","format":"int32"},"status":{"type":"string","nullable":true},"sortOrder":{"type":"integer","format":"int32","nullable":true},"startDate":{"type":"string","format":"date-time","nullable":true},"endDate":{"type":"string","format":"date-time","nullable":true},"duration":{"type":"integer","format":"int32","nullable":true},"errorCount":{"type":"integer","format":"int32","nullable":true},"warningCount":{"type":"integer","format":"int32","nullable":true},"warningRejectCount":{"type":"integer","format":"int32","nullable":true},"recordCount":{"type":"integer","format":"int32","nullable":true},"description":{"type":"string","nullable":true},"modulUniqueId":{"type":"string","format":"uuid","nullable":true},"descriptionAdd":{"type":"string","nullable":true}}}}},"paths":{"/addressprocessing/Create":{"post":{"tags":["Batch"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchCreateRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/BatchCreateRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/BatchCreateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/BatchDetail"}},"application/json":{"schema":{"$ref":"#/components/schemas/BatchDetail"}},"text/json":{"schema":{"$ref":"#/components/schemas/BatchDetail"}}}}}}}}} ``` ### :upload: FileUpload Fügt eine Datei zur Verarbeitung hinzu. ## POST /addressprocessing/FileUpload > ```json {"openapi":"3.0.1","info":{"title":"multisource•api ","version":"v2"},"tags":[{"name":"Batch"}],"servers":[{"url":"https://api.multisource.ch/v2","description":"Production - v2"},{"url":"https://api.multisource.ch","description":"Production"},{"url":"https://apitep.multisource.ch","description":"Pre-Production Testing"}],"security":[{"auth-key":[]}],"components":{"securitySchemes":{"auth-key":{"type":"apiKey","description":"API Key required for authorized endpoints","name":"auth-key","in":"header"}},"schemas":{"IFormFile":{"type":"string","format":"binary"}}},"paths":{"/addressprocessing/FileUpload":{"post":{"tags":["Batch"],"parameters":[{"name":"batchId","in":"query","schema":{"type":"integer","format":"int32"}},{"name":"batchUid","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"description","in":"query","schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"$ref":"#/components/schemas/IFormFile"}}}}},"required":true},"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"string"}},"text/json":{"schema":{"type":"string"}}}}}}}}} ``` ### :file-circle-plus: AddRecords Einzelne Datenrecords hochladen – unabhängig von einem FileUpload. Die Funktion kann verwendet werden, um einzelne neue Records zu übermitteln oder bestehende Uploads durch zusätzliche Records zu ergänzen. ## PUT /addressprocessing/AddRecords > ```json {"openapi":"3.0.1","info":{"title":"multisource•api ","version":"v2"},"tags":[{"name":"Batch"}],"servers":[{"url":"https://api.multisource.ch/v2","description":"Production - v2"},{"url":"https://api.multisource.ch","description":"Production"},{"url":"https://apitep.multisource.ch","description":"Pre-Production Testing"}],"security":[{"auth-key":[]}],"components":{"securitySchemes":{"auth-key":{"type":"apiKey","description":"API Key required for authorized endpoints","name":"auth-key","in":"header"}},"schemas":{"BatchProcessingApiRecord":{"type":"object","properties":{"customerId":{"type":"string","nullable":true},"classification":{"type":"string","nullable":true},"dwhId":{"type":"string","nullable":true},"kbbCompanyId":{"type":"integer","format":"int32","nullable":true},"kbcPersonId":{"type":"integer","format":"int32","nullable":true},"kbcHouseholdId":{"type":"integer","format":"int32","nullable":true},"beac":{"type":"integer","format":"int32","nullable":true},"egid":{"type":"string","nullable":true},"edid":{"type":"string","nullable":true},"postAddressId":{"type":"string","nullable":true},"freetext1":{"type":"string","nullable":true},"freetext2":{"type":"string","nullable":true},"freetext3":{"type":"string","nullable":true},"freetext4":{"type":"string","nullable":true},"freetext5":{"type":"string","nullable":true},"firstname":{"type":"string","nullable":true},"companyName":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"birthDate":{"type":"string","nullable":true},"street":{"type":"string","nullable":true},"streetNo":{"type":"string","nullable":true},"streetAdd":{"type":"string","nullable":true},"careOf":{"type":"string","nullable":true},"poBox":{"type":"string","nullable":true},"poZip":{"type":"string","nullable":true},"poTown":{"type":"string","nullable":true},"zip":{"type":"string","nullable":true},"town":{"type":"string","nullable":true},"mobileNo":{"type":"string","nullable":true},"phoneNo":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"uid":{"type":"string","nullable":true},"chnr":{"type":"string","nullable":true}}}}},"paths":{"/addressprocessing/AddRecords":{"put":{"tags":["Batch"],"parameters":[{"name":"id","in":"query","schema":{"type":"integer","format":"int32"}},{"name":"uid","in":"query","schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BatchProcessingApiRecord"}}},"text/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BatchProcessingApiRecord"}}},"application/*+json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BatchProcessingApiRecord"}}}},"required":true},"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"string"}},"text/json":{"schema":{"type":"string"}}}}}}}}} ``` ### :play: Start Startet die Verarbeitung. ## POST /addressprocessing/Start > ```json {"openapi":"3.0.1","info":{"title":"multisource•api ","version":"v2"},"tags":[{"name":"Batch"}],"servers":[{"url":"https://api.multisource.ch/v2","description":"Production - v2"},{"url":"https://api.multisource.ch","description":"Production"},{"url":"https://apitep.multisource.ch","description":"Pre-Production Testing"}],"security":[{"auth-key":[]}],"components":{"securitySchemes":{"auth-key":{"type":"apiKey","description":"API Key required for authorized endpoints","name":"auth-key","in":"header"}}},"paths":{"/addressprocessing/Start":{"post":{"tags":["Batch"],"parameters":[{"name":"id","in":"query","schema":{"type":"integer","format":"int32"}},{"name":"uid","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"string"}},"text/json":{"schema":{"type":"string"}}}}}}}}} ``` ### :magnifying-glass: Detail Bietet eine Übersicht aller verfügbaren Dateien und deren Verarbeitungsschritte. Enthält zudem die eindeutige Identifikationsnummer (`fileUniqueId`) jeder Datei. #### Batch Status
Status IDNameBeschreibung
0CreatedAngelegt, noch nicht bearbeitet
1ExecuteEingereiht; sobald Ressourcen verfügbar sind, startet die Verarbeitung
2ProcessingVerarbeitung läuft
3Marked for processingÜbergangsstatus zwischen Execute und Processing
4DoneVerarbeitung erfolgreich abgeschlossen
6ErrorVerarbeitung fehlgeschlagen; es ist ein Fehler aufgetreten
8Skippedeinzelne Module wurden übersprungen
## GET /addressprocessing/Detail > ```json {"openapi":"3.0.1","info":{"title":"multisource•api ","version":"v2"},"tags":[{"name":"Batch"}],"servers":[{"url":"https://api.multisource.ch/v2","description":"Production - v2"},{"url":"https://api.multisource.ch","description":"Production"},{"url":"https://apitep.multisource.ch","description":"Pre-Production Testing"}],"security":[{"auth-key":[]}],"components":{"securitySchemes":{"auth-key":{"type":"apiKey","description":"API Key required for authorized endpoints","name":"auth-key","in":"header"}},"schemas":{"BatchDetail":{"type":"object","properties":{"batchId":{"type":"integer","format":"int32"},"batchUniqueId":{"type":"string","format":"uuid"},"processGroup":{"type":"integer","format":"int32"},"insertBy":{"type":"string","nullable":true},"insertAt":{"type":"string","format":"date-time","nullable":true},"description":{"type":"string","nullable":true},"userDescription":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date-time","nullable":true},"endDate":{"type":"string","format":"date-time","nullable":true},"processingDate":{"type":"string","format":"date-time","nullable":true},"duration":{"type":"integer","format":"int32","nullable":true},"errorCount":{"type":"integer","format":"int32","nullable":true},"warningCount":{"type":"integer","format":"int32","nullable":true},"warningRejectCount":{"type":"integer","format":"int32","nullable":true},"createTypeId":{"type":"integer","format":"int32"},"runSingle":{"type":"boolean","nullable":true},"agent":{"type":"string","nullable":true},"datagroupId":{"type":"integer","format":"int32","nullable":true},"orderNr":{"type":"string","nullable":true},"settings":{"type":"object","additionalProperties":{"type":"string"},"nullable":true},"files":{"type":"array","items":{"$ref":"#/components/schemas/BatchFile"}},"steps":{"type":"array","items":{"$ref":"#/components/schemas/BatchStep"}}}},"BatchFile":{"type":"object","properties":{"fileUniqueId":{"type":"string","format":"uuid"},"direction":{"type":"string","nullable":true},"fileName":{"type":"string","nullable":true},"processFileDetection":{"type":"string","nullable":true},"description":{"type":"string","nullable":true}}},"BatchStep":{"type":"object","properties":{"stepId":{"type":"integer","format":"int32"},"status":{"type":"string","nullable":true},"sortOrder":{"type":"integer","format":"int32","nullable":true},"startDate":{"type":"string","format":"date-time","nullable":true},"endDate":{"type":"string","format":"date-time","nullable":true},"duration":{"type":"integer","format":"int32","nullable":true},"errorCount":{"type":"integer","format":"int32","nullable":true},"warningCount":{"type":"integer","format":"int32","nullable":true},"warningRejectCount":{"type":"integer","format":"int32","nullable":true},"recordCount":{"type":"integer","format":"int32","nullable":true},"description":{"type":"string","nullable":true},"modulUniqueId":{"type":"string","format":"uuid","nullable":true},"descriptionAdd":{"type":"string","nullable":true}}}}},"paths":{"/addressprocessing/Detail":{"get":{"tags":["Batch"],"parameters":[{"name":"id","in":"query","schema":{"type":"integer","format":"int32"}},{"name":"uid","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/BatchDetail"}},"application/json":{"schema":{"$ref":"#/components/schemas/BatchDetail"}},"text/json":{"schema":{"$ref":"#/components/schemas/BatchDetail"}}}}}}}}} ``` ### :download: FileDownload Lädt die Resultate eines AdressProcessing-Batches als Datei herunter. Die Ausgabe erfolgt im **TSV-Format** (tabulatorgetrennte Werte). Über den Parameter **compressed** kann gesteuert werden, ob die Datei **komprimiert** **(.txt.gz)** (false) oder **unkomprimiert (.txt)** (true) ausgeliefert wird. ## GET /addressprocessing/FileDownload > ```json {"openapi":"3.0.1","info":{"title":"multisource•api ","version":"v2"},"tags":[{"name":"Batch"}],"servers":[{"url":"https://api.multisource.ch/v2","description":"Production - v2"},{"url":"https://api.multisource.ch","description":"Production"},{"url":"https://apitep.multisource.ch","description":"Pre-Production Testing"}],"security":[{"auth-key":[]}],"components":{"securitySchemes":{"auth-key":{"type":"apiKey","description":"API Key required for authorized endpoints","name":"auth-key","in":"header"}}},"paths":{"/addressprocessing/FileDownload":{"get":{"tags":["Batch"],"parameters":[{"name":"id","in":"query","schema":{"type":"integer","format":"int32"}},{"name":"uid","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"decompress","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"OK"}}}}}} ``` ### :memo-circle-check: GetRecords Ruft die Resultate eines AdressProcessing-Batches direkt als **JSON** ab. Dieser Endpoint eignet sich, wenn die Daten unmittelbar im System weiterverarbeitet werden sollen, ohne eine Datei herunterzuladen. ## GET /addressprocessing/GetRecords > ```json {"openapi":"3.0.1","info":{"title":"multisource•api ","version":"v2"},"tags":[{"name":"Batch"}],"servers":[{"url":"https://api.multisource.ch/v2","description":"Production - v2"},{"url":"https://api.multisource.ch","description":"Production"},{"url":"https://apitep.multisource.ch","description":"Pre-Production Testing"}],"security":[{"auth-key":[]}],"components":{"securitySchemes":{"auth-key":{"type":"apiKey","description":"API Key required for authorized endpoints","name":"auth-key","in":"header"}}},"paths":{"/addressprocessing/GetRecords":{"get":{"tags":["Batch"],"parameters":[{"name":"uid","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"file","in":"query","schema":{"type":"boolean","default":false}},{"name":"fileDecompress","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"OK"}}}}}} ``` ## Optionale Schritte (für erweiterte Anwendungsfälle) ### AddDatagroup Fügt eine Datengruppe hinzu. Daten werden in sogenannten Data Groups organisiert. Diese dienen dazu, Datensätze bei Bedarf logisch zu trennen. So lassen sich zum Beispiel Bestandskunden, Neukunden oder Kampagnen getrennt verarbeiten und auswerten. In vielen Fällen genügt jedoch auch eine einzelne Data Group, in die alle Daten geladen und fortlaufend aktualisiert werden. > Hinweis: Sobald eine Data Group gestartet wird, werden die bestehenden Daten in dieser Gruppe überschrieben. ## PUT /addressprocessing/AddDatagroup > ```json {"openapi":"3.0.1","info":{"title":"multisource•api ","version":"v2"},"tags":[{"name":"Batch"}],"servers":[{"url":"https://api.multisource.ch/v2","description":"Production - v2"},{"url":"https://api.multisource.ch","description":"Production"},{"url":"https://apitep.multisource.ch","description":"Pre-Production Testing"}],"security":[{"auth-key":[]}],"components":{"securitySchemes":{"auth-key":{"type":"apiKey","description":"API Key required for authorized endpoints","name":"auth-key","in":"header"}}},"paths":{"/addressprocessing/AddDatagroup":{"put":{"tags":["Batch"],"parameters":[{"name":"description","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}}}} ``` ### GetDataGroups Listet die verfügbaren Datengruppen auf. ## GET /addressprocessing/GetDatagroups > ```json {"openapi":"3.0.1","info":{"title":"multisource•api ","version":"v2"},"tags":[{"name":"Batch"}],"servers":[{"url":"https://api.multisource.ch/v2","description":"Production - v2"},{"url":"https://api.multisource.ch","description":"Production"},{"url":"https://apitep.multisource.ch","description":"Pre-Production Testing"}],"security":[{"auth-key":[]}],"components":{"securitySchemes":{"auth-key":{"type":"apiKey","description":"API Key required for authorized endpoints","name":"auth-key","in":"header"}}},"paths":{"/addressprocessing/GetDatagroups":{"get":{"tags":["Batch"],"responses":{"200":{"description":"OK"}}}}}} ``` ### SetBatchSettings Setzt Batch-Einstellungen.
Request-ParameterErklärung
property-name

Setting Werte werden als Property im Body mit den jeweiligen Werten übergeben:

  • InputMapping Definiert, welches Datenmapping zur Datenverarbeitung angewendet wird.
  • RangeBack für zu betrachtende Adressänderungen (z.B. Umzüge der letzten 12 Monate). → Standardwert: 36 Monate
  • WebhookUrl zur Automatisierung nach Abschluss des Batches. Kann zur weiteren Automatisierung von Prozessen genutzt werden, um nach Abschluss des Batches Aktionen beim Kunden auszulösen (z.B. Aktualisierung von Reports in PowerBI).
  • webhookmethod Definiert die HTTP-Methode, die für den Aufruf verwendet wird (z. B. POST oder PUT).
  • webhookheader Optional – definiert die HTTP-Headers als Stringified JSON, z. B. zur Übergabe von Authentifizierungstokens.
  • webhookbody Optional – definiert den HTTP-Body als Stringified JSON, z. B. zur Übermittlung individueller Nutzdaten oder Payloads
## POST /addressprocessing/SetBatchSettings > ```json {"openapi":"3.0.1","info":{"title":"multisource•api ","version":"v2"},"tags":[{"name":"Batch"}],"servers":[{"url":"https://api.multisource.ch/v2","description":"Production - v2"},{"url":"https://api.multisource.ch","description":"Production"},{"url":"https://apitep.multisource.ch","description":"Pre-Production Testing"}],"security":[{"auth-key":[]}],"components":{"securitySchemes":{"auth-key":{"type":"apiKey","description":"API Key required for authorized endpoints","name":"auth-key","in":"header"}}},"paths":{"/addressprocessing/SetBatchSettings":{"post":{"tags":["Batch"],"parameters":[{"name":"uid","in":"query","schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"string"}}},"text/json":{"schema":{"type":"object","additionalProperties":{"type":"string"}}},"application/*+json":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}},"required":true},"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"string"}},"text/json":{"schema":{"type":"string"}}}}}}}}} ```