core/printnode

Moduł Orbito wysyłający pliki PDF do drukarek obsługiwanych przez PrintNode. Korzysta z Basic Auth (klucz API jako nazwa użytkownika), GET /printers i POST /printjobs zgodnie z oficjalną dokumentacją PrintNode.

Moduł rejestruje się również jako dostawca wspólnego kontraktu core.printing.getProvider. Przyciski w core/shipping nie odwołują się bezpośrednio do PrintNode, więc można wyłączyć ten moduł i włączyć core/printer bez zmian w UI. Jednocześnie aktywny powinien być tylko jeden moduł drukowania.

Konfiguracja

Po włączeniu modułu skonfiguruj:

1. globalny blok Połączenie z PrintNode — sekret apiKey;
2. globalny blok Domyślna drukarka — defaultPrinterId;
3. opcjonalny blok użytkownika Moja drukarka — printerId, który ma pierwszeństwo przed drukarką globalną.

Administrator Orbito musi również zatwierdzić domenę api.printnode.com dla Core.fetch, ponieważ wywołania PrintNode są wykonywane przez serwerowy proxy Orbito.

Klucz API nigdy nie jest zwracany do interfejsu ani umieszczany w logach. Lista drukarek jest pobierana z PrintNode z limitem czasu.

Metody

printBase64(params, ctx)

Wymaga uprawnienia print.base64.

Parametry:

• base64 lub contentBase64 — PDF zakodowany base64 (może być data URL application/pdf), maksymalnie 20 MB po dekodowaniu;
• title — opcjonalny tytuł kolejki, maksymalnie 200 znaków;
• options — opcjonalny, ograniczony rozmiarem prosty obiekt JSON opcji PrintNode;
• idempotencyKey — opcjonalny klucz 8–128 znaków.

Sukces zwraca { success, printJobId, idempotencyKey, duplicate, requestId, outcomeUncertain }.

printShipmentLabel(params, ctx)

Wymaga uprawnienia print.shipment_label. Przyjmuje jedno z:

• shipmentId — etykieta jest pobierana przez bezpieczne core/shipping.shipments.getLabel, które odczytuje przesyłkę po jej identyfikatorze i wybiera zapisanego przewoźnika;
• gotowy PDF w base64/contentBase64; albo
• pełny obiekt shipmentData (lub shipment). Dla DPD moduł korzysta z carrierData.sessionId/reference i core/dpd.getLabel; dla InPost z carrierData.inpostShipmentId/externalId i core/inpost.getLabel. shipmentData._id, jeśli obecne razem z shipmentId, musi być zgodne.

core/dpd i core/inpost są opcjonalnymi integracjami wykonawczymi. Gdy odpowiedni moduł nie jest zainstalowany albo dane przewoźnika są niepełne, należy przekazać gotowy PDF.

Automatyzacje

Akcja Wyślij etykiety zamówienia do PrintNode wymaga klucza zdarzenia core/orders:ORDER_ID (od SDK 4.0.0 klucze innych modułów występują wyłącznie z prefiksem), więc można podłączyć ją bezpośrednio do triggerów Zamówienie spakowane i Nowa przesyłka. Opcjonalnie czyta core/shipping:SHIPMENT_ID, aby wydrukować tylko nową przesyłkę, oraz core/shipping:USER_ID jako użytkownika, na którego drukarce powstaje wydruk. Dla zdarzenia pakowania drukuje wszystkie etykiety zamówienia na drukarce użytkownika, który jako ostatni pakował pozycję. Brak użytkownika albo jego drukarki kończy akcję błędem — automatyzacja nie przechodzi po cichu na drukarkę globalną.

Akcja czeka do 6 godzin na utworzenie przesyłki, po czym pobiera i wysyła do PrintNode właściwą nową etykietę albo komplet etykiet zamówienia — zależnie od triggera. Opcjonalny parametr pozwala ustawić liczbę kopii od 1 do 100. Stabilny klucz idempotencji jest osobny dla każdego biegu i każdej przesyłki.

Idempotencja i wyniki niepewne

Każdy POST /printjobs ma X-Idempotency-Key. Caller może przekazać stabilny klucz logicznego wydruku; w przeciwnym razie moduł generuje UUID dla pojedynczego wywołania. Moduł nigdy nie ponawia automatycznie POST.

HTTP 409 oznacza kolizję klucza zatrzymywaną przez PrintNode. Moduł traktuje ją deterministycznie jako sukces { duplicate: true, printJobId: null }: nowe zadanie nie zostało utworzone. Klucza wolno ponownie użyć wyłącznie dla identycznego logicznego wydruku; odpowiedź 409 nie potwierdza zgodności treści starego i nowego payloadu. PrintNode przechowuje klucze przez 24 godziny.

Timeout lub błąd transportu po rozpoczęciu POST zwraca success: false, outcomeUncertain: true oraz idempotencyKey. Nie należy wtedy generować nowego klucza ani wysyłać wydruku „od nowa”; ponowienie z tym samym kluczem pozwala PrintNode odrzucić duplikat. Błędy API są celowo zwięzłe i nie zawierają klucza API ani treści PDF.

Weryfikacja

npm test
omm pack -C printnode-module --dry-run