Batch

Adressprocessing Ablauf

1

Daten im CRM selektieren

Im CRM die zu verarbeitenden Datensätze selektieren – entweder alle Datensätze oder nur eine Teilmenge.

2

Erstellen von Data Groups

/api/AddressProcessing/AddDatagroup

  • Daten werden in sogenannten Data Groups organisiert. Diese fungieren als Verarbeitungspakete und können mit einzelnen Schubladen in einem grossen Schrank verglichen werden.

    • Beispiel: Eine Data Group wird für wöchentliche Updates erstellt, eine andere für monatliche.

    • Hinweis: Sobald eine Data Group gestartet wird, werden die bestehenden Daten überschrieben.

3

Erstellung eines Batches

/api/AddressProcessing/Create

  • Ein Batch ist die Hülle, die als Rahmen für die Verarbeitung dient. Er wird über den /batches Endpunkt erstellt.

4

Einstellungen konfigurieren

/api/AddressProcessing/SetBatchSettings

  • Über SetBatchSettings können folgende Parameter festgelegt werden:

  • InputMapping

  • RangeBack

  • WebhookUrl

5

Datei hochladen und Batch starten

/api/AddressProcessing/FileUpload

Hier erfolgt der Upload der Datei, die verarbeitet werden soll. Anschliessend startet der Batch basierend auf dem angegebenen UID-Schlüssel.

/api/AddressProcessing/Start

Statusabfrage: Der Fortschritt kann mittels /api/AddressProcessing/Detail überwacht werden. Dabei können laufende Module, Status der Dateien etc. eingesehen werden.

6

Download der Ergebnisse

/api/AddressProcessing/Detail

/api/AddressProcessing/FileDownload

  • Im Detail ist die Liste aller Files mit einer eindeutigen File-ID enthalten. In Kombination mit der Batch-ID entsteht eine eindeutige Zuordnung.

  • Die Resultate sind im .csv-Format verfügbar, wobei die Struktur auf tabulatorgetrennte Werte ausgelegt ist.

Funktionen

AddDatagroup

Fügt eine Datengruppe hinzu.

put
Authorizations
Query parameters
descriptionstringOptional
Responses
200

OK

No content
put
PUT /api/addressprocessing/AddDatagroup HTTP/1.1
Host: webservices.kbdata.ch
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

OK

No content

GetDataGroups

Listet die verfügbaren Datengruppen auf.

get
Authorizations
Responses
200

OK

No content
get
GET /api/addressprocessing/GetDatagroups HTTP/1.1
Host: webservices.kbdata.ch
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

OK

No content

Create

Erstellt eine Adressverarbeitung.

Request-Parameter
Erklärung

ordernr

Benutzerdefinierte Referenznummer, die zur eindeutigen Identifikation einer Bestellung vergeben werden kann, z. B. für spätere Rückfragen oder Abklärungen.

datagroupid

Eindeutige Identifikation der Data Group.

processid

Systemseitig vergebene ID für den Prozess. → Standardwert: 400

userDescription

Name der Kampagne oder des Batches.

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.

processingdate

Definiert, wann der Batch gestartet werden soll (z.B. Hülle heute erstellen, Verarbeitung am Wochenende).

notificatioEmail

E-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
Authorizations
Body
orderNrstringRequired
dataGroupIdinteger · int32Optional
dataGroupCodestring | nullableOptional
userDescriptionstring | nullableRequired
processIdinteger · int32Required
businessCaseinteger · int32Optional
productinteger · enumRequiredPossible values:
notificationEmailstringOptional
processingDatestring · date-timeOptional
runParallelbooleanOptional
Responses
200

OK

post
POST /api/addressprocessing/Create HTTP/1.1
Host: webservices.kbdata.ch
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 226

{
  "orderNr": "text",
  "dataGroupId": 1,
  "dataGroupCode": "text",
  "userDescription": "text",
  "processId": 1,
  "businessCase": 1,
  "product": "1 = Enrich",
  "notificationEmail": "text",
  "processingDate": "2025-09-24T16:42:54.386Z",
  "runParallel": true
}
200

OK

{
  "batchId": 1,
  "batchUniqueId": "123e4567-e89b-12d3-a456-426614174000",
  "processGroup": 1,
  "insertBy": "text",
  "insertAt": "2025-09-24T16:42:54.386Z",
  "description": "text",
  "userDescription": "text",
  "status": "text",
  "startDate": "2025-09-24T16:42:54.386Z",
  "endDate": "2025-09-24T16:42:54.386Z",
  "processingDate": "2025-09-24T16:42:54.386Z",
  "duration": 1,
  "errorCount": 1,
  "warningCount": 1,
  "warningRejectCount": 1,
  "createTypeId": 1,
  "runSingle": true,
  "agent": "text",
  "datagroupId": 1,
  "orderNr": "text",
  "files": [
    {
      "fileUniqueId": "123e4567-e89b-12d3-a456-426614174000",
      "direction": "text",
      "fileName": "text",
      "processFileDetection": "text",
      "description": "text"
    }
  ],
  "steps": [
    {
      "stepId": 1,
      "status": "text",
      "sortOrder": 1,
      "startDate": "2025-09-24T16:42:54.386Z",
      "endDate": "2025-09-24T16:42:54.386Z",
      "duration": 1,
      "errorCount": 1,
      "warningCount": 1,
      "warningRejectCount": 1,
      "recordCount": 1,
      "description": "text",
      "modulUniqueId": "123e4567-e89b-12d3-a456-426614174000",
      "descriptionAdd": "text"
    }
  ]
}

SetBatchSettings

Setzt Batch-Einstellungen.

Request-Parameter
Erklä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
Authorizations
Query parameters
uidstring · uuidOptional
Body
Other propertiesstringOptional
Responses
200

OK

Responsestring
post
POST /api/addressprocessing/SetBatchSettings HTTP/1.1
Host: webservices.kbdata.ch
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 34

{
  "ANY_ADDITIONAL_PROPERTY": "text"
}
200

OK

text

FileUpload

Fügt eine Datei zur Verarbeitung hinzu.

post
Authorizations
Query parameters
batchIdinteger · int32Optional
batchUidstring · uuidOptional
descriptionstringOptional
Body
filestring · binaryOptional
Responses
200

OK

Responsestring
post
POST /api/addressprocessing/FileUpload HTTP/1.1
Host: webservices.kbdata.ch
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: multipart/form-data
Accept: */*
Content-Length: 17

{
  "file": "binary"
}
200

OK

text

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
Authorizations
Query parameters
idinteger · int32Optional
uidstring · uuidOptional
Bodyobject[]
customerIdstring | nullableOptional
classificationstring | nullableOptional
dwhIdstring | nullableOptional
kbbCompanyIdinteger · int32 | nullableOptional
kbcPersonIdinteger · int32 | nullableOptional
kbcHouseholdIdinteger · int32 | nullableOptional
beacinteger · int32 | nullableOptional
egidstring | nullableOptional
edidstring | nullableOptional
postAddressIdstring | nullableOptional
freetext1string | nullableOptional
freetext2string | nullableOptional
freetext3string | nullableOptional
freetext4string | nullableOptional
freetext5string | nullableOptional
firstnamestring | nullableOptional
companyNamestring | nullableOptional
namestring | nullableOptional
birthDatestring | nullableOptional
streetstring | nullableOptional
streetNostring | nullableOptional
streetAddstring | nullableOptional
careOfstring | nullableOptional
poBoxstring | nullableOptional
poZipstring | nullableOptional
poTownstring | nullableOptional
zipstring | nullableOptional
townstring | nullableOptional
mobileNostring | nullableOptional
phoneNostring | nullableOptional
emailstring | nullableOptional
uidstring | nullableOptional
chnrstring | nullableOptional
Responses
200

OK

Responsestring
put
PUT /api/addressprocessing/AddRecords HTTP/1.1
Host: webservices.kbdata.ch
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 561

[
  {
    "customerId": "text",
    "classification": "text",
    "dwhId": "text",
    "kbbCompanyId": 1,
    "kbcPersonId": 1,
    "kbcHouseholdId": 1,
    "beac": 1,
    "egid": "text",
    "edid": "text",
    "postAddressId": "text",
    "freetext1": "text",
    "freetext2": "text",
    "freetext3": "text",
    "freetext4": "text",
    "freetext5": "text",
    "firstname": "text",
    "companyName": "text",
    "name": "text",
    "birthDate": "text",
    "street": "text",
    "streetNo": "text",
    "streetAdd": "text",
    "careOf": "text",
    "poBox": "text",
    "poZip": "text",
    "poTown": "text",
    "zip": "text",
    "town": "text",
    "mobileNo": "text",
    "phoneNo": "text",
    "email": "text",
    "uid": "text",
    "chnr": "text"
  }
]
200

OK

text

Start

Startet die Verarbeitung.

post
Authorizations
Query parameters
idinteger · int32Optional
uidstring · uuidOptional
Responses
200

OK

Responsestring
post
POST /api/addressprocessing/Start HTTP/1.1
Host: webservices.kbdata.ch
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

OK

text

Detail

Bietet eine Übersicht aller verfügbaren Dateien und deren Verarbeitungsschritte. Enthält zudem die eindeutige Identifikationsnummer jeder Datei.

get
Authorizations
Query parameters
idinteger · int32Optional
uidstring · uuidOptional
Responses
200

OK

get
GET /api/addressprocessing/Detail HTTP/1.1
Host: webservices.kbdata.ch
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

OK

{
  "batchId": 1,
  "batchUniqueId": "123e4567-e89b-12d3-a456-426614174000",
  "processGroup": 1,
  "insertBy": "text",
  "insertAt": "2025-09-24T16:42:54.386Z",
  "description": "text",
  "userDescription": "text",
  "status": "text",
  "startDate": "2025-09-24T16:42:54.386Z",
  "endDate": "2025-09-24T16:42:54.386Z",
  "processingDate": "2025-09-24T16:42:54.386Z",
  "duration": 1,
  "errorCount": 1,
  "warningCount": 1,
  "warningRejectCount": 1,
  "createTypeId": 1,
  "runSingle": true,
  "agent": "text",
  "datagroupId": 1,
  "orderNr": "text",
  "files": [
    {
      "fileUniqueId": "123e4567-e89b-12d3-a456-426614174000",
      "direction": "text",
      "fileName": "text",
      "processFileDetection": "text",
      "description": "text"
    }
  ],
  "steps": [
    {
      "stepId": 1,
      "status": "text",
      "sortOrder": 1,
      "startDate": "2025-09-24T16:42:54.386Z",
      "endDate": "2025-09-24T16:42:54.386Z",
      "duration": 1,
      "errorCount": 1,
      "warningCount": 1,
      "warningRejectCount": 1,
      "recordCount": 1,
      "description": "text",
      "modulUniqueId": "123e4567-e89b-12d3-a456-426614174000",
      "descriptionAdd": "text"
    }
  ]
}

Files

Sämtliche Files welche von der Verarbeitung erstellt wurden und zum Downlaod bereitstehen.

get
Authorizations
Query parameters
idinteger · int32Optional
uidstring · uuidOptional
Responses
200

OK

get
GET /api/addressprocessing/Files HTTP/1.1
Host: webservices.kbdata.ch
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

OK

[
  {
    "fileUniqueId": "123e4567-e89b-12d3-a456-426614174000",
    "direction": "text",
    "fileName": "text",
    "processFileDetection": "text",
    "description": "text"
  }
]

FileDownload

Lädt verarbeitete Dateien herunter.

get
Authorizations
Query parameters
idinteger · int32Optional
uidstring · uuidOptional
decompressbooleanOptionalDefault: false
Responses
200

OK

No content
get
GET /api/addressprocessing/FileDownload HTTP/1.1
Host: webservices.kbdata.ch
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

OK

No content

Webhooks

Die Batch bietet Webhooks an, um automatisierte Benachrichtigungen nach abgeschlossenen Prozessen zu ermöglichen. Sie können eingerichtet werden, um nach der Verarbeitung eines Batches eine Benachrichtigung auszulösen.

Konfiguration des Webhooks

Details zur Einrichtung finden Sie unter SetBatchSettings.

WebhookUrl

  • Ermöglicht die Automatisierung von Prozessen nach Abschluss eines Batches.

  • Unterstützt aktuell GET-Requests mit Querystring-Parametern.

Unterstützte Events

  • Batch abgeschlossen: Benachrichtigung, sobald die Verarbeitung eines Batches abgeschlossen ist.

PreviousMatchNextData

Last updated