Przejdź do głównej zawartości

Faktury

Sellrocket nie jest programem księgowym — faktury powstają w zewnętrznym systemie fakturowym, a w zamówieniu lądują jako załącznik (PDF z numerem faktury). Masz dwie drogi: zlecić wystawienie faktury automatyzacji (skryptowi AJS z akcją fakturową) albo wystawiać ją we własnym systemie i tylko dołączyć plik do zamówienia. W obu przypadkach faktura jest widoczna w zamówieniu, można ją wysłać klientowi e-mailem z automatyzacji, a jeśli integracja kanału sprzedaży to obsługuje — przekazać na marketplace.

Automatyzacja z akcją fakturową Własny system fakturowy
Kto wystawia fakturę System fakturowy podłączony w Sellrocket Twój system (ERP, program księgowy)
Konfiguracja Połączenie fakturowe i skrypt z akcją „wystaw fakturę” — w panelu Brak — tylko token API
Jak zlecasz Zdarzenie w zamówieniu (np. zmiana statusu), przycisk lub uruchomienie skryptu przez API OMS → Załączniki zamówienia
Korekty Skrypt z akcją korekty W Twoim systemie, plik korekty jako kolejny załącznik

Połączenie fakturowe (konto w systemie fakturowym, dział firmy, numeracja) oraz skrypt z akcją fakturową konfiguruje administrator instancji w panelu — w kreatorze automatyzacji. W akcji ustawia się m.in.:

Ustawienie Znaczenie
Rodzaj dokumentu M.in. faktura VAT, proforma, paragon, faktura VAT marża (z wybraną procedurą marży)
Data sprzedaży / wystawienia Data pobrania zamówienia, data jego potwierdzenia albo konkretna data
Język, dział firmy Język dokumentu i dział z systemu fakturowego
VAT dostawy Stawka z pierwszej pozycji zamówienia albo podana wprost
OSS Rozpoznanie sprzedaży w procedurze OSS

Faktura powstaje na podstawie danych zamówienia (nabywca i dane do faktury, pozycje, dostawa). Jako integrator nie budujesz treści faktury — wyzwalasz skrypt dla zamówienia.

  1. Wybierz sposób wyzwolenia

    Sposób Kiedy Co robisz w API
    Zdarzenie — np. ustawienie statusu „Do faktury” (skrypt z wyzwalaczem „zmiana statusu” i warunkiem na status) Faktura ma powstawać w ustalonym momencie procesu Zmieniasz status: PUT /api/v4/Orders/OrdersStatusUpdate — zobacz Statusy
    Zdarzenie użytkownika — przycisk „Wystaw fakturę” w panelu Ten sam skrypt ma być dostępny dla obsługi i dla Twojej integracji POST /api/v3/UserEvents/{userEventId}/Call
    Uruchomienie skryptu Chcesz wystawić fakturę na żądanie, bez zmiany statusu POST /api/v3/automaticScripts/start/{id}

    Najprostsza i najbardziej przewidywalna jest zmiana statusu — sprzedawca widzi w panelu, na jakim etapie jest zamówienie, a ten sam skrypt działa dla zamówień obsługiwanych ręcznie.

  2. Uruchom skrypt fakturowy dla zamówienia (jeśli nie korzystasz ze statusu)

    ID skryptu znajdziesz na liście GET /api/v1/automaticScripts (np. po nazwie lub grupie „Faktury”).

    Okno terminala
    curl -X POST "https://$SR_INSTANCE-ajs-api.enterprise.sellrocket.pl/api/v3/automaticScripts/start/57" \
    -H "Authorization: Bearer $SR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{ "context": "api", "order": { "id": 204295 } }'

    Odpowiedź 202 Accepted zawiera identyfikator uruchomienia. Pole context jest wymagane (dowolna niepusta etykieta). Dla wielu zamówień użyj POST /api/v3/automaticScripts/start_batch.

  3. Sprawdź wynik uruchomienia

    GET /api/v3/runs/{id} zwraca stan uruchomienia, a GET /api/v1/runs/{id}/logs — logi (np. błąd systemu fakturowego). Akcja fakturowa czeka na zakończenie wystawiania, więc zakończone uruchomienie oznacza, że system fakturowy przetworzył zlecenie. Historia skryptów wykonanych dla zamówienia: GET /api/v1/runs/history/{orderId}.

  4. Odczytaj fakturę z zamówienia

    Gotowa faktura pojawia się w załącznikach zamówienia (pole attachments w GET /api/v5/Orders, z uploadType i invoiceNumber). Plik pobierzesz przez GET /api/v3/Orders/Download/{orderAttachmentId}.

  • Korekta — osobna akcja w kreatorze automatyzacji, z powodem korekty i połączeniem fakturowym. Wyzwalasz ją tak samo jak fakturę (np. status „Zwrot przyjęty” albo uruchomienie skryptu). Obsługiwane są wyłącznie korekty pełne — całej faktury zamówienia.
  • Dokument wydania zewnętrznego (WZ) — również akcja automatyzacji, skonfigurowana w panelu.

Jeśli faktury wystawia Twój ERP lub program księgowy, dołącz PDF do zamówienia jako załącznik typu faktura:

Okno terminala
curl -X POST "https://$SR_INSTANCE-smerp-api.enterprise.sellrocket.pl/api/v3/Orders/204295/Attachments/FV-2026-10-0042.pdf" \
-H "Authorization: Bearer $SR_TOKEN" \
-H "Content-Type: application/octet-stream" \
-H "Upload-Type: Invoice" \
-H "Invoice-Number: FV/2026/10/0042" \
--data-binary @FV-2026-10-0042.pdf

POST /api/v3/Orders/{orderId}/Attachments/{filename} przyjmuje plik w treści żądania, a metadane w nagłówkach:

Nagłówek Znaczenie
Upload-Type Typ załącznika, np. Invoice
Invoice-Number Numer faktury widoczny w zamówieniu
Ksef-Number Numer KSeF, jeśli faktura została już wysłana do KSeF

Operacja jest asynchroniczna (zwraca JobDTO). Numer faktury poprawisz przez PUT /api/v3/Orders/{orderId}/Attachments/{attachmentId}.

Czy integracja kanału sprzedaży potrafi przekazać fakturę na marketplace, pokazuje flaga invoiceTransfer w definicji połączenia (GET /api/v3/ConnectionDefinitions).

  • Nie wystawiaj faktury dwa razy. Jeśli skrypt fakturowy reaguje na status, a Ty dodatkowo uruchamiasz go przez API — powstaną dwie faktury. Przed uruchomieniem sprawdź, czy zamówienie nie ma już załącznika-faktury.
  • Warunki skryptu nadal obowiązują. Warunki (np. „status = Do faktury”, „klient chce fakturę”) są częścią kodu skryptu — jeśli zamówienie ich nie spełnia, uruchomienie zakończy się bez faktury. Sprawdź logi uruchomienia.
  • Zmiany „po cichu” nie wystawią faktury. Nagłówek X-SR-ForceSilentChanges: true wyłącza automatyzacje — zmiana statusu z tym nagłówkiem nie uruchomi skryptu fakturowego (Konwencje API).
  • Korekty częściowe nie są obsługiwane przez akcję korekty — przy częściowym zwrocie wystaw korektę w systemie fakturowym lub w swoim systemie i dołącz ją jako załącznik.
  • Konfiguracja należy do sprzedawcy. ID skryptu, przycisku czy statusu „Do faktury” ustala administrator instancji — opisz je w dokumentacji wdrożenia, nie zakładaj ich na sztywno w kodzie.
  • Beel API nie wystawia faktur. Metody addInvoice i getInvoices w trybie zgodności z BaseLinkerem to zaślepki — zobacz Beel API → Faktury.
BaseLinker Sellrocket
addInvoice Skrypt z akcją fakturową: zmiana statusu, POST /api/v3/UserEvents/{userEventId}/Call lub POST /api/v3/automaticScripts/start/{id}
getInvoices Załączniki-faktury w zamówieniu: attachments w GET /api/v5/Orders
getInvoiceFile GET /api/v3/Orders/Download/{orderAttachmentId}
addOrderInvoiceFile POST /api/v3/Orders/{orderId}/Attachments/{filename} z Upload-Type: Invoice
Akcja automatyczna „Wystaw fakturę” Akcja fakturowa w skrypcie AJS — Automatyzacje
Korekta faktury Skrypt z akcją korekty