orderPRO/.paul/docs/API.md

API

Zakres

• Dokument opisuje aktualne endpointy z routes/web.php (stan repo: 2026-04-18).
• Runtime API jest oparte o sesje (AuthMiddleware) i CSRF dla formularzy.
• Publiczny endpoint bez sesji: GET /cron (token w query lub segmencie sciezki).
• API dla klienta drukowania uzywa X-Api-Key (ApiKeyMiddleware).

Uwierzytelnianie

• Session auth: wszystkie trasy panelowe i wiekszosc tras /api/*.
• API key auth: tylko zdalne kolejki druku.
• CSRF: wszystkie trasy POST w panelu (_token w body).

Endpointy publiczne

• GET /health - status aplikacji JSON.
• GET /info - strona info.
• GET /cron?token=... - uruchomienie crona przez HTTPS.
• GET /cron/{tokenValue} - alternatywny wariant tokenu w sciezce.

Auth

• GET /login - formularz logowania.
• POST /login - logowanie.
• POST /logout - wylogowanie.

Nawigacja i dashboard

• GET / - redirect do /settings/users (zalogowany) albo /login.
• GET /users - redirect do /settings/users.
• GET /orders - redirect do /orders/list.
• GET /settings - redirect do /settings/users.

Orders

• GET /orders/list - lista zamowien; AJAX zwraca fragmenty HTML tabeli/panelu statusow.
• GET /orders/{id} - szczegoly zamowienia.
• POST /orders/{id}/status - zmiana statusu; obsluguje HTML i AJAX JSON.
• POST /orders/{id}/details/update - update formy dostawy/platnosci.
• POST /orders/{id}/send-email - wysylka e-mail z szablonu (JSON).
• POST /orders/{id}/email-preview - preview e-maila (JSON: subject/body/attachments).
• POST /orders/{id}/payment/add - reczne dodanie platnosci (JSON).
• GET /api/orders/search - quick search (JSON).
• GET /api/orders/{id}/preview - podglad mini karty zamowienia (HTML fragment).

Receipts i accounting

• GET /orders/{id}/receipt/create
• POST /orders/{id}/receipt/store
• GET /orders/{id}/receipt/{receiptId}
• GET /orders/{id}/receipt/{receiptId}/print
• GET /orders/{id}/receipt/{receiptId}/pdf
• GET /accounting - lista paragonow.
• POST /accounting/export - eksport danych ksiegowych.

Shipments

• GET /orders/{id}/shipment/prepare
• POST /orders/{id}/shipment/create
• GET /orders/{id}/shipment/{packageId}/status
• POST /orders/{id}/shipment/{packageId}/label
• POST /orders/{id}/shipment/manual
• POST /orders/{id}/shipment/{packageId}/delete

Printing API

• Session auth:
• POST /api/print/jobs - dodanie zlecenia druku.
• GET /api/print/jobs/status - statusy kolejek.
• API key auth (X-Api-Key):
• GET /api/print/jobs/pending - lista zadan pending.
• GET /api/print/jobs/{id}/download - pobranie etykiety.
• POST /api/print/jobs/{id}/complete - finalizacja zadania.

Settings: users i baza

• GET /settings/users
• POST /settings/users
• GET /settings/database
• POST /settings/database/migrate

Settings: statusy

• GET /settings/statuses
• POST /settings/status-groups
• POST /settings/status-groups/update
• POST /settings/status-groups/delete
• POST /settings/status-groups/reorder
• POST /settings/statuses/create
• POST /settings/statuses/update
• POST /settings/statuses/delete
• POST /settings/statuses/reorder

Settings: cron i integracje

• GET /settings/cron
• POST /settings/cron
• GET /settings/integrations

Settings: Allegro

• GET /settings/integrations/allegro
• POST /settings/integrations/allegro/save
• POST /settings/integrations/allegro/settings/save
• POST /settings/integrations/allegro/oauth/start
• GET /settings/integrations/allegro/oauth/callback
• POST /settings/integrations/allegro/import-single
• POST /settings/integrations/allegro/statuses/save
• POST /settings/integrations/allegro/statuses/save-bulk
• POST /settings/integrations/allegro/statuses/delete
• POST /settings/integrations/allegro/statuses/save-pull
• POST /settings/integrations/allegro/statuses/sync
• POST /settings/integrations/allegro/delivery/save

Settings: Apaczka / Inpost / shopPRO

• GET /settings/integrations/apaczka
• POST /settings/integrations/apaczka/save
• POST /settings/integrations/apaczka/test
• GET /settings/integrations/inpost
• POST /settings/integrations/inpost/save
• GET /settings/integrations/shoppro
• POST /settings/integrations/shoppro/save
• POST /settings/integrations/shoppro/test
• POST /settings/integrations/shoppro/statuses/save
• POST /settings/integrations/shoppro/statuses/save-pull
• POST /settings/integrations/shoppro/statuses/sync
• POST /settings/integrations/shoppro/delivery/save

Settings: firma, e-mail, automatyzacja, delivery mapping

• GET /settings/company
• POST /settings/company/save
• GET /settings/accounting
• POST /settings/accounting/save
• POST /settings/accounting/toggle
• POST /settings/accounting/delete
• GET /settings/email-mailboxes
• POST /settings/email-mailboxes/save
• POST /settings/email-mailboxes/delete
• POST /settings/email-mailboxes/toggle
• POST /settings/email-mailboxes/test
• GET /settings/email-templates
• GET /settings/email-templates/create
• GET /settings/email-templates/edit
• POST /settings/email-templates/save
• POST /settings/email-templates/delete
• POST /settings/email-templates/duplicate
• POST /settings/email-templates/toggle
• POST /settings/email-templates/preview
• GET /settings/email-templates/variables
• GET /settings/automation
• GET /settings/automation/create
• POST /settings/automation/store
• GET /settings/automation/edit
• POST /settings/automation/update
• POST /settings/automation/delete
• POST /settings/automation/duplicate
• POST /settings/automation/toggle
• GET /settings/delivery-status-mappings
• POST /settings/delivery-status-mappings/save
• POST /settings/delivery-status-mappings/save-bulk
• POST /settings/delivery-status-mappings/reset
• POST /settings/delivery-status-mappings/reset-all

Settings: druk i mapowania projektow

• GET /settings/printing
• POST /settings/printing/keys/create
• POST /settings/printing/keys/{id}/delete
• POST /settings/printing/jobs/delete
• GET /settings/project-mappings
• POST /settings/project-mappings
• POST /settings/project-mappings/{id}/update
• POST /settings/project-mappings/{id}/delete
• POST /settings/project-mappings/{id}/toggle

API shipment presets

• GET /api/shipment-presets
• POST /api/shipment-presets
• POST /api/shipment-presets/update
• POST /api/shipment-presets/delete

Kontrakty JSON (najwazniejsze)

• GET /health: {status, app, timestamp}.
• GET /cron*: {ok, message, limit, timestamp} albo blad {ok:false, message, error?}.
• POST /api/print/jobs: tworzy rekord kolejki dla package_id; zwraca JSON statusu.
• GET /api/print/jobs/pending: lista pending dla klienta desktop.
• POST /api/print/jobs/{id}/complete: potwierdza wydruk, ustawia completed.
• GET /api/orders/search: {results:[...]}.
• POST /orders/{id}/payment/add: {ok, payment_id, payment_status, total_paid} lub blad.