Dokumentation zu Schnittstelle und Webhooks

Die öffentliche NavyFlame-Schnittstelle ist eine Server-zu-Server-Schnittstelle. Jeden Aufruf autorisieren Sie mit einem Schlüssel, und die Antworten haben eine stabile, versionierte Form. Die Basisadresse liegt auf Ihrer eigenen Kontodomain:

https://{your-slug}.navyflame.com/api/public/v1

Die vollständige maschinenlesbare Spezifikation (OpenAPI 3.1) finden Sie unter /openapi-public-v1.yaml und importieren sie in Postman, Insomnia oder einen beliebigen OpenAPI-Client.

Legen Sie zuerst in der Oberfläche einen Schlüssel an (Konto - API) und prüfen Sie die Verbindung mit GET /me - das verlangt keinen Bereich, ein gültiger Schlüssel genügt. Es liefert Ihren Tarif, Ihre Limits und die Bereiche des Schlüssels.

curl https://{your-slug}.navyflame.com/api/public/v1/me \
  -H "Authorization: Bearer nf_live_your_key"

Eine Beispielantwort:

{
  "tenant": "your-slug",
  "keyPrefix": "nf_live_abc123",
  "scopes": ["orders:read", "orders:write"],
  "plan": "Professional",
  "rateLimitPerMin": 3000,
  "apiVersion": "v1"
}

Den Schlüssel übergeben Sie im Kopfteil Authorization als Bearer-Token (empfohlen). Für Werkzeuge ohne Bearer-Unterstützung gibt es den Alias X-API-Key:

Authorization: Bearer nf_live_your_key
# or
X-API-Key: nf_live_your_key

Schlüssel legen Sie in der Oberfläche an, erneuern und widerrufen sie dort. Wir speichern nur einen Hash des Schlüssels (SHA-256) - den vollen Wert sehen Sie einmal, beim Anlegen. Der Schlüssel wird aus allen Protokollen entfernt. Behandeln Sie ihn wie ein Passwort und legen Sie ihn nie im Browser ab.

Jeder Schlüssel trägt Bereiche. Ein Bereich :write schliesst den passenden :read ein. Fehlt ein nötiger Bereich, kommt 403 missing_scope zurück.

Limits gelten je Konto, nicht je Schlüssel. Die Kopfteile X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset in jeder Antwort nennen den Stand des Zeitfensters. Ist das Limit überschritten, erhalten Sie 429 mit dem Kopfteil Retry-After.

Lesen (seitenweise Abfrage über Cursor, Filter, Sortierung):

GET /orders            GET /orders/{id}          GET /orders/stats
GET /orders/{id}/status-history
GET /warehouse-items   GET /warehouse-items/{id}
GET /invoices          GET /invoices/{id}        GET /invoices/stats
GET /shipments         GET /shipments/{id}       GET /shipments/stats

Schreiben:

PUT   /orders/{id}/status            # change the status (transition matrix)
POST  /orders                        # create an order (source: api)
POST  /orders/{id}/invoice           # trigger invoicing
PATCH /warehouse-items/{id}/stock    # stock correction (set / adjust)

Ein Beispiel: die letzten Bestellungen.

curl "https://{your-slug}.navyflame.com/api/public/v1/orders?limit=25" \
  -H "Authorization: Bearer nf_live_your_key"

Ein Beispiel: den Bestand um 3 Stück verringern (atomar).

curl -X PATCH \
  "https://{your-slug}.navyflame.com/api/public/v1/warehouse-items/{id}/stock" \
  -H "Authorization: Bearer nf_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f9a...-unikat" \
  -d '{"operation":"adjust","quantity":-3}'

Nur lesende Auswertungsressourcen (die Bereiche reports:read, analytics:read, monitoring:read). Beträge in Berichten und Auswertungen sind Zahlen (Summen), anders als bei den Transaktionsressourcen, wo ein Betrag Text mit zwei Nachkommastellen ist.

GET /reports/sales                 GET /reports/sales/channels
GET /reports/sales/countries       GET /reports/products/bestsellers
GET /reports/products/high-returns GET /reports/products/low-rotation
GET /reports/operations/sla        GET /reports/operations/fulfillment
GET /reports/export/csv            GET /reports/export/xlsx     # binary files

GET /ai-ops/status                 GET /ai-ops/stock-predictions
GET /ai-ops/price-optimizations    GET /ai-ops/anomalies
GET /ai-ops/sales-forecast         GET /ai-ops/insights         # billable (LLM)

GET /monitoring/webhooks           GET /monitoring/webhooks/{id}
GET /monitoring/invoice-links      GET /monitoring/dlq
GET /monitoring/dlq/{id}           GET /monitoring/stats
GET /usage                         # counters, storage used, plan limits

Die Exporte /reports/export/csv und /xlsx sind die binäre Ausnahme von JSON - sie liefern eine Datei mit dem Kopfteil Content-Disposition: attachment (CSV in UTF-8 mit BOM, Semikolon als Trenner). Fehler kommen weiterhin als application/problem+json.

Die Details unter /monitoring/webhooks/{id} und /monitoring/dlq/{id} enthalten den rohen Inhalt der Anbindung (personenbezogene Daten der Käuferschaft), der Bereich monitoring:read ist deshalb als sensibel gekennzeichnet. Die Listen dieser Ressourcen geben keinen Inhalt zurück.

Ein Beispiel: eine Verkaufsübersicht der letzten 30 Tage.

curl "https://{your-slug}.navyflame.com/api/public/v1/reports/sales?periodDays=30" \
  -H "Authorization: Bearer nf_live_your_key"

Ressourcen mit personenbezogenen Daten (die Bereiche customers:read, email:read, notifications:read, alerts:read, postsale:read). Nur lesend.

GET /customers                     GET /customers/{email}
GET /customers/stats               GET /customers/{email}/orders
GET /customers/growth              GET /customers/export        # CSV

GET /email-templates(/{id})        GET /email-logs
GET /notifications(/{id})          GET /notifications/unread-count
GET /notification-preferences      # needs ?userId=

GET /alert-rules(/{id})            GET /alert-rules/history

GET /post-sale/capabilities        GET /post-sale/inbox
GET /post-sale/conversations(/{id})(/messages)
GET /post-sale/disputes(/{id})(/messages)
GET /post-sale/returns(/{id})      GET /post-sale/refunds

Eine Kundin oder ein Kunde ist eine gedachte Einheit (aus Bestellungen zusammengeführt), angesprochen über die E-Mail-Adresse. Benachrichtigungen gelten für das ganze Konto (ein Schlüssel steht nicht für eine einzelne Person); das optionale ?userId= grenzt sie auf eine empfangende Person ein, und die Einstellungen verlangen es. Die Nachverkaufsbearbeitung liest nur, was im System gespeichert ist (keine Aufrufe beim Marktplatz auf Ihre Kosten); die Verfügbarkeit sehen Sie unter /post-sale/capabilities.

Die Bereiche customers:read, email:read und postsale:read geben personenbezogene Daten preis - vergeben Sie sie nur an Anbindungen, denen Sie vertrauen, und verarbeiten Sie die Daten im Einklang mit der DSGVO.

Vollständiges Schreiben im Katalog (die Bereiche catalog:read / catalog:write). Anlegende und unumkehrbare Vorgänge verlangen den Kopfteil Idempotency-Key - eine Wiederholung mit demselben Schlüssel gibt das gespeicherte Ergebnis zurück, statt den Vorgang erneut auszuführen.

# Products
POST/PUT/DELETE /warehouse-items(/{id})   POST /warehouse-items/{id}/backorder
GET  /warehouse-items/by-barcode          GET  /warehouse-items/{id}/stock-history
# Warehouses and locations
GET/POST/PUT/DELETE /warehouses(/{id})
GET /warehouse-items/{id}/locations       PUT /warehouse-items/{id}/locations/{warehouseId}
GET/PUT /warehouse-settings
# Reservations and stock documents
GET/POST /reservations                    DELETE /reservations/{id}
GET/POST /stock-documents(/{id})          POST /stock-documents/{id}/lines
POST /stock-documents/{id}/commit         POST /stock-documents/{id}/cancel
# Bundles
GET /bundles(/{id})   PUT /bundles/{id}   DELETE /bundles/{id}

Beschreibungs- und Artikelvorlagen (die Bereiche templates:read / templates:write). Das Anwenden einer Vorlage legt einen Artikel an, deshalb verlangt POST /product-templates/{id}/apply zusätzlich catalog:write.

GET/POST/PUT/DELETE /description-templates(/{id})
GET/POST/PUT/DELETE /product-templates(/{id})
PUT  /product-templates/{id}/variants                  # replace the whole set of variants
POST /product-templates/{id}/variants                  # add a variant
PATCH/DELETE /product-templates/{id}/variants/{variantId}
POST /product-templates/{id}/apply                     # + catalog:write

KI-Inhalte (die Bereiche ai:read / ai:write). Erzeugen und Übersetzen sind bei Ihrem eigenen KI-Anbieter kostenpflichtige Vorgänge (den Schlüssel richten Sie unter Anbindungen ein), deshalb ist Idempotency-Key erforderlich - eine Wiederholung gibt das Ergebnis zurück und rechnet es nicht erneut ab. Das Schreiben des Ergebnisses in einen Artikel (applyToProduct / createNewProducts) verlangt zusätzlich catalog:write. Mengenvorgänge geben je Position eine gekürzte Vorschau zurück - den vollen Text holen Sie aus /ai/generation-logs oder aus dem Artikel.

GET/PUT /ai/settings                 GET /ai/generation-logs
POST /ai/generate-description        POST /ai/translate
POST /ai/batch-generate              POST /ai/batch-translate     # up to 50 items
POST /ai/preview-template            # no AI; templates:read + catalog:read

Ein Beispiel: eine Beschreibungsvorlage anlegen (idempotent).

curl -X POST \
  "https://{your-slug}.navyflame.com/api/public/v1/description-templates" \
  -H "Authorization: Bearer nf_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1e-tpl-001" \
  -d '{"name":"Premium description","templateBody":"{{productName}} - {{price}} {{currency}}"}'

Versandeinrichtung (die Bereiche shipping:read / shipping:write): Versandregeln, Zonen mit Tarifen, Zustelloptionen und Ausnahmen je Artikel, dazu der Kostenrechner. Anlegende Vorgänge verlangen den Kopfteil Idempotency-Key. Beträge und Gewicht übergeben Sie beim Schreiben als Zahlen (nicht als Text). Das ist die Einrichtung, nicht die Abwicklung beim Transporteur - das Aufgeben von Sendungen und die Etiketten kommen in einer eigenen Phase.

# Shipping rules
GET/POST/PUT/DELETE /shipping-rules(/{id})
# Zones and rates (a rate belongs to its owning zone)
GET/POST/PUT/DELETE /shipping-zones(/{id})
POST /shipping-zones/{id}/rates       PUT/DELETE /shipping-zones/{id}/rates/{rateId}
# Delivery options
GET/POST/PUT/DELETE /delivery-options(/{id})
# Per-product shipping overrides
GET/POST /products/{productId}/shipping-overrides
PUT/DELETE /product-shipping-overrides/{id}
# Cost calculator (a POST, but it only needs shipping:read)
POST /shipping/calculate

Namen sind nicht eindeutig, ein Konflikt durch Doppelung (409) entsteht also nicht. Die deliveryOptionId an einem Tarif oder einer Ausnahme muss auf Ihre eigene Zustelloption zeigen (sonst 422), und ein Tarif ausserhalb Ihrer Zone gibt 404. Der Rechner liefert die Optionen aufsteigend nach Kosten sortiert.

Ein Beispiel: die Versandkosten nach Polen berechnen.

curl -X POST \
  "https://{your-slug}.navyflame.com/api/public/v1/shipping/calculate" \
  -H "Authorization: Bearer nf_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"countryCode":"PL","orderValue":199.99,"totalWeightKg":1.5,"itemCount":2}'

Lebenszyklus der Sendung (der Bereich shipments:write) und unterstützende Abfragen beim Transporteur (der Bereich shipments:read): Sie legen eine Sendung an, bestellen ein Etikett beim Transporteur, stornieren, frischen die Verfolgung auf und übergeben die Sendungsnummer an Allegro. Gewicht, Masse und Beträge übergeben Sie als Zahlen.

# Creating a shipment (status Draft; costs nothing)
POST   /shipments                    # one at a time
POST   /shipments/bulk               # in bulk, up to 100 (partial success)
# The carrier label
POST   /shipments/{id}/label         # BILLABLE - buying a label (Idempotency-Key required)
GET    /shipments/{id}/label         # fetch the label (PDF, binary)
# The rest of the lifecycle
DELETE /shipments/{id}               # delete a draft or cancel with the carrier
POST   /shipments/{id}/refresh-tracking
POST   /shipments/{id}/push-tracking
# Helper reads (shipments:read)
GET    /shipments/points                       # pickup points (InPost, Poczta Polska, Furgonetka)
GET    /couriers/{provider}/services           # carrier services (Apaczka, Furgonetka)
GET    /shipments/allegro/delivery-services    # Allegro Delivery services
POST   /shipments/available-dates              # pickup dates (DHL; a POST, but shipments:read)

Ein Etikett zu bestellen ist kostenpflichtig - es kauft eine echte Sendung beim Transporteur. Deshalb verlangt POST /shipments/{id}/label den Kopfteil Idempotency-Key: eine Wiederholung mit demselben Schlüssel gibt das gespeicherte Ergebnis zurück und kauft nie ein zweites Etikett (der Schutz liegt auf dem Server). Ein Etikett bestellen Sie nur für eine Sendung im Entwurf. Das Herunterladen des Etiketts (GET .../label) ist die binäre Ausnahme - es liefert application/pdf, nicht JSON.

Eine Transporteur- oder Allegro-Anbindung, die nicht verbunden ist, gibt 403 not_supported zurück (nie ein 500), ein Fehler beim Transporteur oder bei Allegro gibt 502 bad_gateway. Unterstützende Abfragen bei einem nicht unterstützten Anbieter geben { "supported": false } zurück statt eines Fehlers. Eine Stornierung ändert den lokalen Status nicht, wenn der Transporteur den Vorgang ablehnt.

Ein Beispiel: ein Etikett bestellen (idempotent, kostenpflichtig).

curl -X POST \
  "https://{your-slug}.navyflame.com/api/public/v1/shipments/{id}/label" \
  -H "Authorization: Bearer nf_live_your_key" \
  -H "Idempotency-Key: 6f9a...-label-001"

Anbindungen entdecken (der Bereich integrations:read) sowie Lese- und Schreibvorgänge für Marktplatzangebote (die Bereiche offers:read / offers:write). Ein Teil der Vorgänge ist lokal (aus Ihren eigenen Daten, ohne Kosten), ein anderer sind Live-Aufrufe gegen Entgelt bei der Anbindung - unten gekennzeichnet.

Entdecken und lokale Abfragen (ohne Kosten):

GET /connectors                          # the list of connectors (no secrets)
GET /warehouse-items/{id}/listings       # the product's marketplace offers (keyset)
GET /category-mappings                   # category mappings (keyset)

GET /connectors gibt einen streng begrenzten Satz an Feldern zurück - key, configId, displayName, enabled und connected - und gibt nie Zugangsdaten zurück (keine Schlüssel, Tokens oder Passwörter der Anbindung). Das Feld connected ist ein errechneter Zustand: die Anbindung ist aktiviert und hat gespeicherte Zugangsdaten. Den Wert configId übergeben Sie in Kategoriezuordnungen als Filter ?sourceConfigId= oder ?destConfigId=.

Die Angebote eines Artikels (/warehouse-items/{id}/listings) verbinden eine Lagerposition mit einem Angebot im Kanal (die fremde Kennung, Preis und Status auf Seiten des Marktplatzes, eine mögliche Preisausnahme je Kanal). Jedes Angebotsobjekt trägt eine instanceId, also die dauerhafte Kennung einer bestimmten Verbindung, sowie einen instanceName zur Anzeige. So kann derselbe Artikel unabhängige Angebote, Preise und Abgleichszustände etwa auf ebay.de und ebay.com haben. Das Feld lastSyncError wird von Mustern bereinigt, die wie Zugangsdaten aussehen und in einem Fehler der Anbindung stecken könnten.

Ein Beispiel: die Anbindungen des Kontos.

curl "https://{your-slug}.navyflame.com/api/public/v1/connectors" \
  -H "Authorization: Bearer nf_live_your_key"

Live-Abfragen beim Marktplatz (der Bereich offers:read) führen einen echten Aufruf bei der Anbindung aus - sie sind kostenpflichtig (sie zählen auf das Limit der Anbindung), aber ausschliesslich lesend (sie veröffentlichen und ändern kein Angebot). Eine nicht verbundene Anbindung gibt 403 not_supported zurück (nie 500), ein Fehler auf Seiten des Marktplatzes gibt 502 bad_gateway. Die Form der Daten hängt von der Anbindung ab.

GET /marketplace/{connectorKey}/products
GET /marketplace/{connectorKey}/products/{externalProductId}
GET /marketplace/{connectorKey}/categories?q=fraza
GET /marketplace/{connectorKey}/categories/{categoryId}/parameters
GET /marketplace/{connectorKey}/responsible-producers
GET /marketplace/{connectorKey}/responsible-persons

Das Schreiben von Kategoriezuordnungen (der Bereich offers:write) sind lokale Schreibvorgänge - keiner davon veröffentlicht oder ändert ein echtes, für die Käuferschaft sichtbares Angebot (das Veröffentlichen echter Angebote ist unten beschrieben). POST /category-mappings verlangt den Kopfteil Idempotency-Key (eine Doppelung gibt 409); sync frischt den lokalen Zwischenspeicher der Kategorien aus der Anbindung auf (kostenpflichtig, aber idempotent).

POST   /category-mappings           # create (Idempotency-Key required; a duplicate -> 409)
POST   /category-mappings/bulk      # in bulk (up to 1000; duplicates skipped)
PUT    /category-mappings/{id}       # repoint the mapping at another target
DELETE /category-mappings/{id}       # delete the mapping
POST   /category-mappings/sync      # refresh the local category cache (billable, idempotent)

Das Veröffentlichen und Abgleichen echter Angebote (der Bereich offers:write) legt ein für die Käuferschaft sichtbares Angebot im Kanal an oder aktualisiert es - kostenpflichtige Vorgänge (ein echter Aufruf beim Marktplatz). publish und sync verlangen den Kopfteil Idempotency-Key (eine Wiederholung mit demselben Schlüssel gibt die gespeicherte Antwort zurück, statt den kostenpflichtigen Aufruf zu wiederholen). publish gibt 409 zurück, wenn der Artikel auf genau dieser Verbindung bereits veröffentlicht ist (oder seine Veröffentlichung läuft) - ein Angebot auf einer anderen Instanz derselben Anbindung erzeugt keinen Konflikt. Nutzen Sie dann sync für dieselbe configId. Eine nicht verbundene Anbindung gibt 403 not_supported, ein Fehler auf Seiten des Marktplatzes gibt 502 bad_gateway.

Übergeben Sie im Inhalt von publish, sync und PUT .../pricing die configId, die Sie von GET /connectors erhalten haben. Hat eine Anbindung mehrere aktivierte Verbindungen, endet ein Weglassen des Feldes mit 422 validation_failed. Die Schnittstelle wählt kein Standardkonto blind aus. Gibt es genau eine aktivierte Verbindung, kann sie diese selbst auflösen.

Wichtig bei einem 502 beim Veröffentlichen: eine Zeitüberschreitung oder ein 5xx des Marktplatzes ist mehrdeutig - das Angebot kann entstanden sein. Eine Wiederholung mit demselben Idempotency-Key gibt dasselbe 502 zurück (sie veröffentlicht nicht erneut). Prüfen Sie das Angebot im Kanal und wiederholen Sie mit einem neuen Idempotency-Key erst, wenn Sie wissen, dass das Angebot nicht entstanden ist.

POST /warehouse-items/{id}/publish/{connectorKey}          # publish the offer (billable; Idempotency-Key required)
POST /warehouse-items/{id}/sync/{connectorKey}             # update the offer (billable; Idempotency-Key required)
POST /warehouse-items/{id}/pull/{connectorKey}             # pull the offer from the channel into the catalogue
POST /warehouse-items/{id}/refresh-status/{connectorKey}   # refresh the status of one offer
POST /warehouse-items/refresh-status                       # in bulk (up to 100 products)
PUT  /warehouse-items/{id}/listings/{connectorKey}/pricing # price per instance (local, no outbound call)

# Body for publish / sync:
{ "configId": "8d1ec28d-..." }

# Body for pricing:
{ "configId": "8d1ec28d-...", "mode": "markup", "value": 12.5 }

Ein Angebot ins Lager importieren ( POST /catalog/import) legt aus einem Marktplatzartikel eine Lagerposition an. Es verlangt zwei Bereiche zugleich - offers:write und catalog:write (fehlt einer, gibt es 403 missing_scope) - sowie den Kopfteil Idempotency-Key. Eine doppelte Artikelnummer oder ein doppelter Strichcode geben 409 conflict.

POST /catalog/import   # import a marketplace product -> a stock item (offers:write + catalog:write)

Schreibvorgänge für Kommunikation, erneute Verarbeitung und Nachverkauf (die Bereiche notifications:write, alerts:write, email:write, monitoring:write, postsale:write und postsale:refunds:write). Anlegende und unumkehrbare Vorgänge verlangen den Kopfteil Idempotency-Key; von Natur aus idempotente Vorgänge (als gelesen markieren, umschalten) beachten ihn wahlweise.

# Notifications (notifications:write)
POST /notifications                  # create (the recipient must be a member of the account; Idempotency-Key required)
POST /notifications/{id}/read        # mark one as read
POST /notifications/read-all         # mark all (needs ?userId=)
# Alerts (alerts:write)
POST /alert-rules                    # create a rule (Idempotency-Key required)
PUT/DELETE /alert-rules/{id}         # update / delete
POST /alert-rules/{id}/toggle        # enable / disable
# E-mail (email:write)
POST/PUT/DELETE /email-templates(/{id})   # templates (plan limit; a duplicate name -> 409)
POST /emails/send                    # BILLABLE - a real send (Idempotency-Key required)

Das Anlegen einer Benachrichtigung prüft, ob recipientUserId Mitglied des Kontos ist (keine Mitgliedschaft gibt 422, eine unsichere Prüfung gibt 503) - ein Schlüssel darf nicht das Postfach einer beliebigen Person fluten. E-Mail-Vorlagen unterliegen der Tarifgrenze (Basic 10, Professional 24, Enterprise ohne Limit) und geben sonst 403 plan_limit, ein doppelter Name gibt 409. Der E-Mail-Versand (`POST /emails/send`) ist kostenpflichtig und hat ein eigenes Limit von etwa 10 pro Stunde je Konto ( 429); ein Anbieter ohne Einrichtung gibt 403 not_supported, ein Übertragungsfehler gibt 502 bad_gateway. Eine Warnregel mit dem Kanal email oder both erzeugt beim Auslösen mittelbar Versand.

Die erneute Verarbeitung der Fehlerliste (der Bereich monitoring:write) startet den ursprünglichen Ablauf eines Eintrags - bei Quellen der Rechnungsstellung entsteht eine echte Rechnung, sie ist also kostenpflichtig und folgenreich, und Idempotency-Key ist erforderlich. Wiederholbar sind nur drei Quellen (shopify_to_wfirma_pipeline, shopify, wfirma_invoice) - andere geben 422; ein nicht erreichbares Temporal gibt 503. Eine Wiederholung ist über eine feste Prozesskennung idempotent (sie gibt alreadyRunning zurück).

POST /monitoring/dlq/{id}/retry      # BILLABLE - runs the original process (Idempotency-Key required)

Nachverkaufsbearbeitung (der Bereich postsale:write): Sie antworten in Verläufen und Streitfällen, ändern den Status eines Streitfalls und nehmen eine Rücksendung an oder lehnen sie ab. Die Zugehörigkeit von Verlauf, Streitfall oder Rücksendung wird vor dem Aufruf des Kanals geprüft (eine fremde oder nicht vorhandene Kennung gibt 404), und die Vorgänge hängen je Anbindung von deren Fähigkeiten ab - fehlt eine Fähigkeit oder Methode, kommt 403 not_supported (nie 500). Ein Fehler des Kanals gibt 502 bad_gateway.

# Post-sale handling with no movement of money (postsale:write)
POST /post-sale/conversations/{id}/messages   # reply to the buyer (Idempotency-Key required)
POST /post-sale/conversations/{id}/read        # mark the thread read
POST /post-sale/disputes/{id}/messages         # reply in a dispute (Idempotency-Key required)
POST /post-sale/disputes/{id}/status           # a decision in a dispute (see money isolation)
POST /post-sale/returns/{id}/accept            # accept the return
POST /post-sale/returns/{id}/reject            # reject the return
# Refunds - a SEPARATE money scope (postsale:refunds:write)
POST /post-sale/refunds/issue                  # a REAL refund to the buyer
POST /post-sale/refunds/commission-claim       # a commission refund

Geld ist abgetrennt. Eine Rückzahlung hat einen eigenen Bereich `postsale:refunds:write`, getrennt von postsale:write, damit ein durchgesickerter Schlüssel ohne ihn kein Geld bewegen kann. Die Route POST /post-sale/disputes/{id}/status gehört zu postsale:write, doch wenn die Entscheidung Geld an die Käuferschaft bewegt (ein vorhandenes partialRefund oder der Status ACCEPTED_REFUND / ACCEPTED_PARTIAL_REFUND), muss der Schlüssel zusätzlich `postsale:refunds:write` tragen - sonst gibt die Anfrage 403 missing_scope zurück und es geschieht nichts.

Rückzahlungen wiederholen. refunds/issue und commission-claim sind auf Seiten des Kanals idempotent (Ihr Idempotency-Key wird zur Kennung des Vorgangs beim Kanal) - wiederholen Sie bei einem 502 mit demselben Schlüssel, der Kanal entfernt die Doppelung. Eine Entscheidung im Streitfall, die Geld bewegt, hat dagegen beim Kanal keine Idempotenz - prüfen Sie bei einem unklaren Fehler das Ergebnis im Verkaufskanal und wiederholen Sie erst mit einem neuen Idempotency-Key (für denselben Schlüssel kommt dasselbe 502 zurück).

Ein Beispiel: eine echte Rückzahlung (idempotent, kostenpflichtig).

curl -X POST \
  "https://{your-slug}.navyflame.com/api/public/v1/post-sale/refunds/issue" \
  -H "Authorization: Bearer nf_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f9a...-refund-001" \
  -d '{"connectorKey":"shopify","instanceId":"shop-1","orderExternalId":"1234","amount":49.99,"currency":"PLN"}'

Ein vollständiges, begehbares Verzeichnis aller öffentlichen v1-Endpunkte, nach Ressourcen gruppiert. Das ist die Ebene für Menschen - die vollständigen Schemata für Anfragen und Antworten bis auf Feldebene (179 Stück) stehen in der OpenAPI-Spezifikation . Jeder lebende Endpunkt ist hier aufgeführt.

• Bereich - der nötige Bereich des Schlüssels. Ein Bereich :write schliesst den passenden :read ein. Die Schreibweise a + b heisst bereichsübergreifend (beide zugleich nötig).
• Idem. - K! = der Kopfteil Idempotency-Key ist erforderlich; K? = wird beachtet (optional); leer = nicht zutreffend (Lesevorgang).
• Fehler - die wichtigen Codes ausser den überall möglichen 401, 403 und 429 (sowie 500/503, die überall auftreten können).

Listen geben wir seitenweise über Cursor aus (ohne Offset). Die Antwort trägt pagination.nextCursor - übergeben Sie ihn im Parameter cursor, um die nächste Seite zu holen. Der Parameter updatedSince (ein Zeitpunkt nach ISO mit Zone) liefert Datensätze, die seit diesem Moment geändert wurden. Fragen Sie für einen abholenden Abgleich mit überlappendem Fenster ab und entfernen Sie Doppel über die id.

GET /orders?limit=50&cursor=eyJjIjoi...&updatedSince=2026-07-01T00:00:00Z

Schreibvorgänge schützt der Kopfteil Idempotency-Key (ein beliebiger eindeutiger Wert, empfohlen ist eine UUID, bis 255 Zeichen). Er ist bei POST /orders und POST /orders/{id}/invoice erforderlich und wird bei PUT und PATCH beachtet.

• Eine Wiederholung mit demselben Schlüssel und demselben Inhalt gibt das gespeicherte Ergebnis zurück (Kopfteil Idempotency-Replayed: true), ohne doppelte Wirkung.
• Derselbe Schlüssel mit anderem Inhalt gibt 409 idempotency_conflict zurück.
• Ein gleichzeitiges Duplikat in Bearbeitung gibt 409 idempotency_in_progress mit Retry-After zurück.
• Schlüssel laufen nach 24 Stunden ab.

Fertige Ausschnitte in drei Varianten: curl, JavaScript (fetch, Node 20+) und Python (die Bibliothek requests). Die Varianten für JS und Python setzen die Konstanten BASE (Basisadresse) und KEY (der Schlüssel aus einem sicheren Speicher) voraus, gesetzt im Beispiel zur Anmeldung.

Anmeldung (Bearer und X-API-Key)

curl

# Bearer (recommended)
curl https://{your-slug}.navyflame.com/api/public/v1/me \
  -H "Authorization: Bearer nf_live_your_key"

# The X-API-Key alias (tools without Bearer support)
curl https://{your-slug}.navyflame.com/api/public/v1/me \
  -H "X-API-Key: nf_live_your_key"

JavaScript

const BASE = "https://my-shop.navyflame.com/api/public/v1";
const KEY = process.env.NAVYFLAME_API_KEY;

const res = await fetch(BASE + "/me", {
  headers: { Authorization: "Bearer " + KEY },
});
if (!res.ok) throw new Error("HTTP " + res.status);
const me = await res.json();
console.log(me.plan, me.scopes);

Python

import os, requests

BASE = "https://my-shop.navyflame.com/api/public/v1"
KEY = os.environ["NAVYFLAME_API_KEY"]

r = requests.get(BASE + "/me", headers={"Authorization": "Bearer " + KEY})
r.raise_for_status()
me = r.json()
print(me["plan"], me["scopes"])

Seitenweise Abfrage über Cursor (Schleife und Entdopplung)

curl

curl "https://{your-slug}.navyflame.com/api/public/v1/orders?limit=100&updatedSince=2026-07-01T00:00:00Z" \
  -H "Authorization: Bearer nf_live_your_key"
# the response carries pagination.nextCursor -> pass it as &cursor=... on the next call

JavaScript

async function* paginate(path) {
  let cursor = null;
  do {
    const url = new URL(BASE + path);
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("cursor", cursor);
    const res = await fetch(url, {
      headers: { Authorization: "Bearer " + KEY },
    });
    if (res.status === 429) {
      const wait = Number(res.headers.get("Retry-After") || 1);
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    if (!res.ok) throw new Error("HTTP " + res.status);
    const page = await res.json();
    for (const row of page.data) yield row;
    cursor = page.pagination.nextCursor;
  } while (cursor);
}

const seen = new Set();
for await (const order of paginate("/orders?updatedSince=2026-07-01T00:00:00Z")) {
  if (seen.has(order.id)) continue; // deduplicate by id
  seen.add(order.id);
  // ... process the order
}

Python

import time

def paginate(path, params=None):
    params = dict(params or {})
    params["limit"] = 100
    while True:
        r = requests.get(BASE + path, params=params,
                         headers={"Authorization": "Bearer " + KEY})
        if r.status_code == 429:
            time.sleep(int(r.headers.get("Retry-After", "1")))
            continue
        r.raise_for_status()
        page = r.json()
        for row in page["data"]:
            yield row
        cursor = page["pagination"]["nextCursor"]
        if not cursor:
            break
        params["cursor"] = cursor

seen = set()
for order in paginate("/orders", {"updatedSince": "2026-07-01T00:00:00Z"}):
    if order["id"] in seen:  # deduplicate by id
        continue
    seen.add(order["id"])
    # ... process the order

Ein idempotenter Schreibvorgang (Idempotency-Key und wachsende Abstände)

curl

curl -X POST "https://{your-slug}.navyflame.com/api/public/v1/orders" \
  -H "Authorization: Bearer nf_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f1c9a20-7b2e-4c6d-9f10-000000000001" \
  -d '{"customer":{"name":"Jan Kowalski"},"lineItems":[{"title":"Kubek 300 ml","sku":"KUB-300-BIA","quantity":2,"unitPrice":"39.99","taxRate":"23"}],"currency":"PLN"}'

JavaScript

import { randomUUID } from "node:crypto";

async function createOrder(body) {
  const key = randomUUID(); // the same key on every retry
  for (let attempt = 0; attempt < 5; attempt++) {
    const res = await fetch(BASE + "/orders", {
      method: "POST",
      headers: {
        Authorization: "Bearer " + KEY,
        "Content-Type": "application/json",
        "Idempotency-Key": key,
      },
      body: JSON.stringify(body),
    });
    if (res.status === 429 || res.status === 502 || res.status === 503) {
      const wait = Number(res.headers.get("Retry-After") || 2 ** attempt);
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue; // transient - retry with the same key
    }
    if (res.status === 409) {
      const problem = await res.json();
      if (problem.code === "idempotency_in_progress") {
        await new Promise((r) => setTimeout(r, 1000));
        continue;
      }
      throw new Error("idempotency conflict: " + problem.code); // a different body
    }
    if (!res.ok) throw new Error("HTTP " + res.status);
    return res.json(); // 201 or replayed (Idempotency-Replayed: true)
  }
  throw new Error("wyczerpano proby ponowienia");
}

Python

import time
from uuid import uuid4

def create_order(body):
    key = str(uuid4())  # the same key on every retry
    for attempt in range(5):
        r = requests.post(BASE + "/orders", json=body, headers={
            "Authorization": "Bearer " + KEY,
            "Idempotency-Key": key,
        })
        if r.status_code in (429, 502, 503):
            time.sleep(int(r.headers.get("Retry-After", 2 ** attempt)))
            continue  # transient - retry with the same key
        if r.status_code == 409:
            code = r.json().get("code")
            if code == "idempotency_in_progress":
                time.sleep(int(r.headers.get("Retry-After", "1")))
                continue
            raise RuntimeError("idempotency conflict: " + str(code))
        r.raise_for_status()
        return r.json()  # 201 or replayed
    raise RuntimeError("wyczerpano proby ponowienia")

Die Prüfung der Webhook-Signatur (JavaScript und Python) finden Sie im Abschnitt Ausgehende Webhooks .

Fehler geben wir nach RFC 9457 zurück (application/problem+json). Jeder trägt einen stabilen code und eine requestId zur Zuordnung beim Support.

{
  "type": "https://navyflame.com/dokumentacja/api/bledy#validation_failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "Invalid order input.",
  "code": "validation_failed",
  "requestId": "req_abc123",
  "errors": [{ "field": "lineItems[0].unitPrice", "message": "Kwota >= 0 (jako string)." }]
}

Die Codes 500 (internal) und 503 (service_unavailable) können bei jedem Vorgang auftreten und werden nicht je Endpunkt aufgeführt. Auslieferungen laufen fortlaufend - ein Client sollte vereinzelte 502/503 als vorübergehend behandeln (Wiederholung mit wachsendem Abstand) und Schreibvorgänge mit einem Idempotency-Key absichern. Das Feld type in problem+json zeigt auf den Anker dieses Abschnitts (etwa #validation_failed).

Sie abonnieren ein Ereignis und geben eine HTTPS-Adresse an, dann senden wir dorthin eine signierte Benachrichtigung. Die Ereignisse in v1 sind order.synced, order.status_changed, invoice.issued, shipment.status_updated und catalog.updated. Jede Zustellung trägt die Kopfteile X-NavyFlame-Event, X-NavyFlame-Delivery-Id und X-NavyFlame-Signature. Erfolg ist eine 2xx-Antwort innerhalb von 5 Sekunden; bei einem Fehlschlag wiederholen wir mit wachsendem Abstand etwa 24 Stunden lang, und den Zustellverlauf sehen Sie in der Oberfläche.

Die Form des Inhalts (der gemeinsame Rahmen):

{
  "id": "evt_9f4c2f6a-...",
  "type": "order.synced",
  "apiVersion": "v1",
  "occurredAt": "2026-07-07T12:00:00Z",
  "tenant": "your-slug",
  "origin": { "channel": "api", "apiKeyPrefix": "nf_live_abc123" },
  "data": { "order": { }, "isNew": true }
}

Das Feld origin.channel (api | panel | sync | automation) erlaubt es, eine Rückkopplung zu unterbrechen - haben Sie die Änderung selbst mit einem Schlüssel ausgelöst, erkennen Sie das an apiKeyPrefix und überspringen das Ereignis. Die empfangende Seite entfernt Doppel über die id des Ereignisses und über den Kopfteil X-NavyFlame-Delivery-Id (Zustellung mindestens einmal, ohne Zusage zur Reihenfolge).

Der Ereigniskatalog (v1)

Eine geschlossene Liste der Ereignisse in v1 - neue Typen sind eine ergänzende Änderung, die empfangende Seite muss also unbekannte Felder und Typen übergehen. Jedes Ereignis trägt den gemeinsamen Rahmen (oben); der typspezifische Inhalt steht im Feld data:

{
  "id": "evt_9f4c2f6a-1b2c-4d3e-8a9b-000000000001",
  "type": "order.synced",
  "apiVersion": "v1",
  "occurredAt": "2026-07-09T12:00:00Z",
  "tenant": "my-shop",
  "origin": { "channel": "sync" },
  "data": {
    "order": { "id": "0e6b7c...", "orderNumber": "2026/07/000123",
               "status": "Processing", "totalPrice": "129.99", "currency": "PLN" },
    "isNew": false
  }
}

{
  "id": "evt_2b3c4d5e-6f70-4a8b-9c0d-000000000005",
  "type": "order.status_changed",
  "apiVersion": "v1",
  "occurredAt": "2026-08-30T10:30:00Z",
  "tenant": "my-shop",
  "origin": { "channel": "api", "apiKeyPrefix": "nf_live_abc123" },
  "data": {
    "order": { "id": "0e6b7c...", "orderNumber": "2026/08/000321",
               "status": "Processing", "totalPrice": "129.99", "currency": "PLN" },
    "previousStatus": "New"
  }
}

{
  "id": "evt_1a2b3c4d-5e6f-4a7b-8c9d-000000000002",
  "type": "invoice.issued",
  "apiVersion": "v1",
  "occurredAt": "2026-07-09T12:03:00Z",
  "tenant": "my-shop",
  "origin": { "channel": "automation" },
  "data": {
    "invoice": { "id": "7a1c9e...", "number": "FV/2026/07/45",
                 "status": "Issued", "grossAmount": "129.99", "currency": "PLN" }
  }
}

{
  "id": "evt_2b3c4d5e-6f7a-4b8c-9d0e-000000000003",
  "type": "shipment.status_updated",
  "apiVersion": "v1",
  "occurredAt": "2026-07-09T12:10:00Z",
  "tenant": "my-shop",
  "origin": { "channel": "sync" },
  "data": {
    "shipment": { "id": "b2d9f1...", "courierProvider": "inpost",
                  "status": "InTransit", "trackingNumber": "6800000000001" },
    "previousStatus": "PickedUp"
  }
}

{
  "id": "evt_3c4d5e6f-7a8b-4c9d-0e1f-000000000004",
  "type": "catalog.updated",
  "apiVersion": "v1",
  "occurredAt": "2026-07-09T12:15:00Z",
  "tenant": "my-shop",
  "origin": { "channel": "api", "apiKeyPrefix": "nf_live_abc123" },
  "data": {
    "warehouseItemId": "c4e1a2...", "sku": "KUB-300-BIA",
    "changeType": "updated", "stockQuantity": 42
  }
}
// The bulk variant (data):
// { "bulk": true, "source": "wholesale-import", "itemsChanged": 128 }

Prüfung der Signatur

Der Kopfteil X-NavyFlame-Signature hat die Form t=<unix>,v1=<hex>, wobei v1 = HMAC-SHA256(Geheimnis, "<t>." + roher_Inhalt). Der Kopfteil kann mehrere Paare v1= tragen (ein Zeitfenster für den Wechsel des Geheimnisses - altes und neues Geheimnis signieren 24 h parallel) - nehmen Sie jedes an, das passt. Prüfen Sie, ob der Zeitstempel stimmt (Toleranz 300 s), um sich gegen eine Wiedereinspielung zu schützen.

JavaScript (Node)

import crypto from "node:crypto";

function verify(signatureHeader, rawBody, secret) {
  const parts = Object.create(null);
  const sigs = [];
  for (const p of String(signatureHeader).split(",")) {
    const [k, v] = p.split("=");
    if (k === "t") parts.t = v;
    if (k === "v1" && v) sigs.push(v);
  }
  if (!parts.t || sigs.length === 0) return false;
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const computed = crypto
    .createHmac("sha256", secret)
    .update(parts.t + "." + rawBody)
    .digest("hex");
  return sigs.some(
    (s) =>
      s.length === computed.length &&
      crypto.timingSafeEqual(
        Buffer.from(computed, "hex"),
        Buffer.from(s, "hex"),
      ),
  );
}

Python

import hashlib, hmac, time

def verify(signature_header, raw_body, secret):
    t = None
    sigs = []
    for part in signature_header.split(","):
        k, _, v = part.partition("=")
        if k == "t":
            t = v
        elif k == "v1" and v:
            sigs.append(v)
    if not t or not sigs:
        return False
    if abs(time.time() - int(t)) > 300:  # replay protection
        return False
    computed = hmac.new(
        secret.encode(), (t + "." + raw_body).encode(), hashlib.sha256
    ).hexdigest()
    return any(hmac.compare_digest(computed, s) for s in sigs)

Prüfen Sie die Signatur gegen den rohen Anfrageinhalt (die Bytes vor dem Auswerten des JSON) - ein erneutes Serialisieren ändert die Bytes und die Signatur passt nicht mehr. raw_body / rawBody sind genau die im POST-Inhalt empfangenen Bytes, vor dem Dekodieren des JSON.

Ein Rezept für Zapier und Make

1. Legen Sie in Zapier einen Zap mit dem Auslöser Webhooks by Zapier - Catch Hook an (in Make: das Modul Custom Webhook). Kopieren Sie die erzeugte Adresse.
2. Fügen Sie in der NavyFlame-Oberfläche (Konto - API - Webhooks) ein Abonnement hinzu: wählen Sie das Ereignis und fügen Sie die Adresse als Ziel ein. Das Signaturgeheimnis sehen Sie einmal, bewahren Sie es auf.
3. Nutzen Sie die Schaltfläche Test senden in der Oberfläche, um zu bestätigen, dass Ihr Ablauf den Inhalt empfängt.
4. (Empfohlen) Fügen Sie mit der obigen Funktion einen Schritt zur Signaturprüfung ein, bevor Sie den Daten vertrauen.

DSGVO

Die Inhalte der Webhooks tragen personenbezogene Daten der Käuferschaft. Wenn Sie ein Abonnement einrichten (die Zieladresse wählen, etwa Zapier, meist eine Übermittlung ausserhalb des EWR), handeln Sie als verantwortliche Stelle für diese Daten, und das Abonnement ist Ihre dokumentierte Weisung zur Verarbeitung. Die Löschung oder Anonymisierung von Käuferdaten in Systeme weiterzugeben, die über Schnittstelle und Webhooks gespeist werden, liegt bei Ihnen.

Schnellstart (vom Schlüssel zum ersten Aufruf)

1. Legen Sie in der Oberfläche (Konto - API) einen Schlüssel mit den nötigen Bereichen an. Den Schlüssel sehen Sie nur einmal, bewahren Sie ihn in einem sicheren Speicher auf.
2. Bestätigen Sie die Verbindung: GET /me (braucht keinen Bereich). Es liefert Tarif, Limits und die Bereiche des Schlüssels.
3. Machen Sie den ersten Aufruf gegen die gewünschte Ressource, etwa GET /orders?limit=25.

Abholender Abgleich (updatedSince, überlappendes Fenster und Entdopplung)

1. Fragen Sie mit updatedSince = letzter_Abgleich - Überlappungsfenster ab (etwa 5 Minuten). Die Bedeutung ist einschliessend (>=), auf die Millisekunde genau.
2. Blättern Sie über den Cursor, bis pagination.nextCursor gleich null ist.
3. Entdoppeln Sie über die id - >= allein schützt nicht vor einem Datensatz, dessen Transaktion nach Ihrem Lesen bestätigt wurde (daher das überlappende Fenster).
4. Merken Sie sich das höchste updatedAt der Seite als Startpunkt des nächsten Durchlaufs.
5. Führen Sie nach einer Wiederherstellung des Kontos aus einer Sicherung einen vollständigen Neuabgleich durch - verlassen Sie sich nicht auf updatedSince (und legen Sie neue Schlüssel an).

Zapier und Make (ein Webhook in eine Aktion)

1. Legen Sie in Zapier den Auslöser Webhooks by Zapier - Catch Hook an (in Make: Custom Webhook) und kopieren Sie die erzeugte Adresse.
2. Fügen Sie in der Oberfläche (Konto - API - Webhooks) ein Abonnement hinzu: Ereignis wählen, Adresse als Ziel einfügen, das Geheimnis sichern (wird einmal gezeigt).
3. Klicken Sie in der Oberfläche auf Test senden, um den Empfang des Inhalts zu bestätigen.
4. Fügen Sie einen Schritt zur Signaturprüfung ein (siehe den Abschnitt Webhooks), bevor Sie den Daten vertrauen.
5. Nutzen Sie für Rückrufe an die Schnittstelle das Modul HTTP / Custom Request mit dem Kopfteil Authorization: Bearer.

Schlüssel und Webhook-Geheimnis wechseln (Fenster von 24 Std.)

• Schlüssel: ein Wechsel in der Oberfläche gibt einmalig ein neues Token aus; das alte gilt noch 24 Std. (ohne Ausfall) - tauschen Sie es in diesem Fenster in Ihrer Anbindung. Ein Widerruf wirkt sofort.
• Webhook-Geheimnis: der Wechsel hat ein Überlappungsfenster - altes und neues Geheimnis signieren 24 Std. parallel. Der Signatur-Kopfteil kann mehrere Paare v1= tragen, sodass der Wechsel keine brechende Änderung ist, wenn Sie jedes passende annehmen.
• Nach einer Wiederherstellung aus einer Sicherung werden die Schlüssel automatisch widerrufen - legen Sie neue an und gleichen Sie vollständig neu ab.

Mit Limits umgehen (Retry-After und wachsende Abstände)

• Lesen Sie das Tariflimit aus GET /me ( rateLimitPerMin) oder GET /usage. Limits gelten je Konto, nicht je Schlüssel.
• Jede Antwort trägt X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset - steuern Sie Ihr Tempo laufend.
• Beachten Sie bei 429 das Retry-After (Sekunden) und warten Sie exponentiell länger. Halten Sie die Gleichzeitigkeit unter dem Limit laufender Anfragen (20 parallele Anfragen je Konto).
• Bei Enterprise ist das Minutenlimit abgeschaltet; der Schutz gegen Fluten je IP-Adresse und die Obergrenze der Gleichzeitigkeit gelten immer (Schutz der Infrastruktur, keine Tarifeigenschaft).

Die Version steht im Pfad (/api/public/v1). Ergänzende Änderungen (neue Felder, neue Endpunkte, neue Ereignistypen) brechen die Verträglichkeit nicht - Ihr Client muss unbekannte Felder übergehen. Brechende Änderungen kündigen wir vorher an: ein Eintrag im Änderungsverlauf, eine E-Mail an die Inhaberschaft aktiver Schlüssel sowie die Kopfteile Deprecation und Sunset.

Der Versionsverlauf von v1 (die Versionsnummer ist die jeweils nächste Ausbaustufe). Alle Änderungen sind ergänzend - wir haben keinen Endpunkt und kein Feld entfernt und die Bedeutung keines davon geändert. Aktuelle Fassung der OpenAPI-Spezifikation: v1.10.0.

Die Versionierung steht im Pfad: eine brechende Änderung käme nach /v2, wobei v1 daneben mindestens 6 Monate ab der Ankündigung weiterläuft (ein Eintrag im Änderungsverlauf, eine E-Mail an die Inhaberschaft aktiver Schlüssel sowie die Kopfteile Deprecation und Sunset).

• Prüfen Sie die Verbindung mit GET /me, bevor Sie die erste Anbindung bauen.
• Fügen Sie Schreibvorgängen immer einen Idempotency-Key bei und wiederholen Sie vorübergehende Fehler mit wachsendem Abstand.
• Führen Sie nach einer Wiederherstellung des Kontos aus einer Sicherung einen vollständigen Neuabgleich durch (verlassen Sie sich nicht auf updatedSince) und legen Sie neue Schlüssel an - die alten werden dabei ungültig.
• Nutzen Sie für den abholenden Abgleich updatedSince mit überlappendem Fenster und entdoppeln Sie über die id.