Dokumentacja Dashbord.pl

Jak korzystać z dokumentacji

• Każdy ekran opisany jest osobno — znajdziesz tam co robi, co pokazuje i z jakich systemów OMS pobiera dane.
• Kolorowe etykiety OMS (Apilo, BaseLinker, Sellasist, Sellrocket, Thulium) informują które połączenia są wymagane aby dany ekran miał dane.
• Użyj wyszukiwarki w lewym menu lub przewijaj treść kolejno.
• Tabela kompatybilności na początku daje szybki przegląd wszystkich ekranów.

• Zamówienia i pozycje zamówień
• Płatności (embedded w zamówieniu)
• Dane wysyłki i numer przesyłki (embedded w zamówieniu)
• Zwroty i reklamacje
• Katalog produktów (agregowany z historii zamówień)
• Dokumenty finansowe

• Zamówienia, pozycje, płatności, wysyłki, etykiety
• Zwroty i reklamacje
• Katalog produktów (z historii zamówień)
• Słowniki statusów zamówień

• Zamówienia, pozycje, płatności, wysyłki, etykiety
• Zwroty i reklamacje
• Logi pakowania (kto, kiedy, co spakował)
• Dane pracowników i ich aktywność
• Słowniki statusów zamówień

• Zamówienia, pozycje, płatności, wysyłki, etykiety
• Zwroty i reklamacje
• Słowniki statusów zamówień

• Zamówienia i pozycje zamówień
• Katalog produktów z cenami i stanami magazynowymi
• Dane klientów (e-mail, adres dostawy)

• Zamówienia i pozycje zamówień
• Katalog produktów ze stanami magazynowymi
• Dane klientów (e-mail, adres dostawy)

• Historia rozmów telefonicznych i ich oceny
• System ticketów (zgłoszenia klientów)
• Agenci i kolejki telefoniczne
• Snapshoty kolejek (Live Wallboard)
• Obsługa webhooków w czasie rzeczywistym

Pierwsza strona po zalogowaniu. Daje natychmiastowy przegląd sytuacji sprzedażowej — bez klikania, bez raportów. Widzisz najważniejsze liczby za wybrany okres.

Co pokazuje

• 8 KPI: Zamówienia, Przychód całkowity, Średnia wartość zamówienia (AOV), Opłacone %, Zaległości, Wysłane %, Backlog (nieopłacone), Świeżość syncu
• Granice zamówień — data pierwszego i ostatniego zamówienia w systemie
• Podział przychodów per waluta gdy konto obsługuje wiele walut
• Filtry okresu: 7 / 30 / 60 / 90 dni oraz "Wszystkie"
• Filtr konta OMS — możliwość oglądania danych jednego źródła

Centralne miejsce do przeglądania wszystkich zamówień ze wszystkich podłączonych sklepów w jednej tabeli. Kliknij zamówienie żeby zobaczyć szczegóły — produkty, adres, płatność, wysyłkę.

Co pokazuje

• Lista zamówień: numer, data, klient, kwota brutto, waluta, status płatności, konto OMS
• Sortowanie każdej kolumny kliknięciem nagłówka (▲/▼)
• Wyszukiwarka (nr zamówienia, dane klienta)
• Filtr "Z komentarzem" — tylko zamówienia z notami/komentarzami
• Paginacja z selektorem liczby rekordów na stronę
• Eksport do pliku XLS

Panel szczegółu zamówienia

• Dane klienta i adres dostawy
• Lista pozycji zamówienia (nazwa, SKU, ilość, cena)
• Status płatności i metoda płatności
• Dane wysyłki i list przewozowy
• Noty i komentarze do zamówienia

Historia zwrotów i reklamacji z wszystkich podłączonych sklepów. Sprawdź które produkty są najczęściej zwracane i jakie kwoty są w grze.

Co pokazuje

• Typ zdarzenia: Zwrot / Reklamacja
• Data, konto OMS, kwota
• Panel boczny: szczegóły zwrotu + produkty z powiązanego zamówienia
• Ranking: produkt, SKU, liczba zwrotów, łączna ilość szt., wartość zwrotów
• Filtry: typ, zakres dat, konto OMS
• Eksport XLS (osobno dla każdego taba)

Baza Twoich klientów zbudowana automatycznie na podstawie zamówień. Sprawdź kto kupuje najczęściej, ile wydał łącznie i kiedy był ostatni raz aktywny.

Co pokazuje

• Lista unikalnych klientów (unikalność wg adresu email)
• Per klient: liczba zamówień, przychód brutto, data pierwszego i ostatniego zamówienia, okres aktywności
• Sortowanie: po przychodzie, liczbie zamówień, pierwszym lub ostatnim zamówieniu
• Wyszukiwarka z debounce po emailu, nazwie i nazwie firmy
• Paginacja (50 rekordów / stronę)

Panel boczny klienta

• KPI: łączne zamówienia, przychód, daty
• Historia ostatnich 50 zamówień: numer, data, kwota, status

Szybki podgląd które zamówienia zostały opłacone, a które czekają na płatność. Pomocne przy codziennej kontroli zaległości i weryfikacji przelewów.

Co pokazuje

• Lista zamówień z ich statusem płatności
• Kolumny: numer, data zamówienia, klient, kwota brutto, waluta, status płatności, konto OMS
• Sortowanie kolumn, wyszukiwarka, paginacja, eksport XLS
• Filtr statusu płatności: Opłacone / Nieopłacone / Częściowo

Analiza sprzedaży produktów — co się sprzedaje, co zalega na magazynie, które produkty rosną a które tracą popularność.

Katalog produktów

• Nazwa, SKU, EAN, VAT, łączna ilość, liczba zamówień, przychód brutto
• Ceny: średnia / min / max brutto, data pierwszego i ostatniego zamówienia
• Wyszukiwarka (nazwa, SKU, EAN) z debounce 400ms
• Kliknięcie produktu → panel kanałów sprzedaży (Allegro, Sklep, Castorama itd.)
• Sortowanie każdej kolumny, paginacja server-side (50/stronę), eksport XLS

Nie sprzedane

• Produkty bez żadnego zamówienia przez wybrany okres: 7, 30 lub 60 dni
• Badge z liczbą dni bez sprzedaży, data ostatniego zamówienia
• Wyszukiwarka, sortowanie, paginacja, eksport XLS

Ranking

• Top 20 produktów wg: Przychód brutto / Ilość (szt.) / Liczba zamówień
• Selektor okresu: 30 dni / 90 dni / 12 miesięcy / Wszystkie
• Pasek postępu z % udziałem każdego produktu

Katalog produktów zsynchronizowanych bezpośrednio z systemu magazynowego lub OMS — z aktualnymi stanami i cenami. Różni się od ekranu Produkty tym, że dane tu pochodzą z katalogu systemu, nie z historii zamówień.

Co pokazuje

• Lista produktów z nazwą, SKU, EAN, ceną netto i brutto
• Stany magazynowe per produkt i wariant
• Warianty produktu (rozmiary, kolory) rozwijane w tabeli
• Status aktywności produktu w systemie OMS
• Wyszukiwarka po nazwie, SKU, EAN — sortowanie kolumn

Panel magazyniera. Widać co jest do spakowania teraz, kto spakował ile paczek i jak szybko idzie realizacja zamówień.

Kolejka pakowania

• Liczniki: DO ZROBIENIA / ZROBIONE DZIŚ / RAZEM z paskiem postępu
• Tabela: nr zamówienia, godzina, klient, liczba szt., list przewozowy, konto OMS
• Przycisk "Spakowałem" przy każdym zamówieniu
• Automatyczne odświeżanie co 30 sekund
• Paginacja, sortowanie kolumn, eksport XLS

Raport pakowania, Wyniki pracowników, Produkty wg pracownika

• Szczegółowe raporty z danymi spakowanych paczek per pracownik i per dzień
• Filtr zakresu dat, filtr kuriera
• Eksport CSV i XLS

Lista wszystkich wygenerowanych etykiet i listów przewozowych. Sprawdź numer przesyłki dla konkretnego zamówienia lub zweryfikuj które wysyłki są już w transporcie.

Co pokazuje

• Lista wysyłek z numerami listów przewozowych
• Kolumny: numer zamówienia, data, kurier, numer przesyłki, status, konto OMS
• Wyszukiwarka po numerze zamówienia i numerze przesyłki
• Sortowanie kolumn, paginacja, eksport XLS

Podgląd słowników statusów zamówień pobranych z systemów OMS. Przydatne gdy chcesz zobaczyć jakie statusy istnieją w Twoim panelu Sellasist, BaseLinker lub Sellrocket.

Co pokazuje

• Pobrane z OMS słowniki statusów zamówień (np. "Nowe", "W realizacji", "Wysłane")
• Zakładki wg rodzaju słownika
• Wyszukiwarka, sortowanie kolumn, grupowanie po koncie OMS
• Eksport XLS

Statystyki pakowania dla każdego pracownika magazynu. Kto ile paczek spakował, w jakim czasie i w które dni tygodnia — dane prosto z Sellasist.

Co pokazuje

• Ranking pracowników wg liczby spakowanych zamówień
• Kolumny: awatar, pracownik, spakowanych zamówień, wartość spakowanych, pierwsza i ostatnia aktywność
• Kliknięcie pracownika → panel boczny z wykresem aktywności dziennej
• Filtr zakresu dat, eksport XLS

Dziennik wszystkich ważnych działań wykonanych w systemie — kto dodał użytkownika, kto usunął połączenie, kiedy był ostatni sync. Przeznaczony dla właściciela konta i administratora.

Co pokazuje

• Chronologiczny dziennik ważnych zdarzeń: dodanie użytkownika, usunięcie użytkownika, usunięcie połączenia OMS
• Per zdarzenie: data, typ akcji (kolorowy badge), użytkownik wykonujący, cel akcji, szczegóły
• Kolorowanie: czerwony = usunięcie, zielony = dodanie, pomarańczowy = synchronizacja
• Filtr po typie akcji, wyszukiwarka lokalna
• Paginacja (50 rekordów / stronę)

Rozszerzona wersja Dashboardu — skupia się na wskaźnikach jakościowych, nie tylko ilościowych. Każdy KPI porównywany jest automatycznie z poprzednim takim samym okresem i wyświetlany ze strzałką trendu.

Co pokazuje

• AOV (średnia wartość koszyka) — z trendem względem poprzedniego okresu
• LTV (wartość życiowa klienta) — średni przychód na klienta w danym oknie
• Skuteczność płatności — % zamówień opłaconych w czasie
• Nowi vs powracający klienci — ile osób kupuje po raz pierwszy, ile wraca
• Średni przychód dzienny i średnia liczba zamówień na dzień
• Źródła zamówień z % udziałem przychodów
• Kliknięcie KPI → drill-down z tabelą zamówień składających się na tę wartość

Pogłębiona analiza biznesowa — więcej wskaźników niż na Dashboardzie. Kliknij dowolną metrykę żeby zobaczyć listę zamówień które się na nią składają.

Co pokazuje

• Sekcja Zamówienia (30 dni): AOV, LTV, skuteczność płatności
• Sekcja Klienci: nowi vs powracający, częstotliwość zakupów
• Sekcja Płatności: opłacone / nieopłacone per waluta
• Sekcja Wysyłki: % wysłanych, backlog
• Sekcja Pakowanie: wydajność linii pakowania
• Sekcja Źródła zamówień: ranking kanałów sprzedaży z % udziałem i przychodem
• Kliknięcie KPI otwiera drill-down z tabelą szczegółową
• Eksport XLS tabeli kanałów

Miesięczna tabela przychodów i kosztów. Część danych pochodzi automatycznie z zamówień, część wpisujesz ręcznie (koszty zakupu, prowizje, wysyłka). Na końcu widzisz szacowaną marżę netto.

Co pokazuje — wiersze automatyczne (z OMS)

• Sprzedaż brutto (GMV) — suma wszystkich zamówień per miesiąc
• Anulowane & zwrócone brutto
• GMV bez anulowanych (GMV netto)
• Szacunkowy VAT (23/123)
• Sprzedaż netto

Wiersze edytowalne (wprowadzane ręcznie)

• Koszty zakupu towarów
• Prowizje marketplace
• Koszty wysyłki
• Szacowane: marketing, wynagrodzenia, koszty operacyjne, pozostałe
• Kliknięcie komórki → edycja inline, zapis na Enter lub kliknięcie poza komórkę

Wiersze obliczane

• Marża na sprzedaży (GMV netto − koszty zakupu)
• Szacowana marża brutto (po odjęciu prowizji i wysyłki)
• Szacowana marża netto (po wszystkich kosztach)

Inne funkcje

• Selektor okresu: 3 / 6 / 12 / 24 miesiące
• Filtr konta OMS
• Sticky lewa kolumna, przewijalne kolumny miesięczne
• Eksport XLS (wszystkie miesiące, jeden arkusz)

Rozkład przychodów wg kanału sprzedaży — ile procent pochodzi z Allegro, ile ze sklepu własnego, ile z Castoramai itd. Wykres kołowy i tabela z wartościami.

Co pokazuje

• Wykres donut z % udziałem przychodów per kanał sprzedaży (Allegro, Sklep, Castorama itd.)
• Tabela z sortowaniem: kanał, zamówienia, przychód brutto, udział %
• Wiersz "Razem" na dole tabeli
• Selektor okresu: 3 / 6 / 12 / 24 miesiące + własny zakres dat
• Eksport XLS

Wykresy słupkowe pokazujące jak sprzedaż zmieniała się miesiąc po miesiącu — i czy ten rok jest lepszy od poprzedniego.

Co pokazuje

• Stacked bar chart: sprzedaż miesięczna per kanał lub per konto OMS
• Przełącznik: Liczba zamówień / Wartość zamówień
• Przełącznik: Wg kanału sprzedaży / Wg konta OMS
• Selektor okresu: 3 / 6 / 12 / 24 miesiące + własny zakres dat
• Tryb "vs Poprzedni rok" — grouped bar chart bieżący vs poprzedni rok
• Klikalna legenda — odklikaj kanały których nie chcesz widzieć
• Tabela zestawień pod wykresem z % udziałami
• Eksport XLS

Galeria wykresów analitycznych pogrupowanych tematycznie. Każdy wykres można filtrować po koncie OMS i zakresie dat. Przydatne do odkrywania wzorców — kiedy kupują klienci, który kurier dominuje, jak wygląda sezonowość.

Grupy wykresów

Połączenia

• Dodawanie i zarządzanie kontami Thulium
• Test połączenia, force sync, status webhooków
• Logi synchronizacji danych

Przegląd

• KPI: liczba rozmów, ticketów, czas obsługi, oceny
• Trend rozmów i ticketów per dzień
• Top kolejki i top agenci

Live Wallboard

• Polling co 30 sekund: aktywne rozmowy, stan kolejek
• Eventy w czasie rzeczywistym, alerty SLA

Rozmowy

• Lista rozmów z filtrami: data, agent, kolejka, ocena
• Panel boczny ze szczegółami, RAW data

Zgłoszenia (tickety)

• Lista ticketów z filtrami, historia komentarzy
• Wskaźniki SLA, oceny klientów

Klient 360

• Wyszukaj klienta po numerze telefonu lub ID
• Pełna historia rozmów i ticketów tego klienta

Tu podłączasz swoje sklepy i systemy OMS do Dashbord. Bez tego ekranu nie ma danych. Tutaj też widzisz kiedy ostatnio odbył się synchronizacja i czy są jakieś błędy połączenia.

Co umożliwia

• Dodawanie nowych połączeń OMS (Apilo, BaseLinker, Sellasist, Sellrocket, Thulium)
• Podgląd statusu synchronizacji każdego połączenia (aktywne / błąd / nieaktywne)
• Ręczne wznowienie synchronizacji (przycisk "Wznów pobieranie danych")
• Usuwanie nieaktywnych połączeń
• Filtr konta OMS widoczny na innych ekranach odpowiada podłączonym tu kontom

Jeżeli sprzedajesz przez własny sklep (PrestaShop, Shopify), a zamówienia trafiają też przez OMS (Sellasist, BaseLinker) — to samo zamówienie może wchodzić do Dashbord dwukrotnie. Mapowanie kanałów mówi systemowi: "te zamówienia z OMS to te same co z połączenia PrestaShop" — i eliminuje podwójne liczenie.

Problem bez mapowania

OMS pobiera zamówienia ze wszystkich kanałów sprzedaży — Allegro, własny sklep, marketplace'y. Dashbord może mieć jednocześnie bezpośrednie połączenie z tym samym sklepem PrestaShop lub Shopify. Bez mapowania to samo zamówienie pojawi się w statystykach dwa razy.

Jak działa dopasowanie

Każde zamówienie synchronizowane z OMS ma dwa pola identyfikujące jego źródło:

Mapowanie łączy konkretny kanał OMS z połączeniem bezpośrednim. Dashbord przy liczeniu statystyk automatycznie wyklucza zamówienia OMS dla zmapowanych kanałów — zostają tylko te z połączenia bezpośredniego.

Jak skonfigurować

1. Przejdź do Mapowanie kanałów
2. Wybierz połączenie OMS (np. Sellasist) i konkretny kanał (np. PrestaShop - sklep) lub całe połączenie dla `*`
3. Wybierz odpowiadające mu połączenie bezpośrednie (np. Twój PrestaShop)
4. Zapisz — od tej chwili zamówienia z tego kanału OMS nie są liczone podwójnie

Co umożliwia

• Przypisanie kanału OMS (np. "PrestaShop - sklep") do konkretnego połączenia bezpośredniego
• Wykluczenie duplikatów z sum i wykresów (zamówienie liczone raz, nie dwa razy)
• Lista istniejących mapowań z możliwością usunięcia

Apilo i Allegro — pole externalId

Apilo zapisuje w polu Order.externalId wartość idExternal z API Apilo, która dla zamówień Allegro jest równoznaczna z checkoutFormId Allegro. To pole jest kluczem łączącym zamówienie OMS z danymi rozliczeniowymi Allegro (prowizje, billing entries).

Zarządzanie osobami mającymi dostęp do Twojego konta Dashbord. Dodaj współpracownika, zmień mu hasło lub usuń dostęp gdy odejdzie z firmy.

Co umożliwia

• Lista użytkowników z rolami (OWNER, ADMIN, MEMBER) i statusem 2FA
• Dodawanie nowych użytkowników — system automatycznie generuje hasło i wysyła e-mail powitalny
• Resetowanie hasła użytkownika — nowe hasło wysyłane na e-mail
• Usuwanie użytkownika z konta (OWNER nie może usunąć siebie)
• Eksport listy użytkowników XLS

Konfiguracja własnego SMTP do wysyłki e-maili, włączanie 2FA, a także zarządzanie kluczami API dla zewnętrznych systemów ERP.

Konfiguracja SMTP

• Możliwość skonfigurowania własnego serwera SMTP do wysyłki maili z konta (np. potwierdzenia zamówień)
• Pola: host, port, SSL, login, hasło (szyfrowane), nadawca
• Przycisk "Testuj połączenie" — weryfikuje SMTP bez wysyłki
• Jeśli nie skonfigurowane — używany jest systemowy SMTP Dashbord.pl

Uwierzytelnianie dwuskładnikowe (2FA)

• Włączanie i wyłączanie 2FA dla własnego konta użytkownika
• Konfiguracja przez kod QR z aplikacją TOTP (Google Authenticator, Authy itd.)
• Zaufane urządzenia — opcja "Zaufaj temu urządzeniu przez 30 dni" przy logowaniu

Klucze API

• Generowanie kluczy API dla zewnętrznych systemów ERP (np. Subiekt GT, Symfonia)
• Każdy klucz ma etykietę i jest pokazywany tylko raz po wygenerowaniu
• Unieważnianie kluczy — natychmiast blokuje dostęp

Logi API

• Historia wszystkich wywołań API z kluczami ERP: czas, endpoint, status, adres IP
• Filtr okresu: 6h / 24h / 48h / 7 dni

Obsługiwane źródła

Porównujesz co faktycznie wpłynęło na Twoje konto z tym co masz w zamówieniach. Wgrywasz plik rozliczeniowy z Allegro, PayU, DPD czy innej platformy — system automatycznie dopasowuje każdą linię do zamówienia i pokazuje różnice.

Obsługiwane źródła

Format wykrywany automatycznie po nazwie pliku i nagłówkach — nie trzeba wybierać źródła ręcznie.

Import pliku

1. Przejdź do Rozliczenia → Import pliku
2. Kliknij Wybierz plik… i wskaż plik rozliczeniowy
3. Kliknij Importuj — system automatycznie wykrywa format i dopasowuje wiersze do zamówień
4. Po imporcie wyświetlane jest podsumowanie: dopasowane / niedopasowane / niejednoznaczne

Statusy dopasowania wiersza

Metody dopasowania

Historia importów

• Zakładka Historia importów — lista wszystkich wgranych plików z datą, nazwą, źródłem i statusem
• Kliknięcie importu pokazuje wiersze z filtrowaniem po statusie (Wszystkie / MATCHED / UNMATCHED / AMBIGUOUS)
• Każdy wiersz zawiera: externalId, kwotę klienta, kwotę otrzymaną, prowizję, nadpłatę, datę rozliczenia, datę pobrania przez ERP

Pobieranie rozliczeń przez API (dla systemu ERP)

System ERP może automatycznie pobierać wiersze rozliczeń z Dashbord przez API (uwierzytelnienie kluczem X-Api-Key). Przydatne gdy ERP ma pobierać kwoty prowizji, pobrań lub rozliczeń platform do własnych rejestrów.

Co pokazuje

• Lista wszystkich dokumentów ERP (faktur i paragonów) przesłanych przez zewnętrzny system (np. Subiekt GT, Symfonia)
• Typ dokumentu, numer, data, numer zamówienia, status dopasowania i kwota brutto
• Filtrowanie po statusie: Dopasowano / Częściowo / Nie dopasowano
• Sortowanie po każdej kolumnie (kliknięcie nagłówka)

Panel szczegółu dokumentu

• Lista pozycji: SKU, nazwa, ilość, cena brutto, koszt jednostkowy, stawka VAT, status dopasowania pozycji
• Przycisk "Przejdź do zamówienia" — otwiera zamówienie powiązane z dokumentem

Jak działa dopasowanie faktury do zamówienia

Gdy ERP przesyła dokument, Dashbord automatycznie szuka pasującego zamówienia po polu sourceOrderNumber — sprawdzane są kolejno dwa miejsca:

1. Order.externalId — zewnętrzny identyfikator zamówienia z platformy (np. checkoutFormId Allegro)
2. Order.providerOrderId — wewnętrzny numer zamówienia z OMS (Apilo, Sellasist itp.)

Po znalezieniu zamówienia Dashbord dopasowuje pozycje faktury do pozycji zamówienia po SKU (bez rozróżniania wielkości liter). Dla dopasowanych pozycji aktualizowany jest koszt zakupu (purchasePriceUnit) na pozycji zamówienia.

Statusy dopasowania

Pobieranie dokumentów ERP przez API

System ERP może też sam odpytywać Dashbord o listę dokumentów — np. żeby sprawdzić statusy dopasowania lub pobrać powiązane dane zamówień. Wymaga klucza X-Api-Key.

Przepływ: ERP ↔ Dashbord

Jak działa autoryzacja

Każde żądanie do API ERP wymaga nagłówka X-Api-Key z ważnym kluczem wygenerowanym dla Twojego konta. Klucze są przypisane do konkretnego konta (tenant) i widoczne tylko raz po wygenerowaniu.

Generowanie klucza

1. Przejdź do Ustawienia → Klucze API
2. Wpisz etykietę (np. Subiekt GT) i kliknij Generuj klucz
3. Skopiuj klucz — wyświetlany jest tylko raz
4. Umieść klucz w konfiguracji systemu ERP jako nagłówek X-Api-Key

Bezpieczeństwo

• Klucz przechowywany jako hash SHA-256 — nawet administrator nie może go odczytać po zamknięciu okna
• Każde użycie klucza jest logowane (Ustawienia → Logi API): czas, endpoint, status, IP
• Klucz można unieważnić w dowolnym momencie — operacja nieodwracalna

Scenariusz rozliczenia

Dashbord łączy zamówienia z e-commerce z dokumentami sprzedaży z ERP oraz z plikami rozliczeniowymi od operatorów płatności (Allegro Finanse, PayU, PayPo itp.). Dzięki temu ERP wie: która faktura została opłacona, kiedy i ile wpłynęło na konto.

POST /api/erp/documents

Przesyła fakturę lub paragon. Dashbord automatycznie szuka pasującego zamówienia i aktualizuje koszty zakupu pozycji.

// Nagłówki
Content-Type: application/json
X-Api-Key: twój-klucz-api

// Ciało żądania
{
  "documentType": "INVOICE",          // "INVOICE" lub "RECEIPT"
  "documentNumber": "FV/2024/001",
  "documentDate": "2024-01-15T12:00:00Z",  // opcjonalne
  "sourceOrderNumber": "12345",        // numer zamówienia lub GUID z OMS
  "totalNet": 89.43,                   // opcjonalne
  "totalGross": 110.00,                // opcjonalne
  "operatorPaymentSymbol": "PayU",     // opcjonalne — symbol operatora
  "paymentFormId": 3,                  // opcjonalne — id formy platnosci
  "dokId": 123456,                     // opcjonalne — Dok_id z ERP (bigint)
  "dokTyp": 2,                         // opcjonalne — 2=FV, 21=PA
  "paymentIdentifier": "a1b2c3d4-...", // opcjonalne — GUID lub nr listu
  "items": [                           // opcjonalne — pusta tablica = naglowek
    {
      "sku": "SKU-001",
      "name": "Produkt A",
      "quantity": 2,
      "unitPriceNet": 40.65,
      "unitPriceGross": 50.00,
      "purchasePriceUnit": 28.00,      // koszt zakupu — zapisywany do zamówienia
      "taxRate": 23
    }
  ]
}

Pola żądania

Pola pozycji (items[])

Odpowiedz 201 Created

{
  "importId": "clxxx...",      // GUID importu
  "documentId": "clyyy...",
  "matchStatus": "MATCHED",    // MATCHED | PARTIAL | UNMATCHED
  "orderId": "clzzz..."       // null jesli nie znaleziono zamowienia
}

Kody błędów

POST /api/erp/documents/bulk

Wsadowe przesłanie do 200 dokumentów w jednym żądaniu. Każdy dokument jest przetwarzany niezależnie — błąd jednego nie przerywa pozostałych. Odpowiedź HTTP 207 zawiera wynik dla każdego dokumentu z osobna.

// Nagłówki
Content-Type: application/json
X-Api-Key: twój-klucz-api

// Ciało żądania — tablica 1–200 dokumentów (ta sama struktura co pojedynczy dokument)
[
  {
    "documentType": "INVOICE",
    "documentNumber": "FV/2024/001",
    "documentDate": "2024-01-15T12:00:00Z",
    "sourceOrderNumber": "12345",
    "totalNet": 89.43,
    "totalGross": 110.00,
    "items": [
      {
        "sku": "SKU-001",
        "quantity": 2,
        "purchasePriceUnit": 28.00
      }
    ]
  },
  {
    "documentType": "INVOICE",
    "documentNumber": "FV/2024/002",
    "sourceOrderNumber": "12346",
    "items": [{ "sku": "SKU-002", "quantity": 1, "purchasePriceUnit": 45.00 }]
  }
]

Odpowiedź 207 Multi-Status

{
  "importId": "clxxx...",   // GUID importu
  "processed": 2,   // liczba dokumentow zapisanych bez bledu
  "failed": 0,      // liczba dokumentow, ktore nie zostaly zapisane
  "results": [
    {
      "documentNumber": "FV/2024/001",
      "documentId": "clxxx...",
      "matchStatus": "MATCHED",    // MATCHED | PARTIAL | UNMATCHED
      "orderId": "clyyy..."        // null jeśli nie znaleziono zamówienia
    },
    {
      "documentNumber": "FV/2024/002",
      "documentId": "clzzz...",
      "matchStatus": "UNMATCHED",
      "orderId": null
    }
  ]
}

// Gdy dokument nie mógł zostać zapisany, wynik zawiera pole "error":
{
  "documentNumber": "FV/2024/003",
  "documentId": "",
  "matchStatus": "UNMATCHED",
  "orderId": null,
  "error": "Duplicate key constraint"
}

Kody błędów

POST /api/erp/documents/import

Import masowy do 100 000 dokumentow. Przetwarzanie odbywa sie w tle — odpowiedz natychmiast zwraca importId, ktorym mozna odpytywac o status.

// Naglowki
Content-Type: application/json
X-Api-Key: twoj-klucz-api

// Cialo zadania — tablica 1–100 000 dokumentow (ta sama struktura co pojedynczy dokument)
// Limit body: 500 MB
[
  { "documentType": "INVOICE", "documentNumber": "FV/2024/001", "sourceOrderNumber": "12345", ... },
  { "documentType": "INVOICE", "documentNumber": "FV/2024/002", "sourceOrderNumber": "12346", ... },
  // ... do 100 000 dokumentow
]

Odpowiedz 202 Accepted

{
  "importId": "clxxx...",    // GUID — uzyj do pollingu statusu
  "totalCount": 50000,
  "status": "PENDING"
}

Polling statusu: GET /api/erp/documents/import/:id

// Odpytuj co kilka sekund az status zmieni sie na DONE lub ERROR
{
  "id": "clxxx...",
  "status": "PROCESSING",     // PENDING | PROCESSING | DONE | ERROR
  "totalCount": 50000,
  "processedCount": 12400,    // aktualizowany co 100 dokumentow
  "matchedCount": 11200,
  "errorCount": 15,
  "errors": [                  // null jesli brak bledow
    { "documentNumber": "FV/2024/999", "error": "..." }
  ],
  "createdAt": "2024-01-15T12:00:00Z",
  "startedAt": "2024-01-15T12:00:01Z",
  "completedAt": null          // null do zakonczenia
}

Kody bledow

GET /api/erp/documents

Pobiera listę dokumentów ERP dla Twojego konta (paginacja).

// Nagłówki
X-Api-Key: twój-klucz-api

Parametry query

Odpowiedź 200

{
  "items": [
    {
      "id": "clxxx...",
      "documentType": "INVOICE",
      "documentNumber": "FV/2024/001",
      "documentDate": "2024-01-15T12:00:00.000Z",
      "sourceOrderNumber": "12345",
      "orderId": "clyyy...",
      "matchStatus": "MATCHED",
      "totalGross": 110.00,
      "importedAt": "2024-01-15T12:05:00.000Z"
    }
  ],
  "total": 42,
  "page": 1,
  "pages": 5
}

GET /api/erp/documents/:id

Pobiera szczegóły jednego dokumentu wraz z pozycjami.

// Nagłówki
X-Api-Key: twój-klucz-api

Odpowiedź 200

{
  "id": "clxxx...",
  "documentType": "INVOICE",
  "documentNumber": "FV/2024/001",
  "documentDate": "2024-01-15T12:00:00.000Z",
  "sourceOrderNumber": "12345",
  "orderId": "clyyy...",
  "matchStatus": "MATCHED",
  "totalNet": 89.43,
  "totalGross": 110.00,
  "importedAt": "2024-01-15T12:05:00.000Z",
  "items": [
    {
      "id": "clzzz...",
      "sku": "SKU-001",
      "name": "Produkt A",
      "quantity": 2,
      "unitPriceNet": 40.65,
      "unitPriceGross": 50.00,
      "purchasePriceUnit": 28.00,
      "taxRate": 23,
      "orderItemId": "claaa..."   // null jeśli pozycja nie dopasowana
    }
  ]
}

Zwraca 404 gdy dokument nie istnieje lub należy do innego konta.

GET /api/erp/reconciliations

Zwraca faktury/paragony, które mają już dopasowaną płatność i jeszcze nie zostały odebrane przez ERP. Po pobraniu Dashbord oznacza je jako odebrane — przy kolejnym wywołaniu nie pojawią się ponownie.

// Nagłówki
X-Api-Key: twój-klucz-api

Odpowiedź 200

[
  {
    "id": "clxxx...",
    "documentType": "INVOICE",
    "documentNumber": "FV/2024/001",
    "documentDate": "2024-01-15T12:00:00.000Z",
    "sourceOrderNumber": "12345",
    "orderId": "clyyy...",
    "totalNet": 89.43,
    "totalGross": 110.00,
    "matchStatus": "MATCHED",
    "reconciliation": {
      "mode": "GROSS_PLUS_COMMISSION",   // tryb rozliczenia wybrany przy imporcie pliku
      "source": "allegro-finanse",        // identyfikator pliku źródłowego
      "sourceType": "ALLEGRO",
      "matchType": "BY_ORDER_ID",
      "customerAmount": 110.00,           // kwota zapłacona przez klienta
      "receivedAmount": 103.50,           // kwota po odjęciu prowizji
      "commissionAmount": 6.50,           // prowizja operatora
      "overpaymentAmount": 0,
      "currency": "PLN",
      "settledAt": "2024-01-16T08:00:00.000Z"
    }
  }
]

Zwraca pustą tablicę [] gdy nie ma nowych rozliczeń do odebrania. Pole reconciliation jest zawsze obecne (dokumenty bez dopasowania nie trafiają na tę listę).

GET /api/erp/reconciliations/:externalId

Pobiera rozliczenia dla konkretnego dokumentu po jego externalId (wewnętrzne ID rozliczenia w Dashbordzie). Zawsze zwraca dane — niezależnie od tego czy dokument był już pobierany przez ERP.

// Nagłówki
X-Api-Key: twój-klucz-api

Odpowiedź 200

[
  {
    "id": "clxxx...",
    "externalId": "TXN-ABC123",
    "matchStatus": "MATCHED",
    "matchType": "BY_ORDER_ID",
    "customerAmount": 110.00,
    "receivedAmount": 103.50,
    "commissionAmount": 6.50,
    "overpaymentAmount": 0,
    "currency": "PLN",
    "settledAt": "2024-01-16T08:00:00.000Z",
    "orderId": "clyyy...",
    "fetchedByErpAt": "2024-01-16T09:00:00.000Z",  // null jeśli jeszcze nie pobrane
    "source": "allegro-finanse",
    "sourceType": "ALLEGRO"
  }
]

Zwraca 404 gdy nie znaleziono rozliczenia o podanym externalId.

GET /api/erp/orders/:externalId/reconciliation

Pobiera rozliczenia powiązane z konkretnym zamówieniem, podając jego numer (externalId lub providerOrderId). Przydatne gdy ERP chce sprawdzić status rozliczenia dla konkretnego numeru zamówienia.

// Nagłówki
X-Api-Key: twój-klucz-api

Odpowiedź 200

[
  {
    "id": "clxxx...",
    "externalId": "TXN-ABC123",
    "matchStatus": "MATCHED",
    "matchType": "BY_ORDER_ID",
    "customerAmount": 110.00,
    "receivedAmount": 103.50,
    "commissionAmount": 6.50,
    "overpaymentAmount": 0,
    "currency": "PLN",
    "settledAt": "2024-01-16T08:00:00.000Z",
    "orderId": "clyyy...",
    "fetchedByErpAt": "2024-01-16T09:00:00.000Z",
    "source": "allegro-finanse",
    "sourceType": "ALLEGRO"
  }
]

Zwraca 404 gdy zamówienie o podanym numerze nie istnieje. Zwraca pustą tablicę [] gdy zamówienie istnieje, ale nie ma jeszcze rozliczeń.