Dokumentacja API i webhooków

Publiczne API NavyFlame to interfejs typu server-to-server. Każde wywołanie autoryzujesz kluczem API, a odpowiedzi mają stabilny, wersjonowany kształt. Bazowy adres jest w Twojej domenie tenanta:

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

Pełną, maszynową specyfikację (OpenAPI 3.1) pobierzesz pod adresem /openapi-public-v1.yaml i zaimportujesz do Postmana, Insomnii lub dowolnego klienta OpenAPI.

Zacznij od utworzenia klucza w panelu (Konto - API) i sprawdzenia połączenia zapytaniem GET /me - nie wymaga żadnego zakresu, wystarczy ważny klucz. Zwraca Twój plan, limity i zakresy klucza.

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

Przykładowa odpowiedź:

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

Klucz przekazujesz w nagłówku Authorization jako token Bearer (rekomendowane). Dla narzędzi bez wsparcia Bearer działa alias X-API-Key:

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

Klucze tworzysz, rotujesz i odwołujesz w panelu. Przechowujemy tylko skrót klucza (SHA-256) - pełną wartość zobaczysz raz przy utworzeniu. Klucz jest redagowany we wszystkich logach. Traktuj go jak hasło i nigdy nie umieszczaj po stronie przeglądarki.

Każdy klucz ma przypisane zakresy. Zakres :write obejmuje odpowiadający mu :read. Brak wymaganego zakresu zwraca 403 missing_scope.

Limity są agregowane per konto (nie per klucz). Nagłówki X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset na każdej odpowiedzi informują o stanie okna. Po przekroczeniu limitu otrzymasz 429 z nagłówkiem Retry-After.

Odczyt (paginacja kursorowa, filtry, sortowanie):

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

Zapis:

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)

Przykład - lista ostatnich zamówień:

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

Przykład - korekta stanu magazynowego o -3 sztuki (atomowo):

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}'

Read-only zasoby analityczne (zakresy reports:read, analytics:read, monitoring:read). Kwoty w raportach i analityce to liczby (agregaty), w odróżnieniu od zasobów transakcyjnych, gdzie kwoty są tekstem z dwoma miejscami po przecinku.

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

Eksporty /reports/export/csv i /xlsx to wyjątek binarny od formatu JSON - zwracają plik z nagłówkiem Content-Disposition: attachment (CSV w UTF-8 z BOM, separator średnik). Błędy nadal zwracamy jako application/problem+json.

Detale /monitoring/webhooks/{id} i /monitoring/dlq/{id} zawierają surowy payload konektora (dane osobowe kupującego) - zakres monitoring:read jest oznaczony jako wrażliwy. Listy tych zasobów payloadu nie zwracają.

Przykład - podsumowanie sprzedaży z ostatnich 30 dni:

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

Zasoby zawierające dane osobowe (zakresy customers:read, email:read, notifications:read, alerts:read, postsale:read). Tylko odczyt.

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

Klient to byt wirtualny (agregacja z zamówień), adresowany adresem e-mail. Powiadomienia są tenant-wide (klucz API nie reprezentuje jednego użytkownika); opcjonalny ?userId= zawęża do odbiorcy, a preferencje go wymagają. Obsługa posprzedażowa czyta wyłącznie dane zapisane w systemie (bez wywołań do marketplace na Twój koszt); dostępność sprawdzisz w /post-sale/capabilities.

Zakresy customers:read, email:read i postsale:read udostępniają dane osobowe - nadawaj je tylko zaufanym integracjom i przetwarzaj zgodnie z RODO.

Pełny zapis katalogu (zakresy catalog:read / catalog:write). Operacje tworzące i nieodwracalne wymagają nagłówka Idempotency-Key - ponowienie z tym samym kluczem odtwarza zapisany wynik zamiast wykonać operację raz jeszcze.

# 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}

Szablony opisów i produktów (zakresy templates:read / templates:write). Zastosowanie szablonu tworzy produkt, więc POST /product-templates/{id}/apply wymaga dodatkowo 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

Treści AI (zakresy ai:read / ai:write). Generowanie i tłumaczenie to operacje płatne u Twojego dostawcy AI (klucz konfigurujesz w integracjach), dlatego Idempotency-Key jest wymagany - ponowienie odtwarza wynik, nie nalicza go ponownie. Zapis wyniku do produktu (applyToProduct / createNewProducts) wymaga dodatkowo catalog:write. Operacje wsadowe zwracają skrócony podgląd na pozycję - pełny tekst pobierzesz z /ai/generation-logs lub z produktu.

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

Przykład - utworzenie szablonu opisu (idempotentnie):

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}}"}'

Konfiguracja wysyłki (zakresy shipping:read / shipping:write): reguły wysyłki, strefy ze stawkami, opcje dostawy i nadpisania per produkt, plus kalkulator kosztów. Operacje tworzące wymagają nagłówka Idempotency-Key. Kwoty i wagę w zapisie przekazujesz jako liczby (nie tekst). To konfiguracja, a nie obsługa kuriera - nadawanie przesyłek i etykiety pojawią się w osobnej fazie.

# 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

Nazwy nie są unikalne, więc nie ma konfliktu duplikatu (409). deliveryOptionId w stawce i nadpisaniu musi wskazywać Twoją opcję dostawy (inaczej 422), a stawka spoza Twojej strefy zwraca 404. Kalkulator zwraca listę opcji posortowaną rosnąco po koszcie.

Przykład - wyliczenie kosztów wysyłki do Polski:

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}'

Lifecycle przesyłek (zakres shipments:write) oraz odczyty pomocnicze kuriera (zakres shipments:read): tworzysz przesyłkę, zamawiasz etykietę u przewoźnika, anulujesz, odświeżasz tracking i przekazujesz numer śledzenia do Allegro. Wagę, wymiary i kwoty przekazujesz jako liczby.

# 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)

Zamówienie etykiety jest płatne - kupuje realną przesyłkę u przewoźnika. Dlatego POST /shipments/{id}/label wymaga nagłówka Idempotency-Key: ponowienie z tym samym kluczem odtwarza zapisany wynik i nigdy nie kupuje etykiety drugi raz (zabezpieczenie działa po stronie serwera). Etykietę zamówisz tylko dla przesyłki w statusie Szkic. Pobranie etykiety (GET .../label) to wyjątek binarny - zwraca application/pdf, a nie JSON.

Konektor kuriera lub Allegro, który nie jest połączony, zwraca 403 not_supported (nigdy 500), a błąd po stronie przewoźnika lub Allegro - 502 bad_gateway. Odczyty pomocnicze dla nieobsługiwanego dostawcy zwracają { "supported": false } zamiast błędu. Anulowanie nie zmienia statusu lokalnego, jeśli przewoźnik odrzuci operację.

Przykład - zamówienie etykiety (idempotentnie, płatne):

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"

Odkrywanie konektorów (zakres integrations:read) oraz odczyty i zapisy ofert marketplace (zakresy offers:read / offers:write). Część operacji jest lokalna (z Twoich danych, bez kosztów), a część to żywe, płatne wywołania do konektora - oznaczone niżej.

Odkrywanie i lokalne odczyty (bez kosztów):

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 zwraca ściśle ograniczony zestaw pól - key, configId, displayName, enabled i connected - i nigdy nie zwraca danych logowania (kluczy API, tokenów ani haseł konektora). Pole connected to wyliczony status: konektor jest włączony i ma zapisane poświadczenia. Wartość configId przekażesz jako filtr ?sourceConfigId= lub ?destConfigId= w mapowaniach kategorii.

Oferty produktu (/warehouse-items/{id}/listings) wiążą pozycję magazynową z ofertą w kanale (zewnętrzne ID, cena i status po stronie marketplace, ewentualne nadpisanie ceny per kanał). Każdy obiekt oferty zawiera instanceId, czyli trwałe ID konkretnego połączenia, oraz instanceName do wyświetlenia użytkownikowi. Dzięki temu ten sam produkt może mieć niezależne oferty, ceny i stan synchronizacji na przykład na ebay.de i ebay.com. Pole lastSyncError jest oczyszczane z wzorców poświadczeń, które błąd konektora mógłby zawierać.

Przykład - lista konektorów konta:

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

Żywe odczyty marketplace (zakres offers:read) wykonują realne wywołanie do konektora - są płatne (liczą się do limitu API konektora), ale wyłącznie do odczytu (nie publikują ani nie zmieniają oferty). Konektor niepołączony zwraca 403 not_supported (nigdy 500), błąd po stronie marketplace - 502 bad_gateway. Kształt danych zależy od konektora.

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

Zapis mapowań kategorii (zakres offers:write) to zapisy lokalne - żadne z nich nie publikuje ani nie zmienia realnej oferty widocznej dla kupującego (publikację realnej oferty opisano niżej). POST /category-mappings wymaga nagłówka Idempotency-Key (duplikat -> 409); sync odświeża lokalny cache kategorii z konektora (płatne, ale idempotentne).

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)

Publikacja i synchronizacja realnych ofert (zakres offers:write) tworzy lub aktualizuje ofertę widoczną dla kupującego w kanale - operacje płatne (realne wywołanie do marketplace). publish i sync wymagają nagłówka Idempotency-Key (retry z tym samym kluczem odtwarza zapisaną odpowiedź zamiast ponawiać płatne wywołanie). publish zwraca 409, gdy produkt jest już opublikowany na tym konkretnym połączeniu (lub jego publikacja jest w toku) - oferta na innej instancji tego samego konektora nie powoduje konfliktu. Wtedy użyj sync dla tego samego configId. Konektor niepołączony -> 403 not_supported, błąd po stronie marketplace -> 502 bad_gateway.

W body operacji publish, sync i PUT .../pricing przekaż configId otrzymane z GET /connectors. Jeśli konektor ma kilka włączonych połączeń, pominięcie pola kończy się 422 validation_failed. API nie wybiera konta domyślnego w ciemno. Gdy istnieje dokładnie jedno włączone połączenie, może je rozstrzygnąć automatycznie.

Ważne przy błędzie 502 na publikacji: timeout lub błąd 5xx marketplace jest niejednoznaczny - oferta mogła powstać. Retry z tym samym Idempotency-Key odtworzy to samo 502 (nie opublikuje ponownie). Zweryfikuj ofertę w kanale i ponów z nowym Idempotency-Key dopiero wtedy, gdy wiesz, że oferta nie powstała.

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 }

Import oferty do magazynu ( POST /catalog/import) tworzy pozycję magazynową z produktu marketplace. Wymaga dwóch zakresów naraz - offers:write oraz catalog:write (brak jednego -> 403 missing_scope) - i nagłówka Idempotency-Key. Duplikat SKU lub kodu kreskowego -> 409 conflict.

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

Zapis komunikacji, ponownego przetwarzania i obsługi posprzedażowej (zakresy notifications:write, alerts:write, email:write, monitoring:write, postsale:write i postsale:refunds:write). Operacje tworzące i nieodwracalne wymagają nagłówka Idempotency-Key; operacje naturalnie idempotentne (oznaczanie jako przeczytane, toggle) honorują go opcjonalnie.

# 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)

Tworzenie powiadomienia sprawdza, czy recipientUserId jest członkiem konta (nie-członek -> 422, niepewna weryfikacja -> 503) - klucz API nie może zasypać skrzynki dowolnego użytkownika. Szablony e-mail podlegają limitowi planu (Basic 10, Professional 24, Enterprise bez limitu) -> 403 plan_limit, a duplikat nazwy -> 409. Wysyłka e-mail (`POST /emails/send`) jest płatna i objęta dedykowanym limitem ~10 na godzinę per konto ( 429); dostawca bez konfiguracji -> 403 not_supported, błąd transportu -> 502 bad_gateway. Reguła alertu z kanałem email lub both pośrednio generuje wysyłki przy wyzwoleniu.

Ponowne przetwarzanie kolejki błędów (zakres monitoring:write) odpala oryginalny proces wpisu DLQ - dla źródeł fakturowania wystawia realną fakturę, więc jest płatne i destrukcyjne, a Idempotency-Key jest wymagany. Retriable są tylko trzy źródła (shopify_to_wfirma_pipeline, shopify, wfirma_invoice) - inne zwracają 422; niedostępny Temporal -> 503. Powtórzenie jest idempotentne po deterministycznym identyfikatorze procesu (zwraca alreadyRunning).

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

Obsługa posprzedażowa (zakres postsale:write): odpowiadasz w wątkach i sporach, zmieniasz status sporu, akceptujesz lub odrzucasz zwrot. Własność wątku, sporu lub zwrotu jest sprawdzana przed wywołaniem kanału (cudzy lub nieistniejący identyfikator -> 404), a operacje są capability-gated per konektor - brak danej zdolności lub metody zwraca 403 not_supported (nigdy 500). Błąd kanału -> 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

Izolacja pieniędzy. Zwrot środków ma odrębny zakres `postsale:refunds:write`, wydzielony od postsale:write, tak aby wyciekły klucz bez tego zakresu nie mógł ruszyć pieniędzy. Trasa POST /post-sale/disputes/{id}/status należy do postsale:write, ale jeśli decyzja przenosi środki do kupującego (obecne partialRefund albo status ACCEPTED_REFUND / ACCEPTED_PARTIAL_REFUND), klucz musi dodatkowo nieść `postsale:refunds:write` - inaczej żądanie zwraca 403 missing_scope i nic się nie wykonuje.

Ponawianie zwrotów. refunds/issue i commission-claim są idempotentne po stronie kanału (Twój Idempotency-Key staje się identyfikatorem operacji na kanale) - na 502 ponów z tym samym kluczem, a kanał zdeduplikuje. Natomiast decyzja sporu przenosząca środki nie ma idempotencji po stronie kanału - na niepewny błąd zweryfikuj wynik w kanale sprzedaży i ponów dopiero z nowym Idempotency-Key (to samo 502 jest zwracane dla tego samego klucza).

Przykład - realny zwrot środków (idempotentnie, płatne):

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"}'

Kompletny, nawigowalny indeks wszystkich publicznych endpointów v1 pogrupowanych per zasób. To jest warstwa dla człowieka - pełne, polowe schematy żądań i odpowiedzi (179 schematów) znajdziesz w specyfikacji OpenAPI . Każdy żyjący endpoint jest tu wymieniony.

• Zakres - wymagany zakres klucza. Zakres :write obejmuje odpowiadający mu :read. Zapis a + b oznacza cross-scope (potrzebne oba naraz).
• Idem. - K! = nagłówek Idempotency-Key wymagany; K? = honorowany (opcjonalny); puste = nie dotyczy (odczyt).
• Błędy - kluczowe kody poza uniwersalnymi 401, 403, 429 (oraz 500/503, które mogą wystąpić wszędzie).

Listy stronicujemy kursorowo (bez offsetu). Odpowiedź niesie pagination.nextCursor - przekaż go w parametrze cursor, aby pobrać kolejną stronę. Parametr updatedSince (data-czas ISO ze strefą) zwraca rekordy zmienione od danej chwili. Dla pull-synchronizacji odpytuj z oknem nakładki i deduplikuj po id.

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

Operacje zapisu chroni nagłówek Idempotency-Key (dowolny unikat, rekomendowany UUID, do 255 znaków). Jest wymagany na POST /orders i POST /orders/{id}/invoice, a honorowany na PUT i PATCH.

• Powtórka z tym samym kluczem i tą samą treścią zwraca zapisany wynik (nagłówek Idempotency-Replayed: true) - bez podwójnego efektu.
• Ten sam klucz z inną treścią zwraca 409 idempotency_conflict.
• Równoległy duplikat w trakcie przetwarzania zwraca 409 idempotency_in_progress z Retry-After.
• Klucze wygasają po 24 godzinach.

Gotowe fragmenty w trzech wariantach: curl, JavaScript (fetch, Node 20+) i Python (biblioteka requests). Warianty JS i Python zakładają stałe BASE (adres bazowy) i KEY (klucz z bezpiecznego magazynu), ustawione w przykładzie uwierzytelniania.

Uwierzytelnianie (Bearer i 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"])

Paginacja kursorowa (pętla + deduplikacja)

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

Idempotentny zapis (Idempotency-Key + backoff)

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")

Weryfikację podpisu webhooka (JavaScript i Python) znajdziesz w sekcji Webhooki wychodzące .

Błędy zwracamy zgodnie z RFC 9457 (application/problem+json). Każdy niesie stabilny code i requestId do korelacji ze wsparciem.

{
  "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)." }]
}

Kody 500 (internal) i 503 (service_unavailable) mogą wystąpić na każdej operacji i nie są deklarowane per endpoint. Wdrożenia są ciągłe - klient powinien traktować sporadyczne 502/503 jako przejściowe (ponowienie z backoffem), a operacje zapisu zabezpieczać nagłówkiem Idempotency-Key. Nagłówek type w problem+json wskazuje na kotwicę tej sekcji (np. #validation_failed).

Subskrybujesz zdarzenie i podajesz adres HTTPS, a my wysyłamy tam podpisane powiadomienie. Zdarzenia v1: order.synced, order.status_changed, invoice.issued, shipment.status_updated, catalog.updated. Każda dostawa niesie nagłówki X-NavyFlame-Event, X-NavyFlame-Delivery-Id i X-NavyFlame-Signature. Sukces to odpowiedź 2xx w ciągu 5 sekund; przy niepowodzeniu ponawiamy z rosnącym odstępem przez ok. 24 godziny, a historię dostaw widzisz w panelu.

Kształt ładunku (wspólna koperta):

{
  "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 }
}

Pole origin.channel (api | panel | sync | automation) pozwala przerwać pętlę echa - jeśli sam wywołałeś zmianę kluczem API, rozpoznasz to po apiKeyPrefix i pominiesz zdarzenie. Odbiorca deduplikuje po id zdarzenia oraz nagłówku X-NavyFlame-Delivery-Id (gwarancja at-least-once, bez gwarancji kolejności).

Katalog zdarzeń (v1)

Zamknięta lista zdarzeń v1 - nowe typy to zmiana addytywna, więc odbiornik musi ignorować nieznane pola i typy. Każde zdarzenie niesie wspólną kopertę (powyżej); treść specyficzna dla typu jest w polu 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 }

Weryfikacja podpisu

Nagłówek X-NavyFlame-Signature ma postać t=<unix>,v1=<hex>, gdzie v1 = HMAC-SHA256(sekret, "<t>." + surowe_body). Nagłówek może zawierać kilka par v1= (okno rotacji sekretu - stary i nowy sekret podpisują równolegle przez 24 h) - zaakceptuj dowolną pasującą. Sprawdzaj zgodność znacznika czasu (tolerancja 300 s), aby chronić się przed powtórką.

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)

Weryfikuj podpis na surowym ciele żądania (bajty przed parsowaniem JSON) - ponowne serializowanie zmieni bajty i podpis się nie zgodzi. raw_body / rawBody to dokładne bajty odebrane w ciele POST, przed dekodowaniem JSON.

Recepta na Zapier i Make

1. W Zapier utwórz Zap z triggerem Webhooks by Zapier - Catch Hook (w Make: moduł Custom Webhook). Skopiuj wygenerowany adres.
2. W panelu NavyFlame (Konto - API - Webhooki) dodaj subskrypcję: wybierz zdarzenie i wklej adres jako cel. Sekret podpisu zobaczysz raz - zapisz go.
3. Użyj przycisku Wyślij test w panelu, aby potwierdzić, że scenariusz odbiera ładunek.
4. (Zalecane) Dodaj krok weryfikacji podpisu powyższą funkcją, zanim zaufasz danym.

RODO

Ładunki webhooków niosą dane osobowe kupujących. Konfigurując subskrypcję (wybór adresu docelowego, np. Zapier - zwykle transfer poza EOG) występujesz jako administrator tych danych, a subskrypcja jest Twoim udokumentowanym poleceniem przetwarzania. Propagacja usunięcia lub anonimizacji danych kupującego do systemów zasilonych przez API i webhooki jest po Twojej stronie.

Szybki start (od klucza do pierwszego wywołania)

1. W panelu (Konto - API) utwórz klucz z potrzebnymi zakresami. Klucz zobaczysz tylko raz - zapisz go w bezpiecznym magazynie sekretów.
2. Potwierdź połączenie: GET /me (nie wymaga zakresu). Zwraca plan, limity i zakresy klucza.
3. Wykonaj pierwsze wywołanie w docelowym zasobie, np. GET /orders?limit=25.

Pull-synchronizacja (updatedSince + okno nakładki + dedupe)

1. Odpytuj z updatedSince = ostatni_sync - okno_nakładki (np. 5 minut). Semantyka jest inclusive (>=), precyzja milisekundowa.
2. Paginuj kursorowo aż pagination.nextCursor będzie null.
3. Deduplikuj po id - samo >= nie chroni przed rekordem, którego transakcja commitowała po Twoim odczycie (stąd okno nakładki).
4. Zapisz najwyższy updatedAt ze strony jako punkt startu następnego przebiegu.
5. Po przywróceniu konta z kopii zapasowej wykonaj pełny resync - nie polegaj na updatedSince (i utwórz nowe klucze).

Zapier i Make (webhook do akcji)

1. W Zapier utwórz trigger Webhooks by Zapier - Catch Hook (w Make: Custom Webhook) i skopiuj wygenerowany adres.
2. W panelu (Konto - API - Webhooki) dodaj subskrypcję: wybierz zdarzenie, wklej adres jako cel, zapisz sekret (pokazany raz).
3. Kliknij Wyślij test w panelu, aby potwierdzić odbiór ładunku.
4. Dodaj krok weryfikacji podpisu (patrz sekcja Webhooki), zanim zaufasz danym.
5. Do wywołań zwrotnych do API użyj modułu HTTP / Custom Request z nagłówkiem Authorization: Bearer.

Rotacja klucza i sekretu webhooka (okno 24 h)

• Klucz API: rotacja w panelu zwraca nowy token raz; stary działa jeszcze 24 h (zero-downtime) - podmień go w integracji w tym oknie. Odwołanie (revoke) jest skuteczne natychmiast.
• Sekret webhooka: rotacja ma okno overlap - stary i nowy sekret podpisują równolegle przez 24 h. Nagłówek podpisu może nieść wiele par v1=, więc akceptowanie dowolnej pasującej sprawia, że rotacja nie jest zmianą łamiącą.
• Po restore z backupu klucze API są automatycznie odwoływane - utwórz nowe i wykonaj pełny resync.

Obsługa limitów (Retry-After + backoff)

• Odczytaj limit planu z GET /me ( rateLimitPerMin) lub GET /usage. Limity są agregowane per konto, nie per klucz.
• Każda odpowiedź niesie X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset - steruj tempem na bieżąco.
• Na 429 uszanuj Retry-After (sekundy) i zastosuj wykładniczy backoff. Trzymaj współbieżność poniżej limitu in-flight (20 równoległych żądań per konto).
• Enterprise ma limit per-minuta wyłączony; per-IP flood guard i cap współbieżności działają zawsze (ochrona infrastruktury, nie plan).

Wersja jest w ścieżce (/api/public/v1). Zmiany addytywne (nowe pola, nowe endpointy, nowe typy zdarzeń) nie łamią zgodności - Twój klient musi ignorować nieznane pola. Zmiany łamiące zapowiadamy z wyprzedzeniem: wpis w changelogu, e-mail do właścicieli aktywnych kluczy oraz nagłówki Deprecation i Sunset.

Historia wersji v1 (numer wersji = kolejna faza rozbudowy). Wszystkie zmiany są addytywne - nie usunęliśmy ani nie zmieniliśmy znaczenia żadnego endpointu ani pola. Aktualna wersja specyfikacji OpenAPI: v1.10.0.

Wersjonowanie jest w ścieżce: zmiana łamiąca trafiłaby do /v2 z równoległym wsparciem v1 przez min. 6 miesięcy od ogłoszenia (wpis w changelogu, e-mail do właścicieli aktywnych kluczy oraz nagłówki Deprecation i Sunset).

• Testuj połączenie na GET /me przed pierwszą integracją.
• Zawsze dołączaj Idempotency-Key do operacji zapisu i ponawiaj przejściowe błędy z backoffem.
• Po przywróceniu konta z kopii zapasowej wykonaj pełną resynchronizację (nie polegaj na updatedSince) i utwórz nowe klucze - stare są po restore unieważniane.
• Do pull-synchronizacji używaj updatedSince z oknem nakładki i deduplikuj po id.