# Wysyłam z Allegro

Integracja Wysyłam z Allegro w Ritevo: przypisanie konta Allegro, ustawienia paczki i punktów nadania, tworzenie przesyłek i etykiet dla zamówień z Allegro.

Integracja Wysyłam z Allegro tworzy przesyłki dla zamówień z Allegro przez usługę Wysyłam z Allegro. Nie ma własnego logowania - korzysta z konta Allegro, które masz już podłączone w Ritevo.

> **Wymagana integracja:** Potrzebujesz konta Allegro podłączonego w Ritevo jako [integracja Allegro](https://ritevo.com/pl/docs/integrations/allegro).

Integracji Wysyłam z Allegro możesz dodać dowolnie wiele, także kilka dla tego samego konta - na przykład z innym formatem etykiety, inną paczką albo innym adresem nadawcy. Każda działa osobno.

Unikalność nie jest sprawdzana, celowo: każde utworzenie integracji tworzy nową, także dla tego samego `externalId`, żeby jedno konto mogło mieć kilka integracji z różnymi danymi albo ustawieniami.

`externalId` nie jest używany. Integracja wskazuje konto Allegro przez `marketplaceAccountId`. Nie ma endpointu danych logowania - błąd autoryzacji dotyczy integracji Allegro pod `/integrations/marketplaces`, a zapis ustawień tej integracji zawsze ustawia `authError=false` i `active=true`.

## Jakie przesyłki tworzy

- **Tylko zamówienia z Allegro** - z tego konta Allegro, które wybierzesz w integracji. Przy innych zamówieniach nie zobaczysz przycisku, a akcja skończy się błędem **Zamówienie nie jest kompatybilne z wybraną integracją lub metodą wysyłki**.
- **Przewoźnik** - ten, którego kupujący wybrał na Allegro. Nie wybierasz go w Ritevo.
- **Punkt odbioru** - gdy kupujący wybrał paczkomat albo punkt, przesyłka trafia właśnie tam.
- **Pobranie** - gdy zamówienie jest za pobraniem, a wybrana dostawa Allegro obsługuje pobranie.

## Podłączenie konta

Zacznij w Ritevo:

1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu.
2. W sekcji **Przesyłki** wybierz kafelek **Wysyłam z Allegro**.
3. W polu **Konto marketplace Allegro** wybierz konto, z którego zamówienia chcesz wysyłać, a w polu **Nazwa konta** wpisz własną nazwę integracji.
4. Uzupełnij pozostałe ustawienia opisane niżej i kliknij **Utwórz integrację**. Otworzą się ustawienia nowej integracji.

![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp)

![Ekran Dodaj integrację z zaznaczonym kafelkiem Wysyłam z Allegro w sekcji Przesyłki](https://ritevo.com/docs/integrations/send-with-allegro/pl-catalogue.webp)

![Ekran dodawania konta Wysyłam z Allegro z polami Konto marketplace Allegro, Nazwa konta, Rozmiar strony i Format etykiety](https://ritevo.com/docs/integrations/send-with-allegro/pl-add.webp)

## Ustawienia integracji

Na stronie integracji znajdziesz poniższe pola. Zmiany zapisujesz przyciskiem **Zaktualizuj integrację**:

- **Konto marketplace Allegro** - konto Allegro, dla którego zamówień tworzysz przesyłki.
- **Nazwa konta** - Twoja własna nazwa integracji.
- **Rozmiar strony** - A4 albo A6. Domyślnie A4.
- **Format etykiety** - PDF albo ZPL. Domyślnie PDF.
- **Punkty odbioru** - numery punktów, w których nadajesz paczki poszczególnych przewoźników: DPD, Poczta Polska, Allegro One, Allegro International i InPost. Puste pole oznacza, że paczkę odbiera kurier, a uzupełnione - że nadajesz ją w tym punkcie. **Numer punktu UPS** dziś nie jest wykorzystywany.
- **Szczegóły paczki** - typ (**Paczka**, **List**, **Paleta** albo **Inne**), wymiary w centymetrach i waga w kilogramach. Te dane trafiają do każdej przesyłki.
- **Płatność za pobraniem** - **Numer konta IBAN** i **Właściciel konta**. Przekazujemy je tylko wtedy, gdy wybrana dostawa Allegro ich wymaga.
- **Adres nadawcy na etykiecie** - dane nadawcy, które przewoźnik drukuje na etykiecie.
- **Adres odbioru przesyłek przez kuriera** - adres, spod którego kurier odbiera paczki. Może być inny niż adres nadawcy na etykiecie - na przykład przy dropshippingu: na etykiecie jest Twój sklep, a kurier odbiera paczkę z hurtowni.
- **Dodatkowe ubezpieczenie** - kwota ubezpieczenia każdej przesyłki: **Brak**, **Wartość zamówienia z dostawą**, **Wartość zamówienia bez dostawy** albo **Stała kwota**. W **Źródło waluty** wybierasz walutę zamówienia, walutę kraju dostawy albo stałą walutę.

Pola integracji: `accountName`, `marketplaceAccountId` (id integracji Allegro z `GET /integrations/marketplaces`), `pageSize` = `A4` albo `A6`, `labelFormat` = `PDF` albo `ZPL`, numery punktów `dpdPickupPointNumber`, `upsPickupPointNumber`, `pocztaPolskaPickupPointNumber`, `allegroOnePickupPointNumber`, `allegroInternationalPickupPointNumber`, `inPostPickupPointNumber`, `packageDetails` z `packageType` (**Paczka** = `PACKAGE`, **List** = `DOX`, **Paleta** = `PALLET`, **Inne** = `OTHER`) oraz `length`, `width`, `height` w cm i `weight` w kg, a także `cashOnDeliveryBankDetails` z `iban` i `ownerName`.

Pola wspólne dla przesyłek: `senderAddress` i `pickupAddress` (`companyName`, `firstName`, `lastName`, `street`, `city`, `zipCode`, `countryCode`, `phoneNumber`, `email`) oraz `additionalInsurance`. W nim `insuranceType`: **Brak** = `NONE`, **Wartość zamówienia z dostawą** = `ORDER_AMOUNT_WITH_DELIVERY`, **Wartość zamówienia bez dostawy** = `ORDER_AMOUNT_WITHOUT_DELIVERY`, **Stała kwota** = `FIXED_AMOUNT` (kwota w `fixedAmount`), a `currencySource`: **Waluta zamówienia** = `ORDER_CURRENCY`, **Waluta kraju dostawy** = `DELIVERY_COUNTRY_CURRENCY`, **Stała waluta** = `FIXED` (waluta w `fixedCurrency`, wymagana przy `FIXED`).

![Szczegóły integracji Wysyłam z Allegro: ustawienia podstawowe z kontem Allegro i adres nadawcy na etykiecie](https://ritevo.com/docs/integrations/send-with-allegro/pl-details.webp)

![Karta Punkty odbioru z numerami punktów DPD, UPS, Poczta Polska, Allegro One, Allegro International i InPost](https://ritevo.com/docs/integrations/send-with-allegro/pl-pickup-points.webp)

![Karty Szczegóły paczki i Płatność za pobraniem z typem paczki, wymiarami, wagą, numerem IBAN i właścicielem konta](https://ritevo.com/docs/integrations/send-with-allegro/pl-package.webp)

![Karta Adres nadawcy na etykiecie z polami firmy, imienia i nazwiska, adresu, kraju, telefonu i e-maila](https://ritevo.com/docs/integrations/shipping/pl-sender.webp)

![Karta Adres odbioru przesyłek przez kuriera z polami firmy, imienia i nazwiska, adresu, kraju, telefonu i e-maila](https://ritevo.com/docs/integrations/shipping/pl-pickup-address.webp)

![Karta Dodatkowe ubezpieczenie z polami Typ ubezpieczenia i Źródło waluty](https://ritevo.com/docs/integrations/shipping/pl-insurance.webp)

> **Warto wiedzieć:** Integracja nie zamawia podjazdu kuriera. Podjazd zamawiasz bezpośrednio u przewoźnika albo ustawiasz u niego stały harmonogram odbiorów.

> **Warto wiedzieć:** Gdy zamówienie ma metodę płatności **Płatność przy odbiorze**, przesyłka dostaje pobranie automatycznie - w kwocie i walucie zamówienia.

## Tworzenie przesyłek

Przesyłkę tworzysz z zamówienia na dwa sposoby:

- **Ręcznie** - w szczegółach zamówienia, w karcie **Przesyłki**, kliknij przycisk z nazwą integracji Wysyłam z Allegro. Przyciski widzisz tylko dla aktywnych integracji, które pasują do zamówienia.
- **Automatycznie** - krokiem **Utwórz przesyłkę** w [akcjach dla zamówień](https://ritevo.com/pl/docs/automations/order-actions).

Dane przesyłki bierzemy z zamówienia:

- **Odbiorca** - adres dostawy z zamówienia oraz telefon i e-mail kupującego.
- **Punkt odbioru** - punkt wybrany przez kupującego, jeśli zamówienie go ma.
- **Pobranie** - kwota do zapłaty z zamówienia, gdy metoda płatności to **Płatność przy odbiorze**.
- **Paczka** - jedna przesyłka to zawsze jedna paczka.

W tej samej karcie każda przesyłka ma numer śledzenia, stan i datę utworzenia. Stany:

- **W trakcie tworzenia** (API: "W trakcie tworzenia" = `PENDING`; wartość w `shipments[].status`) - przewoźnik jeszcze tworzy przesyłkę. Sprawdzamy ją co kilka sekund. Jeśli przewoźnik nie potwierdzi przesyłki w ciągu 24 godzin, kończy się ona błędem.
- **Utworzona pomyślnie** (API: "Utworzona pomyślnie" = `SUCCESS`; wartość w `shipments[].status`) - przesyłka jest u przewoźnika i ma numer śledzenia.
- **Błąd podczas tworzenia** (API: "Błąd podczas tworzenia" = `ERROR`; wartość w `shipments[].status`) - przewoźnik nie przyjął przesyłki. Przy stanie widzisz powód, a przy błędzie przewoźnika także jego komunikat.

Etykietę utworzonej przesyłki pobierzesz przyciskiem **Pobierz** w karcie **Przesyłki**. Drukujesz ją na dwa sposoby - na komputerze z drukarką musi wtedy działać aplikacja [Ritevo Printer](https://ritevo.com/pl/docs/integrations/ritevo-printer):

- **Ręcznie** - w karcie **Przesyłki** kliknij **Drukuj** i wybierz drukarkę.
- **Automatycznie** - krokiem **Wydrukuj etykietę przesyłki** w [akcjach dla zamówień](https://ritevo.com/pl/docs/automations/order-actions). Krok drukuje etykietę ostatniej przesyłki ze stanem **Utworzona pomyślnie** - przesyłki w trakcie tworzenia i z błędem pomija.

Druk etykiet najlepiej zaplanować po kolei, jako dwie akcje:

- **Pierwsza akcja** - kończy się krokiem **Utwórz przesyłkę**.
- **Druga akcja** - startuje wyzwalaczem **Stworzono przesyłkę**, ma warunek **Status przesyłki jest** z wartością **Utworzona pomyślnie** i jeden krok **Wydrukuj etykietę przesyłki**. Dzięki temu każda nowa przesyłka od razu drukuje swoją etykietę - także gdy zamówienie ma kilka paczek.

> **Warto wiedzieć:** Krok **Wydrukuj etykietę przesyłki** drukuje zawsze tylko jedną etykietę - najnowszej udanej przesyłki. Jeśli najpierw utworzysz wszystkie przesyłki, a dopiero potem włączysz druk, wydrukuje się tylko ostatnia, a pozostałe wydrukujesz ręcznie przyciskiem **Drukuj**. Jeśli nowa przesyłka się nie uda, krok wydrukuje etykietę poprzedniej udanej.

> **Warto wiedzieć:** Każde kliknięcie przycisku i każde uruchomienie kroku **Utwórz przesyłkę** tworzy nową przesyłkę u przewoźnika. Przesyłki nie da się anulować w Ritevo - anulujesz ją w panelu przewoźnika.

### Jak przesyłka trafia do Allegro

- **Potwierdzenie** - Allegro tworzy przesyłkę w tle, więc najpierw ma ona stan **W trakcie tworzenia**.
- **Numer śledzenia** - numer przesyłki nadany przez Allegro.
- **Pobranie bez numeru konta** - gdy dostawa wymaga numeru konta do pobrania, a nie podałeś go w integracji, przesyłka skończy się błędem.
- **Dostawa bez pobrania** - zamówienie za pobraniem z dostawą, która nie obsługuje pobrania, też skończy się błędem.

Przesyłkę tworzysz przez `POST /orders/{orderId}/create-shipments/{shipmentIntegrationId}` - odpowiedź 202, a wynik pojawia się później w `shipments[]` zamówienia (`status`, `trackingNumber`, `errorType`, `errorMessage`). Etykietę pobierasz przez `GET /orders/{orderId}/shipments/{shipmentId}/label`, a wydruk zlecasz przez `POST /orders/{orderId}/print-shipment-label/{shipmentId}/{printerIntegrationId}`.

Akcje dla zamówień: krok **Utwórz przesyłkę** to `CREATE_SHIPMENT`, a **Wydrukuj etykietę przesyłki** to `PRINT_SHIPMENT_LABEL` - oba w `actionSteps[].action.type`, z `uuidValue` = id integracji wysyłkowej (`GET /integrations/shippings`) albo id drukarki (`GET /integrations/printers`). Wyzwalacz **Stworzono przesyłkę** to `triggerType` = `CREATE_SHIPMENT`. Warunki: **Posiada przesyłkę** / **Nie posiada przesyłki** = `HAS_SHIPMENT` / `HAS_SHIPMENT_NOT` (`booleanValues` = `[true]`), **Status przesyłki jest** / **Status przesyłki nie jest** = `SHIPMENT_STATUS_IS` / `SHIPMENT_STATUS_IS_NOT` (`enumValues`: `PENDING`, `SUCCESS`, `ERROR`), **Przesyłka należy do integracji** / **Przesyłka nie należy do integracji** = `SHIPMENT_SHIPPING_INTEGRATION_IS` / `SHIPMENT_SHIPPING_INTEGRATION_IS_NOT` (`uuidValues` = id integracji wysyłkowych). Druk etykiety w akcji bierze najnowszą przesyłkę z `status` = `SUCCESS` (po `createdAt`); ręczny druk przez `POST /orders/{orderId}/print-shipment-label/...` też przyjmuje tylko przesyłkę `SUCCESS`, inaczej zwraca `SHIPMENT_NOT_FOUND`. `SHIPMENT_STATUS_IS` jest spełniony, gdy dowolna przesyłka zamówienia ma podany status, nie tylko ostatnia. Pełny opis: [Akcje dla zamówień](https://ritevo.com/pl/docs/automations/order-actions).

## Wymaga ponownego połączenia

Wysyłam z Allegro nie ma własnego logowania, więc sama nie wymaga ponownego połączenia. Gdy konto Allegro przestanie działać, połącz je ponownie na stronie [integracji Allegro](https://ritevo.com/pl/docs/integrations/allegro#reconnect) - przesyłki zaczną działać bez zmian w tej integracji.

## Usunięcie integracji

**Usuń integrację** wyłącza integrację w Ritevo. Przesyłki utworzone wcześniej zostają w zamówieniach i u przewoźnika. **Przywróć integrację** włącza ją z powrotem.

## Czego integracja nie robi

- Nie zamawia podjazdu kuriera.
- Nie anuluje przesyłek.
- Nie śledzi przesyłki po jej utworzeniu - stan doręczenia sprawdzasz u przewoźnika.
- Nie przekazuje numeru śledzenia do kanału sprzedaży.
- Nie tworzy przesyłek z kilkoma paczkami.
- Nie tworzy przesyłek dla zamówień spoza wybranego konta Allegro.

## Integracja przez API

Endpointy tej integracji są pod `/integrations/shippings/send-with-allegro`, a wspólne dla całego typu (lista, pobranie jednej, usunięcie, przywrócenie) pod `/integrations/shippings`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs.


---

Cała pomoc w jednym pliku: https://ritevo.com/llms-full.txt. Mapa pomocy z linkami do wszystkich stron: https://ritevo.com/llms.txt.