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.
Jak to działa
Dział zatytułowany „Jak to działa”| 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 |
Faktury przez automatyzacje
Dział zatytułowany „Faktury przez automatyzacje”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.
-
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 StatusyZdarzenie 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}/CallUruchomienie 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.
-
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 Acceptedzawiera identyfikator uruchomienia. Polecontextjest wymagane (dowolna niepusta etykieta). Dla wielu zamówień użyjPOST /api/v3/automaticScripts/start_batch. -
Sprawdź wynik uruchomienia
GET /api/v3/runs/{id}zwraca stan uruchomienia, aGET /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}. -
Odczytaj fakturę z zamówienia
Gotowa faktura pojawia się w załącznikach zamówienia (pole
attachmentswGET /api/v5/Orders, zuploadTypeiinvoiceNumber). Plik pobierzesz przezGET /api/v3/Orders/Download/{orderAttachmentId}.
Korekty i dokumenty WZ
Dział zatytułowany „Korekty i dokumenty WZ”- 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.
Własny system fakturowy
Dział zatytułowany „Własny system fakturowy”Jeśli faktury wystawia Twój ERP lub program księgowy, dołącz PDF do zamówienia jako załącznik typu faktura:
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.pdfPOST /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).
Na co uważać
Dział zatytułowany „Na co uważać”- 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: truewyłą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
addInvoiceigetInvoicesw trybie zgodności z BaseLinkerem to zaślepki — zobacz Beel API → Faktury.
Odpowiedniki w BaseLinker
Dział zatytułowany „Odpowiedniki w BaseLinker”| 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 |
Zobacz też
Dział zatytułowany „Zobacz też”- Automatyzacje — uruchamianie skryptów, logi, zdarzenia użytkownika
- Statusy zamówień — zmiana statusu jako wyzwalacz
- Pobieranie zamówień — odczyt załączników zamówienia
- Zwroty — korekty przy zwrotach

