Konnektoren
Schemaobjekte
Die SQL- und Dateibrücke
Das OAuth 2.0 Verfahren
Gesperrte Datensätze

Databyte Konnektor

Databyte ist eine Informationsplattform für detaillierte Firmendaten.
Mit dem Konnektor stehen zentrale Funktionen für Suche, Listenverwaltung, Exporte, Monitoring und Data-Matching zur Verfügung.

Der Konnektor erzeugt Auswahllisten und Schemaobjekte für die Bedienung und verarbeitet Antworten in einem Datensatz-Speicher, damit Ergebnisse synchron weiterverarbeitet oder erneut gelesen werden können.

Voraussetzungen

  • Aktiver Zugang zu Databyte (Zugriffsrechte für Suchen, Listen, Exporte, ggf. Monitoring & Data-Match).
  • Netzwerkzugriff aus Syncler auf die Databyte-Schnittstelle.
  • Ausreichende Kontingente/Quotas für Downloads/Exporte (wichtig für exportrequest).

Objekte

Nachfolgend die bereitgestellten Schemaobjekte inkl. Verhalten beim Lesen/Schreiben:

companylist

Verwaltung von Firmenlisten.

  • Lesen: Vorhandene Listen abrufen.
  • Schreiben: Listen anlegen, umbenennen, löschen.

companylist_copy

Kopieren einer bestehenden Firmenliste.

  • Schreiben: fls = ID der Quellliste → Antwort enthält newfls (ID der Kopie).

companylist_data

Zugriff auf den Inhalt (Firmennummern/IDs) einer Firmenliste.

  • Lesen: Filter erfordert Listen-ID; Rückgabe: Feld data mit Liste von Firmen-IDs.
  • Schreiben: Hinzufügen von Firmen zur Liste via Steuerfeldern:
    • ssid: Bezug auf vorherige Suchanfrage (searchrequest).
    • umfang (Auswahl der Datenmenge):
      • 2 → Bereich von–bis aus dem Suchergebnis
      • 3 → Bereich bereich (jeder x-te Datensatz)
      • 4 → ohne Suche: alle in firmen angegebenen IDs
      • alle anderen Werte → komplettes Suchergebnis
  • Löschen: Leert die Liste (Truncate).

Tipp: Der Listeninhalt eignet sich zur Überwachung von Änderungen (Monitoring-Workflows).

companylist_truncate

Leeren einer vorhandenen Firmenliste.

  • Schreiben: fls = ID der Liste.

datamatch

Verwaltung von Data-Match-Projekten.

  • Lesen: Projekte auflisten, filtern.
  • Schreiben: Projekt anlegen oder löschen.
  • Suche/Filter: Standard-Syncfelder (z. B. Name) werden direkt auf den Projektnamen gemappt.

datamatch_data

Übertragung und Abruf von Vergleichsdatensätzen für ein Projekt.

  • Schreiben: Bis zu 500 Datensätze je Aufruf (Bulkfähig), z. B. Firmenname, Anschrift, optionale kunde_id (externe ID).
  • Lesen: Erfordert Projekt-ID als Filter.
    • Wenn Projekt nicht gestartet → Fehlermeldung.
    • Wenn Projekt läuft → Statusprüfung alle 10 Sekunden bis Abschluss (manuell abbrechbar).
    • Ergebnis wird einmalig aus Databyte gelesen und anschließend:
      • als Einzeldatensätze mit Match-Ergebnis (und ggf. Ziel-ID) im Datensatz-Speicher abgelegt,
      • dem aktuellen Sync zugeordnet und wiederholt aus dem Speicher lesbar.
  • Hinweis: Setzen Sie kunde_id mit Ihrer externen ID, um Resultate eindeutig zuzuordnen.

datamatch_start

Startet die Projektverarbeitung.

  • Schreiben: Projekt-ID übergeben → Verarbeitung beginnt.

datamatch_abort

Bricht die Projektverarbeitung ab.

  • Schreiben: Projekt-ID übergeben → Verarbeitung wird gestoppt.

searchrequest

Auslösen einer Suche.

  • Schreiben: Der Auftrag startet die Suche; Ergebnis wird im Datensatz-Speicher abgelegt.
  • Lesen: Per Filter auf die generierte ssid zugreifen.

exportrequest

Fordert einen Export an (vom Download-Kontingent abgezogen).

  • Schreiben: Steuerung u. a. über:
    • export: Informationstiefe → std, erw, pro
      → Export landet im Datensatz-Speicher unter dem jeweiligen Zielschema (exportstd/exporterw/exportpro)
    • ssid: Bezug auf Suchanfrage
    • umfang: Auswahl (wie bei companylist_data)
      • 2 → von–bis
      • 3 → bereich (jeder x-te)
      • 4 → alle IDs aus firmen (ohne Suche)
    • Weitere Parameter:
      • person: Anzahl Personen pro Datensatz (z. B. 0, 1)
      • zusatz: z. B. passive/schwebende Firmen mit exportieren
  • Lesen: Ergebnisse werden aus dem Datensatz-Speicher gelesen (siehe unten).

exportstd, exporterw, exportpro

Ablage der Export-Ergebnisse im Datensatz-Speicher je gewählter Informationstiefe:

  • Lesen: Einzelne oder alle Datensätze abrufen; kein Sync-Locking.

monitoringrequest

Anfordern/Abbestellen einer Überwachung (Monitoring) für Firmenlisten.

  • Schreiben: Parameter:
    • merkmale: Liste von Monitoring-Merkmalen (aus Auswahlliste „Monitoring“),
    • Listen-ID, Intervall, Aktiv-Kennzeichen.
  • Beim Einlesen des Systemschemas kann eine Liste vorgegeben oder automatisch bestimmt werden.

postbox

Ablage von Monitoring-Nachrichten bei erkannten Änderungen.

  • Lesen: Nachrichten enthalten geschachtelte Daten (Merkmale + Firmen) sowie eine ID-Gesamtliste.
  • Schreiben: confirm = true → Nachricht bestätigen (wird nicht erneut gelesen).

Lesen von Daten

  • Ergebnisse aus Suchen, Exports und Data-Match werden im Datensatz-Speicher abgelegt.
  • Einzellesen vs. Listenlesen je Objekt gemäß oben.
  • Sperren/Einmaligkeit:
    • datamatch_data: Ergebnis ist nur einmal direkt von Databyte abrufbar, danach nur aus dem Datensatz-Speicher.
    • export*: liegen immer im Datensatz-Speicher; beliebig oft lesbar.

Schreiben von Daten

  • Auftragsorientiert (z. B. searchrequest, exportrequest, datamatch*, companylist_*).
  • Seiteneffekte beachten:
    • Exporte reduzieren Kontingente.
    • companylist_data mit Löschen leert die Liste.
    • monitoringrequest beeinflusst laufende Überwachungen.

Die Suche nach Firmen

Verwenden Sie das Schemaobjekt searchrequest:

  • Warum als Schreiben?
    Die Suche ist auftragsbasiert – komplexe Kriterien werden über Feldzuordnungen übergeben.

  • Struktur
    Das Objekt besitzt Bereiche wie firma, anschrift, branche.

    • Gleicher Bereich mehrfach → ODER-Verknüpfung (z. B. anschrift.1, anschrift.2).
    • Zuordnungen innerhalb eines Bereichs → UND-Verknüpft.
    • Verschiedene Bereiche → UND-Verknüpft.

  • Beispiel

    • firma.1.firma = Suchname
    • anschrift.1.ort = Stadt A
    • anschrift.2.ort = Stadt B
      → Ergebnis: Firmenname in Stadt A ODER Stadt B (bei gleichzeitigem UND mit anderen Bereichsbedingungen)

  • Ergebnis

    • Ablage als geschachteltes Objekt im Datensatz-Speicher (gekürzte Firmendaten als Liste).
    • Rückgabe der ssid zur Weiterverwendung (Firmenliste, Export).
    • Zusätzlich ein Feld mit allen Firmen-IDs der Treffer.

Hinzufügen von Firmen zu einer Liste

Verwenden Sie companylist_data (schreibend):

  • Quelle:

    • ssid aus Suchanfrage,
    • ID-Liste aus externem System,
    • IDs aus Monitoring-Nachrichten.

  • Steuerung über umfang

    • 2: Bereich von–bis
    • 3: bereich (jeder x-te)
    • 4: alle in Feld firmen
    • sonst: komplettes Suchergebnis

  • Ablaufempfehlung

    1. Sync A (Universal/Schreib-Sync) → searchrequest (Kriterien)
    2. Sync B (Universal-Sync) → Quelle searchrequest, Ziel companylist_data (mit ssid & umfang)
    3. Ergebnis: Liste ergänzt

Hinweis: Die Listen-ID muss bekannt sein (Transformation oder Vorgänger-Sync).

Export von Firmen & Übertragung in ein externes System

  • Vorbereitung: Auswahlmenge durch Suche (searchrequest) oder ID-Liste (z. B. aus Monitoring).

  • Ablauf

    1. Sync A → searchrequest
    2. Sync B → exportrequest (Quelle: searchrequest, Ziel: exportrequest)
      • ssid, umfang, ggf. firmen setzen
      • export = std/erw/pro (Informationstiefe)
    3. Sync C (Universal) → Quelle: exportstd / exporterw / exportpro, Ziel: externes System

  • Ergebnis

    • Exportdaten im Datensatz-Speicher
    • Flexible Weiterleitung/Transformation über Sync C

Data-Match mit vorhandenen Daten

Ziel: Abgleich Ihrer Stammdaten mit Databyte; Ermittlung möglicher Treffer, IDs & Zuordnungen.

  • Ablauf (4 Syncs)

    1. Projekt anlegen → datamatch (Schreiben)
      • Name, Typ angeben → Projekt-ID wird generiert (für Folgeschritte speichern).
    2. Stammdaten übertragen → datamatch_data (Schreiben, Bulk bis 500/Stapel)
      • Mindestens Name & Anschrift, optional kunde_id (Ihre externe ID).
      • Projekt-ID als Bezug (Parameter/Platzhalter).
    3. Projekt starten → datamatch_start (Schreiben mit Projekt-ID)
      • Laufzeit minutenabhängig (Menge/Parallelität).
    4. Ergebnis lesen → datamatch_data (Lesen mit Projekt-ID)
      • Warten bis Abschluss (Polling alle 10 Sek.).
      • Ergebnis einmalig abrufbar, danach im Datensatz-Speicher hinterlegt (wiederholt lesbar).
      • IDs zurück ins Quellsystem schreiben oder für Folgesyncs nutzen.

  • Automatisierung

    • Im Ablauf nur Sync 1 manuell starten; alle weiteren über Vorgängerdaten verkettet (Projekt-ID durchreichen).

Monitoring von Merkmalsänderungen

  • Basis: Eine gefüllte Firmenliste (siehe oben).
  • Merkmale abonnieren: monitoringrequest (Schreiben) mit Merkmalen aus Auswahlliste „Monitoring“.
  • Abruf von Nachrichten:
    • Quelle: postbox
    • Weiterverarbeitung: z. B. direkt exportrequest als Ziel (IDs sind enthalten).
    • Deduplizieren: Mit Rückschreiben confirm = true → Nachricht wird bestätigt und nicht erneut geliefert.
  • Intervall: kleinstes Intervall = 1 Tag.

Best Practices & Hinweise

  • Kontingente: exportrequest verbraucht Download-Einheiten – vor der Ausführung prüfen.
  • Fehlerbehandlung: Lese-/Schreibfehler stets im Sync-Log prüfen; bei datamatch_data ggf. Projektstatus.
  • IDs & Zuordnung: kunde_id (eigene Fremd-ID) konsequent setzen, um Resultate zuverlässig zu matchen.
  • Performance: Große Suchen/Exporte sinnvoll bündeln (Bereiche, Paging via umfang).
  • Wiederholbarkeit: Ergebnisse im Datensatz-Speicher erlauben wiederholte Verarbeitung ohne erneutes Abrufen bei Databyte.