---
title: "Resumierbaren Portfolio-Sync beginnen"
method: POST
path: "/portfolios/{sourceKey}/syncs"
tags: ["Portfolios"]
---

# Resumierbaren Portfolio-Sync beginnen

`POST /portfolios/{sourceKey}/syncs`

## Request

- Base URL: `https://firmenwatch.ch/api/v1`
- URL: `https://firmenwatch.ch/api/v1/portfolios/{sourceKey}/syncs`
- Auth: HTTP bearer

Reserviert genau einen Staging-Lauf fuer die kontoeigene Quelle, ohne das sichtbare Portfolio zu veraendern. base_version muss der letzten Commit-Quittung entsprechen; eine neue Quelle beginnt bei 0 und am aktuellen verifizierten Ereignis-High-Water. Dadurch entstehen weder historische Alarme noch eine Ereignisluecke waehrend des Syncs. relationship_default ordnet den ganzen Quellenbestand als Kunden, Lieferanten, Mandate, Leads oder Partner ein; eine spaetere lokale Firmenwatch-Annotation hat Vorrang. expected_items zaehlt die eindeutigen external_id-Werte des gesamten Laufs, nicht wiederholte Zeilen oder HTTP-Versuche. Dieselbe sync_id mit denselben validierten Startparametern ist ein idempotenter Resume-Abruf und liefert replayed=true. Dieselbe ID mit anderen Parametern oder ein anderer gleichzeitig aktiver Lauf ergibt 409. Ein Staging-Lauf mit seit mehr als 24 Stunden ausbleibender Stapelaktivitaet wird beim naechsten Start verworfen; danach ist eine neue sync_id zu verwenden. Start-Ruempfe sind auf 32 KiB begrenztes, unkomprimiertes UTF-8-JSON. Nach jedem HTTP-5xx ist dieselbe Anfrage sicher wiederholbar.

## Path parameters

- `sourceKey` string, required

## Request body

- PortfolioSyncStartRequest
  - `sync_id` string, required: Vom Client vergebene Idempotenz- und Resume-Kennung. Mit veraenderten Parametern nicht wiederverwenden.
  - `mode` 'replace' | 'delta', required: replace ist ein vollstaendiger Snapshot; delta enthaelt ausschliesslich explizite Aenderungen.
  - `base_version` integer, required: version der letzten Commit-Quittung; 0 fuer eine noch nicht angelegte Quelle.
  - `expected_items` integer, required: Exakte Zahl eindeutiger external_id-Werte des gesamten Laufs. Wiederholungen zaehlen nicht erneut.
  - `source_revision` string, nullable: Optionale druckbare Revision des Quellsystems ohne Rand-Leerzeichen.
  - `relationship_default` 'customer' | 'supplier' | 'mandate' | 'lead' | 'partner' | 'null', nullable, required: Schlanke Einordnung fuer alle Firmen dieser Quelle. Eine lokale Firmenwatch-Annotation hat immer Vorrang; null bedeutet keine Quellvorgabe.

## Response `200`

Neu angelegter oder idempotent wieder aufgenommener Sync.

- object
  - `data` PortfolioSyncDescriptor, required
    - `source_key` string, required
    - `sync_id` string, required
    - `mode` 'replace' | 'delta', required
    - `status` 'staging' | 'committed' | 'failed', required
    - `base_version` integer, required
    - `generation` integer, required: Vorgesehene neue Version, stets base_version + 1.
    - `expected_items` integer, required
    - `received_items` integer, required: Bereits angenommene eindeutige external_id-Werte.
    - `source_revision` string, nullable, required
    - `relationship_default` 'customer' | 'supplier' | 'mandate' | 'lead' | 'partner' | 'null', nullable, required: Schlanke Einordnung fuer alle Firmen dieser Quelle. Eine lokale Firmenwatch-Annotation hat immer Vorrang; null bedeutet keine Quellvorgabe.
    - `replayed` boolean, required: true, wenn dieselbe sync_id mit denselben validierten Startparametern bereits existierte.
    - `result` PortfolioCommitReceipt
      - `sync_id` string, required
      - `source_key` string, required
      - `mode` 'replace' | 'delta', required
      - `source_revision` string, nullable, required: Vom Quellsystem gelieferte, unveraendert quittierte Revision.
      - `relationship_default` 'customer' | 'supplier' | 'mandate' | 'lead' | 'partner' | 'null', nullable, required: Schlanke Einordnung fuer alle Firmen dieser Quelle. Eine lokale Firmenwatch-Annotation hat immer Vorrang; null bedeutet keine Quellvorgabe.
      - `version` integer, required: Neue Portfolio-Version; beim naechsten Lauf als base_version verwenden.
      - `received_items` integer, required: Eindeutige external_id-Werte, die der Lauf angenommen hat.
      - `source_items` integer, required: Eindeutige external_id-Werte im resultierenden Quellbestand.
      - `monitored_entities` integer, required: Resultierende unterschiedliche Schweizer UIDs und damit belegte Ueberwachungsplaetze.
      - `added` integer, required
      - `updated` integer, required
      - `removed` integer, required
      - `digest` string, required: SHA-256-Quittungsdigest des vollstaendigen resultierenden Quellbestands einschliesslich relationship_default.
      - `committed_at` string, date-time, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required

## Other responses

- `400`: Ungueltige Anfrage (invalid_request).
- `401`: Kein oder ungueltiger Schluessel (unauthorized).
- `402`: Monatskontingent erschoepft (quota_exceeded).
- `403`: Abonnement nicht aktiv oder benoetigtes Schluesselrecht fehlt (forbidden).
- `404`: sourceKey verletzt das kleingeschriebene, URL-stabile Format (not_found).
- `409`: base_version, sync_id oder ein anderer aktiver Lauf widerspricht dem Quellzustand (conflict).
- `429`: Ratenbegrenzung erreicht (rate_limited).
- `500`: Unerwarteter Fehler (internal).
- `503`: Der Dienst ist voruebergehend nicht verfuegbar (temporarily_unavailable). Dieselbe Anfrage spaeter erneut senden.

---

[API](https://skmtc.dev/firmenwatch/apis/firmenwatch-api.md) · [All operations](https://skmtc.dev/firmenwatch/apis/firmenwatch-api/llms.txt) · [OpenAPI document](https://skmtc.dev/firmenwatch/apis/firmenwatch-api/revisions/65e774135677?raw)