Allegro REST API

gdzie?

Jak zarządzać przesyłkami przez Wysyłam z Allegro

Wysyłam z Allegro to narzędzie, które ułatwia zarządzanie przesyłkami w Allegro. Sprzedawcy mogą utworzyć w nim i wydrukować etykiety oraz zamówić odbiór paczek ze wskazanego adresu.

Aktualnie w naszym API, w ramach usługi "Wysyłam z Allegro" udostępniamy zasoby na ścieżce /shipment-management, za pomocą których możesz zarządzać swoimi przesyłkami, utworzyć etykietę, pobrać protokół nadania, a także zamówić podjazd kuriera.

Zanim skorzystasz z API Wysyłam z Allegro, aktywuj swoje konto. Możesz to zrobić poprzez:

Zmiany konfiguracyjne, które wprowadzasz w GUI, wymagają odczekania kilku minut, aż ich wyniki będą widoczne w API.

Jak pobrać listę usług dostawy

Skorzystaj z GET /shipment-management/delivery-services, aby pobrać listę usług dostawy dostępnych dla zautoryzowanego użytkownika. W odpowiedzi zwrócimy dostępne usługi dostawy zdefiniowane na koncie użytkownika, w tym:

  • identyfikator usługi dostawy,
  • identyfikator umowy własnej (jeśli występuje),
  • nazwę usługi dostawy,
  • identyfikator przewoźnika,
  • usługi dodatkowe w ramach danej usługi dostawy.

Identyfikator usługi dostawy przekaż w polu "deliveryMethodId", gdy będziesz tworzyć nową paczkę, korzystając z POST /shipment-management/shipments/create-commands.

Przykładowy request:

curl -X GET \
  'https://api.allegro.pl/shipment-management/delivery-services' \
  -H 'Authorization: Bearer {token}'  \
  -H 'Accept: application/vnd.allegro.public.v1+json'
{
  "services": [
    {
      "id": {
        "deliveryMethodId": "c3066682-97a3-42fe-9eb5-3beeccab840c",    // id usługi dostawy
        "credentialsId": "c9e6f40a-3d25-48fc-838c-055ceb1c5bc0"    // id umowy własnej (jeśli brak, zwracamy "null")
      },
      "name": "Allegro Courier DPD",    // nazwa usługi dostawy
      "carrierId": "DPD",    // id przewoźnika
      "additionalServices": [   // usługi dodatkowe w ramach danej usługi dostawy
        {
          "id": "ADDITIONAL_HANDLING",
          "name": "Non-standard parcel",
          "description": "string"
        }
      ],
      "owner": "ALLEGRO",    // właściciel umowy z przewoźnikiem; dostępne wartości to ALLEGRO lub CLIENT
      "marketplaces": [   // serwis zagraniczny Allegro, do którego przypisana jest usługa dostawy
        "allegro-pl"
      ],
      "packageTypes": [   // typ przesyłki; dostępne wartości: PACKAGE (paczka), DOX (list)
        "DOX"
      ],
      "cashOnDelivery": {    // płatność przy odbiorze
        "limit": 50000,    // limit płatności przy odbiorze
        "currency": "PLN",    // waluta płatności przy odbiorze
        "paymentType": "MONEY_TRANSFER",    // typ płatności; dostępne wartości: MONEY_TRANSFER (przekaz), WALLET)_TRANSFER (przelew)
        "forceRequireIban": true    // wymagany numer IBAN (true - tak, false - nie)
      },
      "insurance": {    // dodatkowa ochrona przesyłki
        "limit": 50000,    // limit kwoty dodatkowej ochrony przesyłki
        "currency": "PLN"    // waluta kwoty dodatkowej ochrony przesyłki
      },
      "features": {    // dodatkowe informacje, zwracamy tylko dla metod Allegro One
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      }
    }
  ]
}

Jak utworzyć nową paczkę

Wybrana przez kupującego metoda dostawy przypisana jest na stałe do usługi dostawy.

Wyróżniamy dwa typy identyfikatorów usług dostawy:

Dla umowy Allegro

Identyfikatory usług dostawy są jednakowe dla wszystkich sprzedawców i są one na stałe przypisane do metod dostawy. Gdy skorzystasz z GET /shipment-management/delivery-services - identyfikator ten zwrócimy również w polu "deliveryMethodId", np.

  • metoda dostawy Allegro Kurier UPS o ID 0e4c7d59-64b6-4b06-89c3-c1d941506dd0 powiązana jest z usługą dostawy o identycznym ID,
  • metoda dostawy Allegro Kurier UPS pobranie o ID 199d2a2a-7c90-4ca7-aaf3-c1d941506dd0 powiązana jest z usługą dostawy o identycznym ID.

Dla umowy własnej

Do utworzenia przesyłki z umową własną, potrzebne są dane, które zwracamy w GET /shipment-management/delivery-services, odpowiednio:

  • id_metody - w polu "deliveryMethodId",
  • id_umowy_własnej - w polu "credentialsId", po wcześniejszym dodaniu umowy własnej w ustawieniach.

Umowa Allegro Inpost wymaga dodania w ustawieniach Wysyłam z Allegro umowy własnej.

W przypadku, gdy tworzysz nową przesyłkę InPost za pomocą POST /shipment-management/shipments/create-commands, przekaż dla wybranej metody dostawy z "carrierId": "INPOST" jedną z obsługiwanych wartości metody nadania:

  • parcel_locker - nadaj w paczkomacie InPost,
  • dispatch_order - zleć odbiór/zamów kuriera,
  • pop - nadaj w Punkcie Obsługi Przesyłek,
  • any_point - nadaj w dowolnym automacie Paczkomacie lub PaczkoPunkcie InPost.

Przykładowy fragment requestu:

curl -X POST \
  'https://api.allegro.pl/shipment-management/shipments/create-commands' \
  -H 'Authorization: Bearer {token}'  \
  -H 'Accept: application/vnd.allegro.public.v1+json'
  -H 'Content-type: application/vnd.allegro.public.v1+json'
…
  "additionalProperties": {
            "inpost#sendingMethod": "parcel_locker"
    },
…

W odpowiedzi dla GET /shipment-management/delivery-services, w polu "additionalProperties", dla metod dostawy z "carrierId": "INPOST", zwrócimy klucz inpost#sendingMethod, który oznacza możliwość skorzystania z metody nadania.

Aby utworzyć nową paczkę, skorzystaj z POST /shipment-management/shipments/create-commands. W polu "commandId" możesz:

  • we własnym zakresie automatycznie wygenerować i przekazać numer UUID. Pamiętaj, aby dla każdej nowej przesyłki, którą tworzysz, użyć nowego numeru UUID,
  • nie przekazywać nam numeru UUID i w tej sytuacji wygenerujemy go za Ciebie i zwrócimy w odpowiedzi na żądanie, w polu "commandId".

Przykładowy request:

curl -X POST \
  'https://api.allegro.pl/shipment-management/shipments/create-commands' \
  -H 'Authorization: Bearer {token}'  \
  -H 'Accept: application/vnd.allegro.public.v1+json'
  -H 'Content-type: application/vnd.allegro.public.v1+json'
       {
   "commandId":"14e142cf-e8e0-48cc-bcf6-399b5fd90b32",    // niewymagane, unikalny identyfikator UUID; jeżeli go nie przekażesz, wygenerujemy go automatycznie
   "input":{
      "deliveryMethodId":"c3066682-97a3-42fe-9eb5-3beeccab840c",    // identyfikator usługi dostawy; pobierzesz go za pomocą GET /shipment-management/delivery-services
      "credentialsId":"c9e6f40a-3d25-48fc-838c-055ceb1c5bc0",    // identyfikator umowy własnej; wymagany, jeżeli nadajesz przesyłkę na umowie własnej, 
      "sender":{    // wymagane, dane nadawcy
         "name":"Jan Kowalski",    // dane osobowe nadawcy
         "company":"Allegro.pl sp. z o.o.",    // nazwa firmy
         "street":"Główna 30",    // ulica oraz numer budynku
         "postalCode":"10-200",    // kod pocztowy
         "city":"Warszawa",    // miasto
         "countryCode":"PL",    // kod kraju zgodny ze standardem ISO 3166-1 alpha-2
         "email":"email@mail.com",    // adres e-mail
         "phone":"500600700",    // numer telefonu nadawcy
         "point":"A1234567"    // wymagane, jeśli adresem nadawczym jest punkt odbioru
      },
      "receiver":{    // wymagane, dane odbiorcy
         "name":"Jan Kowalski",    // dane osobowe odbiorcy
         "company":"Allegro.pl sp. z o.o.",    // nazwa firmy
         "street":"Główna 30",    // ulica oraz numer budynku
         "postalCode":"10-200",    // kod pocztowy
         "city":"Warszawa",    // miasto
         "countryCode":"PL",    // kod kraju zgodny ze standardem ISO 3166-1 alpha-2
         "email":"email@mail.com",    // wymagany, adres e-mail. Musisz  przekazać prawidłowy maskowany adres e-mail wygenerowany przez Allegro, np. hamu7udk3p+17454c1b6@allegromail.pl
         "phone":"500600700",    // numer telefonu
         "point":"A1234567"    // wymagane, jeśli adresem odbiorczym jest punkt odbioru. ID punktu odbioru, pobierzesz z danych zamówienia za pomocą GET /order/checkout-forms
      },
      "pickup":{    // niewymagane, dane miejsca przekazania przesyłki
         "name":"Jan Kowalski",    // dane osobowe nadawcy
         "company":"Allegro.pl sp. z o.o.",    // nazwa firmy
         "street":"Główna 30",    // ulica oraz numer budynku
         "postalCode":"10-200",    // kod pocztowy
         "city":"Warszawa",    // miasto
         "countryCode":"PL",    // kod kraju zgodny ze standardem ISO 3166-1 alpha-2
         "email":"email@mail.com",    // adres e-mail
         "phone":"500600700",    // numer telefonu nadawcy
         "point":"A1234567"    // wymagane, jeśli adresem nadawczym jest punkt odbioru
      },
      "referenceNumber":"abcd1234",    // zewnętrzny ID / sygnatura, który nadaje sprzedający, dzięki któremu rozpozna przesyłkę w swoim systemie (część przewoźników nie korzysta z tego pola, w związku z czym informacja nie będzie widoczna na etykiecie)
      "packages":[   // wymagane, informacje o paczkach. Maksymalna liczba przesyłek dla przewoźników to: 10. Maksymalna liczba paczek wchodzących w skład jednej przesyłki (dotyczy tylko DPD i WE|DO) to: 10.
         {
            "type":"OTHER",    // wymagane, typ przesyłki; dostępne wartości: PACKAGE (paczka), DOX (list), PALLET (przesyłka paletowa), OTHER (inna)
            "length":{    // długość paczki
               "value":12,
               "unit":"CENTIMETER"
            },
            "width":{    // szerokość paczki
               "value":12,
               "unit":"CENTIMETER"
            },
            "height":{    // wysokość paczki
               "value":12,
               "unit":"CENTIMETER"
            },
            "weight":{    // waga paczki
               "value":12.45,
               "unit":"KILOGRAMS"
            },
            "textOnLabel": "towary"    // opis na etykiecie paczki
         }
      ],
      "insurance":{    // dodatkowa ochrona przesyłki
         "amount":"23.47",    // suma dodatkowej ochrony przesyłki
         "currency":"PLN"    // waluta kwoty dodatkowej ochrony przesyłki
      },
      "cashOnDelivery":{    // płatność przy odbiorze
         "amount":"2.50",    // suma płatności przy odbiorze
         "currency":"PLN",    // waluta
         "ownerName":"Jan Kowalski",    // dane adresata płatności; wymagane jeśli dla wybranej usługi dostawy wymagany numer IBAN ("forceRequireIban": true)
         "iban":"PL48109024022441789739167589"    // numer konta IBAN wskazany w przez sprzedawcę przy tworzeniu przesyłki; musi być taki sam, jak w ustawieniach wypłat Allegro; dotyczy tylko przesyłek na terenie PL; wymagany jeśli dla wybranej usługi dostawy wymagany numer IBAN ("forceRequireIban": true)
      },
      "labelFormat":"PDF",    // format etykiety (nie można go zmienić w późniejszym etapie); dostępne wartości: PDF, ZPL
      "additionalServices":[   // usługi dodatkowe. Dostępne są tylko te możliwości, które otrzymałeś w odpowiedzi dla GET /shipment-management/delivery-services dla danej usługi dostawy
         "ADDITIONAL_HANDLING"
      ],
"additionalProperties": {}
   }
}
{
  "commandId": "14e142cf-e8e0-48cc-bcf6-399b5fd90b32",
  "input": {
    "deliveryMethodId": "c3066682-97a3-42fe-9eb5-3beeccab840c",
    "credentialsId": "c9e6f40a-3d25-48fc-838c-055ceb1c5bc0",
    "sender": {
      "name": "Jan Kowalski",
      "company": "Allegro.pl sp. z o.o.",
      "street": "Główna 30",
      "postalCode": "10-200",
      "city": "Warszawa",
      "state": "AL",
      "countryCode": "PL",
      "email": "email@mail.com",
      "phone": "500600700",
      "point": "A1234567"
    },
    "receiver": {
      "name": "Jan Kowalski",
      "company": "Allegro.pl sp. z o.o.",
      "street": "Główna 30",
      "postalCode": "10-200",
      "city": "Warszawa",
      "state": "AL",
      "countryCode": "PL",
      "email": "email@mail.com",
      "phone": "500600700",
      "point": "A1234567"
    },
    "pickup": {
      "name": "Jan Kowalski",
      "company": "Allegro.pl sp. z o.o.",
      "street": "Główna 30",
      "postalCode": "10-200",
      "city": "Warszawa",
      "state": "AL",
      "countryCode": "PL",
      "email": "email@mail.com",
      "phone": "500600700",
      "point": "A1234567"
    },
    "referenceNumber": "abcd1234",
    "packages": [
      {
        "type": "DOX",
        "length": {
          "value": "12",
          "unit": "CENTIMETER"
        },
        "width": {
          "value": "12",
          "unit": "CENTIMETER"
        },
        "height": {
          "value": "12",
          "unit": "CENTIMETER"
        },
        "weight": {
          "value": "12.45",
          "unit": "KILOGRAMS"
        },
        "textOnLabel": "towary"
      }
    ],
    "insurance": {
      "amount": "23.47",
      "currency": "PLN"
    },
    "cashOnDelivery": {
      "amount": "2.50",
      "currency": "PLN",
      "ownerName": "Jan Kowalski",
      "iban": "PL48109024022441789739167589"
    },
    "labelFormat": "PDF",
    "additionalServices": [
      "ADDITIONAL_HANDLING"
    ]
  }
}
…
}

Informacje o identyfikatorach punktów w polach pickup.point i receiver.point.

Jeżeli używasz powyższych pól, możesz je wypełnić wartością pobraną:

  • ze szczegółów zamówienia, za pomocą GET /order/checkout-forms/{id}, w polu: delivery.pickupPoint.id,
  • z API odpowiedniego przewoźnika. Model każdego z nich jest różny, dlatego odwołaj się bezpośrednio do dokumentacji API przewoźników.

Przykładowe wartości poszczególnych przewoźników:

  • DHL (API): "1020384"
  • DPD (API): "PL11033"
  • Fedex (API): "331535"
  • InPost (API): "ADA01N"
  • Poczta Polska (API): "116744"
  • ORLEN Paczka (API): "183000" lub "WS-183000-01-93"
  • UPS (API): "U00032786"

Jak sprawdzić status utworzenia paczki

Za pomocą GET /shipment-management/shipments/create-commands/{commandId} sprawdzisz status utworzenia paczki, a także informacje o błędach, jeśli wystąpiły. Jeśli zadanie nie zostało jeszcze ukończone, w odpowiedzi zwrócimy nagłówek Retry-After, w którym znajdziesz informację, za ile sekund możesz odpytać o status komendy.

Przykładowy request:

  curl -X GET \ 
  'https://api.allegro.pl/shipment-management/shipments/create-commands/14d3b9c4-ca3b-4e37-89c0-6f6cac24a02e' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json'

Przykładowy response:

{
  "commandId": "14e142cf-e8e0-48cc-bcf6-399b5fd90b32",    // numer UUID żądania
  "status": "IN_PROGRESS",    // status zadania, dostępne wartości to: IN_PROGRESS (zadanie w trakcie przetwarzania), SUCCESS (zadanie wykonane prawidłowo), ERROR (wystąpił błąd)
  "errors": [],    // informacje o błędach
  "shipmentId": "ba88f0fb-acf3-438a-877e-580da50c0874"    // ID paczki
}

Przykładowy response, gdy nie przekażesz numeru budynku:

{
  "commandId": "14e142cf-e8e0-48cc-bcf6-399b5fd90b32",
  "status": "ERROR",
  "errors": [
        {
            "code": "VALIDATION_ERROR",
            "message": "Brak numeru budynku",
            "details": null,
            "path": "receiver.street",
            "userMessage": null
        }
    ],
  "shipmentId": null
}

Przykładowy response, gdy przekażesz błędny numer telefonu:

{
  "commandId": "ga77f0fb-acf3-438a-877e-580da50c0865",
  "status": "ERROR",
  "errors": [
        {
            "code": "VALIDATION_ERROR",
            "message": "Niepoprawny numer telefonu (może zawierać od 9 do 14 cyfr)",
            "details": null,
            "path": "receiver.phone",
            "userMessage": null
        }
    ],
  "shipmentId": null
}

Jak pobrać szczegółowe informacje o paczce

Aby pobrać szczegółowe dane paczki, użyj GET /shipment-management/shipments/{shipmentId}. Jako shipmentId przekaż identyfikator paczki, który otrzymasz w odpowiedzi dla GET /shipment-management/shipments/create-commands/{commandId}.

Przykładowy request:

curl -X GET \
  'https://api.allegro.pl/shipment-management/shipments/ba88f0fb-acf3-438a-877e-580da50c0874' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json'
{
  "id": "ba88f0fb-acf3-438a-877e-580da50c0874",    // ID paczki
  "deliveryMethodId": "c3066682-97a3-42fe-9eb5-3beeccab840c",    // ID usługi dostawy
  "credentialsId": "c9e6f40a-3d25-48fc-838c-055ceb1c5bc0",    // ID metody własnej
  "sender": {
    "name": "Jan Kowalski",
    "company": "Allegro.pl sp. z o.o.",
    "street": "Główna 30",
    "postalCode": "10-200",
    "city": "Warszawa",
    "state": "AL",
    "countryCode": "PL",
    "email": "email@mail.com",
    "phone": "500600700",
    "point": "A1234567"
  },
  "receiver": {    // dane odbiorcy
    "name": "Jan Kowalski",
    "company": "Allegro.pl sp. z o.o.",
    "street": "Główna 30",
    "postalCode": "10-200",
    "city": "Warszawa",
    "state": "AL",
    "countryCode": "PL",
    "email": "email@mail.com",
    "phone": "500600700",
    "point": "A1234567"
  },
  "pickup": {    // dane nadawcy
    "name": "Jan Kowalski",
    "company": "Allegro.pl sp. z o.o.",
    "street": "Główna 30",
    "postalCode": "10-200",
    "city": "Warszawa",
    "state": "AL",
    "countryCode": "PL",
    "email": "email@mail.com",
    "phone": "500600700",
    "point": "A1234567"
  },
  "referenceNumber": "abcd1234",    // zewnętrzny ID / sygnatura, który nadaje sprzedający, dzięki któremu rozpozna przesyłkę w swoim systemie
  "packages": [   // informacje o paczce
    {
      "waybill": "string",    // numer listu przewozowego
      "type": "DOX",    // typ przesyłki
      "length": {    // długość paczki
        "value": "12",
        "unit": "CENTIMETER"
      },
      "width": {    // szerokość paczki
        "value": "12",
        "unit": "CENTIMETER"
      },
      "height": {    // wysokość paczki
        "value": "12",
        "unit": "CENTIMETER"
      },
      "weight": {    // waga paczki
        "value": "12.45",
        "unit": "KILOGRAMS"
      },
      "textOnLabel": "towary"
    }
  ],
  "insurance": {    // dodatkowa ochrona przesyłki
    "amount": "23.47",
    "currency": "PLN"
  },
  "cashOnDelivery": {    // płatność przy odbiorze
    "amount": "2.50",
    "currency": "PLN",
    "ownerName": "Jan Kowalski",
    "iban": "PL48109024022441789739167589"
  },
  "createdDate": "string",    // data utworzenia
  "canceledDate": "string",    // data anulowania
  "carrier": "string",    // ID przewoźnika
  "labelFormat": "ZPL",    // format etykiety
  "additionalServices": [   // informacje o ewentualnych usługach dodatkowych
    "ADDITIONAL_HANDLING"
  ],
  "additionalProperties": {    // dodatkowe informacje o przesyłce
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}
}

Jak anulować paczkę

Jeżeli utworzono paczkę, ale np. nieprawidłowo wypełniono niektóre dane, możesz ją anulować za pomocą POST /shipment-management/shipments/cancel-commands. W polu "shipmentId" przekaż identyfikator paczki, którą chcesz usunąć.

Nie możesz anulować:

  • paczek ze wskazaną metodą dostawy z "carrierId": "ALLEGRO",
  • pozostałych paczek odebranych przez kuriera lub nadanych w paczkomacie."

Przykładowy request:

curl -X POST \
  'https://api.allegro.pl/shipment-management/shipments/cancel-commands' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d '{
  "commandId": "14e142cf-e8e0-48cc-bcf6-399b5fd90b32",
  "input": {
    "shipmentId": "ba88f0fb-acf3-438a-877e-580da50c0874"
  }
}'

Jeżeli nie przekażesz numeru UUID w polu "commandId", wygenerujemy go za Ciebie i zwrócimy w odpowiedzi na żądanie.

Przykładowy response:

{
  "commandId": "14e142cf-e8e0-48cc-bcf6-399b5fd90b32",
  "input": {
    "shipmentId": "ba88f0fb-acf3-438a-877e-580da50c0874"
  }
}

Jak sprawdzić status anulowania paczki

Za pomocą GET /shipment-management/shipments/cancel-commands/{commandId} sprawdzisz status anulowania paczki. Jeśli zadanie nie zostało jeszcze ukończone, w odpowiedzi zwrócimy nagłówek Retry-After, w którym znajdziesz informację, za ile sekund możesz sprawdzić status komendy.

Przykładowy request:

curl -X GET  \
  'https://api.allegro.pl/shipment-management/shipments/cancel-commands/14e142cf-e8e0-48cc-bcf6-399b5fd90b32' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json'

Przykładowy response:

{
  "commandId": "14e142cf-e8e0-48cc-bcf6-399b5fd90b32",    // numer UUID żądania
  "status": "SUCCESS",    // status zadania, dostępne wartości to:  IN_PROGRESS (zadanie w trakcie przetwarzania), SUCCESS (nie gwarantuje, że wysyłka paczki została anulowana, np. nie możesz anulować paczki odebranej przez kuriera lub nadanej w paczkomacie), ERROR (wystąpił błąd)
  "errors": [],
  "shipmentId": "14e142cf-e8e0-48cc-bcf6-399b5fd90b32"    // ID paczki
}

Jak sprawdzić proponowaną datę odbioru paczek przez kuriera

Aby otrzymać propozycje dat i godzin odbioru paczek przez kuriera, skorzystaj z POST /shipment-management/pickup-proposals. W żądaniu przekaż:

  • shipmentIds - wymagany, ID paczki, który zwróciliśmy w odpowiedzi dla GET /shipment-management/shipments/create-commands/{commandId}. W sekcji tej możesz przekazać maksymalnie 100 identyfikatorów paczek. Dla każdej paczki zwrócimy osobny zakres dat;
  • readyDate - niewymagany, data, kiedy paczki będą gotowe do odbioru. Datę przekaż w formacie YYYY-MM-DD, np. 2023-09-20.
  • address - wkrótce oznaczymy jako wymagane, adres odbioru paczek przez kuriera

W odpowiedzi, w tablicy proposals, otrzymasz zbiór paczek z proponowanym:

  • identyfikatorem, który zwrócimy w polu "proposalItems.id",
  • terminem odbioru, który zwrócimy w polu "proposalItems.name".

Termin odbioru, który zwrócimy Tobie w polu "proposalItems.name" może przyjąć formę daty, jak również tekstu z terminem odbioru, np. dla przesyłki Inpost - „Następny dzień roboczy".

Wybrany identyfikator przekażesz w kolejnym kroku, w polu "pickupDateProposalId", gdy będziesz zamawiać odbiór paczek przez kuriera, za pomocą POST /shipment-management/pickups/create-commands.

Kurier Pocztex nie obsługuje odbiorów przesyłek, możesz jedynie nadać paczkę w punkcie. W tym przypadku w odpowiedzi zwrócimy pustą tablicę.

Dla przewoźnika InPost nie zwrócimy proponowanych dat odbioru. W takim przypadku, gdy zamawiasz kuriera, w polu "pickupDateProposalId" przekaż wartość "ANY".

Przykładowy request:

curl -X POST \
  'https://api.allegro.pl/shipment-management/pickup-proposals' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d '{
  "shipmentIds": [    // tablica z identyfikatorami paczek do odbioru przez kuriera
    "ba88f0fb-acf3-438a-877e-580da50c0874"
  ],
  "readyDate": "2023-09-15"    // data informująca o tym, kiedy paczki będą gotowe do odbioru
  "address": {    // adres odbioru paczek przez kuriera
    "name": "Jan Kowalski",
    "company": "Allegro.pl sp. z o.o.",
    "street": "Główna 30",
    "postalCode": "10-200",
    "city": "Warszawa",
    "state": null,
    "countryCode": "PL",
    "email": "email@mail.com",
    "phone": "500600700",
    "point": "A1234567"
  }
}'

Przykładowy response:

[
  {
    "proposals": [    // zbiór paczek
      {
        "shipmentId": "ba88f0fb-acf3-438a-877e-580da50c0874",    // ID paczki
        "proposalItems": [    // proponowane daty odbioru paczki przez kuriera
          {
            "id": "2023071210001300",    // ID proponowanego czasu odbioru paczki
            "name": "2023-07-12 10:00-13:00",    // szczegóły dotyczące czasu odbioru paczki
            "description": "Odbiór A"    // opis dotyczący odbioru paczki
          }
        ]
        "address": {    // adres odbioru paczek przez kuriera
          "name": "Jan Kowalski",
          "company": "Allegro.pl sp. z o.o.",
          "street": "Główna 30",
          "postalCode": "10-200",
          "city": "Warszawa",
          "state": null,
          "countryCode": "PL",
          "email": "email@mail.com",
          "phone": "500600700",
          "point": "A1234567"
      }
    ]

Jak zamówić odbiór paczek przez kuriera

Skorzystaj z POST /shipment-management/pickups/create-commands, aby zamówić odbiór przesyłek przez kuriera. W żądaniu przekaż:

W polu "commandId" możesz:

  • we własnym zakresie automatycznie wygenerować i przekazać numer UUID. Pamiętaj, aby dla każdego żądania dotyczącego nowego odbioru przesyłek przez kuriera, który tworzysz - użyć nowego numeru UUID,
  • nie przekazywać nam numeru UUID i w tej sytuacji wygenerujemy go za Ciebie i zwrócimy w odpowiedzi na żądanie, w polu "commandId".

Przykładowy request:

curl -X POST \
  'https://api.allegro.pl/shipment-management/pickups/create-commands' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d '{
  "commandId": "14e142cf-e8e0-48cc-bcf6-399b5fd90b32",    // wymagane, unikalny identyfikator UUID; jeżeli go nie przekażesz, wygenerujemy go automatycznie
  "input": {
    "shipmentIds": [
      "ba88f0fb-acf3-438a-877e-580da50c0874"    // ID paczki
    ],
    "pickupDateProposalId": "2023071210001300",    // ID proponowanego czasu odbioru paczki (W przypadku przesyłki Inpost, w polu pickupDateProposalId przekaż wartość „ANY".
    "address": {    // adres odbioru paczek przez kuriera
      "name": "Jan Kowalski",
      "company": "Allegro.pl sp. z o.o.",
      "street": "Główna 30",
      "postalCode": "10-200",
      "city": "Warszawa",
      "state": null,
      "countryCode": "PL",
      "email": "email@mail.com",
      "phone": "500600700",
      "point": "A1234567"
  }
  }
}'

W przypadku przesyłki Inpost, w polu pickupDateProposalId przekaż wartość „ANY".

W nagłówku Retry-After, zwrócimy informację o tym, za ile sekund możesz sprawdzić status za pomocą GET /shipment-management/pickups/create-commands/{commandId}.

Przykładowy response:

{
  "commandId": "14e142cf-e8e0-48cc-bcf6-399b5fd90b32",
  "input": {
    "shipmentIds": [
      "ba88f0fb-acf3-438a-877e-580da50c0874"
    ],
    "pickupDateProposalId": "2023071210001300",
    "address": {   
      "name": "Jan Kowalski",
      "company": "Allegro.pl sp. z o.o.",
      "street": "Główna 30",
      "postalCode": "10-200",
      "city": "Warszawa",
      "state": null,
      "countryCode": "PL",
      "email": "email@mail.com",
      "phone": "500600700",
      "point": "A1234567"
    }
  }
}

Jak sprawdzić status zamówienia odbioru paczek

Za pomocą GET /shipment-management/pickups/create-commands/{commandId} sprawdź status zamówienia odbioru paczek.

Jeśli zadanie nie zostało jeszcze ukończone, w odpowiedzi zwrócimy nagłówek Retry-After, w którym znajdziesz informację, za ile sekund możesz sprawdzić status komendy.

Przykładowy request:

 curl -X GET \
  'https://api.allegro.pl/shipment-management/pickups/create-commands/14e142cf-e8e0-48cc-bcf6-399b5fd90b32' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json'

Przykładowy response:

{
    "id": "14e142cf-e8e0-48cc-bcf6-399b5fd90b32",    // numer UUID żądania
    "status": "SUCCESS",    // status zadania, dostępne wartości to: IN_PROGRESS (zadanie w trakcie przetwarzania), SUCCESS (zadanie wykonane prawidłowo), ERROR (wystąpił błąd)
    "errors": []    // informacje o błędach
  }

Jak utworzyć etykietę na paczkę

Za pomocą POST /shipment-management/label utworzysz etykietę, którą następnie sprzedawca umieści na paczce. W żądaniu, dla parametrów:

  • shipmentId - wymagane, przekaż identyfikator paczki.
  • pageSize - niewymagane, format strony. Przekaż wartość "A4" lub "A6". Dotyczy tylko plików w formacie PDF,
  • cutline - niewymagane, linie cięcia. Dotyczy tylko plików PDF w formacie A4.

W odpowiedzi otrzymasz plik PDF lub ZPL (w zależności od wybranego formatu na etapie tworzenia paczki), który musisz zapisać na dysku.

Przykładowy request:

curl -X 'POST' \
  'https://api.allegro.pl/shipment-management/label' \
  -H 'accept: application/octet-stream' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d '{
  "shipmentIds": [
    "ba88f0fb-acf3-438a-877e-580da50c0874"
  ],
  "pageSize": "A4",
  "cutLine": true
}'

Przykładowy response:

  Status 200 OK

Jak pobrać protokół nadania przesyłek

Za pomocą POST /shipment-management/protocol pobierzesz protokoły nadania przesyłek. W żądaniu, w polu "shipmentIds", przekaż identyfikatory paczek.

W odpowiedzi otrzymasz plik w formacie PDF, który musisz zapisać na dysku. Dokument wygenerujemy w dwóch kopiach - po jednej dla sprzedawcy i kuriera.

Przykładowy request:

curl -X 'POST' \
  'https://api.allegro.pl/shipment-management/protocol' \
  -H 'accept: application/octet-stream' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d '{
  "shipmentIds": [
    "ba88f0fb-acf3-438a-877e-580da50c0874"
  ]
}'

Przykładowy response:

  Status 200 OK

Przewoźnicy, którzy nie udostępniają protokołów nadawczych to: Allegro One, FedEx, InPost, UPS oraz Poczta Polska. Dla tych przesyłek zwrócimy status 204 no content.

Jak pobrać listę punktów Allegro

Za pomocą GET /order/carriers/ALLEGRO/points pobierzesz listę punktów Allegro, w których klienci mogą nadawać i odbierać przesyłki. Skorzystaj z zasobu, gdy np. musisz zmienić punkt odbioru przesyłki. Zasób zwróci listę wszystkich punktów, dlatego aby zmniejszyć rozmiar odpowiedzi możesz użyć nagłówka Accept-Encoding: gzip. Dzięki temu odpowiedź skompresujemy przy pomocy algorytmu gzip.

Jeśli chcesz w odpowiedzi otrzymać tylko te punkty, które obsługuje dany przewoźnik, dodaj do żądania parametr "carriers" i wskaż odpowiednią wartość (listę dostępnych wartości znajdziesz w dokumentacji).

Aby uniknąć niepotrzebnych interakcji, listę punktów możesz także filtrować za pomocą parametru w nagłówku If-Modified-Since (data ostatniej modyfikacji danych).

  • jeśli wprowadziliśmy zmiany po dacie wskazanej w żądaniu - otrzymasz w odpowiedzi pełen zestaw danych (status: 200 OK);
  • jeśli nie zmieniliśmy danych - otrzymasz pustą odpowiedź (status: 304 Not Modified).

Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/order/carriers/ALLEGRO/points' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'If-Modified-Since: Wed, 07 Apr 2021 08:00:30 GMT' 
{
    "points": [
        {
            "id": "A001536",    // identyfikator punktu, który przekażesz w Wysyłam z Allegro
            "name": "POK2",    // nazwa punktu
            "type": "PUDO",    // typ punktu, dostępne wartości to PUDO (Pick Up Drop Of) lub APM (Automated Parcel Machine)
            "services": [    // usługi dostępne dla punktu
                {
                    "type": "PICKUP"    // odbiór paczek
                },
                {
                    "type": "DROPOFF"    // nadania paczek
                }
            ],
            "restrictions": [    // ograniczenia, które mogą mieć wpływ na wybór punktu. Aktualnie dostępna jest jedna wartość - OVERLOADED (punkt przepełniony).
    {
        "type": "OVERLOADED"
    }
],            
            "description": "Sklep z książkami dla dzieci",    // opis punktu (jeśli go zawiera)
            "payments": [    // metody płatności dostępne w punkcie
                {
                    "method": "CASH"    // płatność gotówką                        
                },
                {
                    "method": "CARD"    // płatność kartą
                }
            ],
            "address": {    // dane adresowe punktu
                "postCode": "01-360",
                "city": "Warszawa",
                "street": "Testowa 1",
                "countryCode": "PL",
                "coordinates": {
                    "lat": 52.2288804171526,
                    "lon": 20.9118756802585
                }
            },
            "opening": [    // informacje na temat dni i godzin otwarcia 
                {
                    "dayOfWeek": "MONDAY",    // dzień
                    "from": "06:00",    // godzina otwarcia
                    "to": "12:00"    // godzina zamknięcia
                },
                {
                    "dayOfWeek": "WEDNESDAY",
                    "from": "06:00",
                    "to": "20:00"
                },
                {
                    "dayOfWeek": "THURSDAY",
                    "from": "00:00",
                    "to": "24:00"
                },
                {
                    "dayOfWeek": "FRIDAY",
                    "from": "00:00",
                    "to": "24:00"
                },
                {
                    "dayOfWeek": "SATURDAY",
                    "from": "09:00",
                    "to": "15:00"
                },
                {
                    "dayOfWeek": "SUNDAY",
                    "from": "09:00",
                    "to": "15:00"
                }
            ]
        },
…
}

Jak pobrać historię statusów przesyłek

Za pomocą GET /order/carriers/{carrierId}/tracking?waybill={waybill} pobierzesz historię statusów wskazanych przesyłek. Jako {carrierId} wskaż ID wybranego przewoźnika (dostępne wartości sprawdzisz w odpowiedzi dla GET /shipment-management/delivery-services), a jako waybill przekaż numer przesyłki, który otrzymasz w odpowiedzi dla GET /shipment-management/shipments/{shipmentId} w polu "packages.waybill".

Możesz przekazać więcej niż jeden numer, maksymalnie 20, np. GET /order/carriers/{carrierId}/tracking?waybill=waybill1&waybill=waybill2&waybill=waybill3.

Możliwe statusy przesyłek to:

  • PENDING - przesyłka została przygotowana przez nadawcę, oczekuje na nadanie;
  • IN_TRANSIT - w drodze. Status obejmuje zdarzenia takie jak:
    • nadanie przesyłki w punkcie,
    • odebranie jej przez kuriera,
    • przyjęcie na sortownie,
    • przekierowanie do innego punktu.
  • RELEASED_FOR_DELIVERY - w trakcie doręczenia przez kuriera (na adres odbiorcy lub do punktu odbioru);
  • AVAILABLE_FOR_PICKUP - oczekuje na odbiór w punkcie;
  • NOTICE_LEFT - kurier wystawił awizo, przesyłka będzie do odbioru pod adresem podanym na awizo;
  • ISSUE - wystąpił problem z przesyłką. Status obejmuje zdarzenia takie jak:
    • odmowa przyjęcia przesyłki,
    • zagubienie przesyłki.
  • DELIVERED - przesyłka została doręczona do odbiorcy lub odebrana z punktu odbioru;
  • RETURNED - przesyłka została zwrócona do nadawcy.

Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/order/carriers/{carrierId}/tracking?waybill=ALE0000000E5D200' \
  -H 'Authorization: Bearer {token}'  \
  -H 'Accept: application/vnd.allegro.public.v1+json' 
{
  "carrierId": "ALLEGRO",    // ID przewoźnika
  "waybills": [    // informacje o statusach dla poszczególnych przesyłek 
    {
      "waybill": "ALE0000000E5D200",    // numer listu przewozowego
      "trackingDetails": {    // informacje o statusach przesyłki. Przyjmuje wartość null, w przypadku, gdy waybill nie został rozpoznany w systemie (np. z powodu braku zarejestrowanego jakiegokolwiek statusu albo dotyczy paczki sprzed ponad 60 dni)
        "statuses": [    // lista statusów
          {
            "occurredAt": "2021-01-22T11:30:21.092Z",    // czas wystąpienia zdarzenia
            "code": "PENDING"    // status przesyłki
          }, {
            "occurredAt": "2021-01-22T11:30:34.710Z",
            "code": "IN_TRANSIT"
          }, {
            "occurredAt": "2021-01-24T08:33:27.219Z",
            "code": "ISSUE",
            "description": "Possible delay in delivery"    // opcjonalny opis dla danego statusu
          }, {
            "occurredAt": "2021-01-24T16:11:31.829Z",
            "code": "AVAILABLE_FOR_PICKUP"
          }, {
            "occurredAt": "2021-01-25T11:35:01.859Z",
            "code": "DELIVERED"
          }
        ],
        "createdAt": "2021-01-22T11:30:22.163Z",    // czas rozpoczęcia rejestrowania trackingu przesyłki
        "updatedAt": "2021-01-25T11:36:02.217Z"    // czas zarejestrowania ostatniej zmiany w trackingu przesyłki
      }
    }
  ]
}

FAQ

Upewnij się, że usługa dostawy, którą wybrałeś jest prawidłowa dla metody dostawy, którą wybrał kupujący. Szczegółowy podział usług na metody dostawy znajdziesz na naszej stronie. Miej także na uwadze, że ID usługi dostawy posiada różną wartość w zależności od konta.

W tym polu wymagamy wartości, która składa się z dwóch osobnych wyrazów. Upewnij się, że przekazujesz ją właśnie w taki sposób.

Taki komunikat otrzymasz, jeśli dla przesyłek Allegro One i Allegro One Kurier w polu "label.sender" przekażesz inne dane niż w polu "pickup". W takim przypadku w polu "label.sender" przekaż wartość null.

Taką usługę wspiera tylko przewoźnik DPD. W pozostałych przypadkach każdą przesyłkę musisz utworzyć za pomocą osobnego, pojedynczego żądania.

Każdy operator logistyczny, który zapewnia usługi dostawy w ramach Wysyłam z Allegro posiada własne limity znaków, dlatego też nie możemy ich zamieścić w dokumentacji. Przygotowaliśmy tabelę, gdzie znajdziesz dokładną specyfikację pól wraz z limitami na GUI. Pamiętaj, że w niektórych przypadkach możemy akceptować dłuższe ciągi znaków, a w wyjątkowych sytuacjach (gdy są dodatkowe ograniczenia po stronie kuriera) krótsze - wtedy zwrócimy Tobie odpowiedni komunikat błędu.

W ramach Allegro One usługi kurierskie świadczy DPD i UPS. Musisz sprawdzić, czy dany punkt obsługuje wybranego kuriera. Skorzystaj z GET /order/carriers/ALLEGRO/points - w polu "carriers" znajdziesz listę obsługiwanych przewoźników.

Sprawdź kwotę dodatkowej ochrony przesyłki (pole "insurance.amount") - podana kwota musi być co najmniej równa kwocie pobrania (pole "cashOnDelivery.amount").

Dla wybranej metody dostawy środki w ramach pobrania (COD) otrzymasz na swoje subkonto w Allegro - Środki i historia operacji. Skorzystaj z GET /shipment-management/delivery-services by sprawdzić, czy dana metoda dostawy wymaga IBAN - pole "cashOnDelivery.forceRequireIban".

Skorzystaj z GET /shipment-management/delivery-services i sprawdź, w jakiej walucie należy przekazać wartość dodatkowej ochrony przesyłki - pole "insurance.currency".

Sprawdź na stronie, czy kod pocztowy nadawcy obsługiwany jest w ramach sieci nadawczej Allegro One Kurier.

Lista zasobów

Pełną dokumentację zasobów w postaci pliku swagger.yaml znajdziesz tu.

Lista zasobów podstawowych opisanych w poradniku:

Czy ten artykuł był dla Ciebie przydatny?

Allegro

Dostosuj ustawienia wyświetlania

ustawienia dotyczą tylko tej przeglądarki