Allegro REST API

gdzie?

Polska | polski | PLN
  • Informacje podstawowe
  • Główne procesy
  • Uwierzytelnianie i autoryzacja
  • Wzorzec Command
  • Glosariusz
  • Lista metod
  • Pierwsze kroki
  • Wystawianie oferty z produktem
  • Serwisy zagraniczne Allegro
  • Zarządzanie ofertami
  • Oferty wielowariantowe
  • Pasuje do
  • Zarządzanie zgłoszeniami ofert do kampanii
  • Rabaty i promocje
  • Zamówienia
  • Wysyłam z Allegro
  • One Fulfillment by Allegro
  • Dyskusje
  • Konto i dane użytkownika
  • Centrum wiadomości
  • Sprawdzanie opłat
  • Wystawianie ogłoszeń
  • Publiczne oferty
FAQ
  • Aktualności
  • Changelog
Dokumentacja
Regulamin
Kontakt
  • Moje aplikacje
  • Moje aplikacje (sandbox)
  • Newsletter
  1. Allegro REST API
  2. Wysyłam z Allegro
Jak pobrać listę usług dostawy
Jak utworzyć nową paczkę
Jak sprawdzić status utworzenia paczki
Jak pobrać szczegółowe informacje o paczce
Jak anulować paczkę
Jak sprawdzić status anulowania paczki
Jak sprawdzić proponowaną datę odbioru paczek przez kuriera
Jak zamówić odbiór paczek przez kuriera
Jak sprawdzić status zamówienia odbioru paczek
Jak utworzyć etykietę na paczkę
Jak pobrać protokół nadania przesyłek
Jak pobrać listę punktów Allegro
Jak pobrać historię statusów przesyłek
Lista zasobów

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 przez przewoźników ze wskazanego adresu.

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

  • dodanie domyślnego adresu w Książce adresowej - Wysyłam z Allegro:
    • https://allegro.pl/moje-allegro/sprzedaz/zamowienia/ustawienia - (środowisko produkcyjne),
    • https://allegro.pl.allegrosandbox.pl/moje-allegro/sprzedaz/zamowienia/ustawienia - (środowisko testowe),
  • lub nadając dowolną przesyłkę korzystając z przycisku NADAJ PRZESYŁKĘ na liście Zamówień.

Jak pobrać listę usług dostawy

Skorzystaj z GET /parcel-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,

  • nazwę usługi dostawy,

  • identyfikator przewoźnika,

  • usługi dodatkowe w ramach danej usługi dostawy.

Identyfikator przekaż, gdy będziesz tworzyć nową paczkę.

Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/parcel-management/delivery-services' \
  -H 'Authorization: Bearer {token}'  \
  -H 'Accept: application/vnd.allegro.public.v1+json' 

Przykładowy response:

  {
    "deliveryServices": [
        {
            "id": "c3066682-97a3-42fe-9eb5-3beeccab840c", - ID usługi dostawy
            "service": "DPD",                             - wyróżnik usługi dostawy
            "name": "Allegro Kurier DPD",                 - nazwa usługi dostawy
            "carrierId": "DPD",                           - identyfikator przewoźnika
             "additionalServices": {                      - dostępne usługi dodatkowe w ramach
                                                          danej usługi dostawy
                 "cashOnDelivery": {            
                      "available": true,
                      "expressAvailable": true
                },
                "options": [                              - dodatkowe opcje dostawy
                      {
                    "name": "guarantee0930",              - nazwa opcji dostawy
                    "description": "Delivery up to        - opis opcji dostawy
                    9:30 / 10:30 (depending on location)"
                      }
                ]
              },
              "owner": "ALLEGRO"                          - właściciel umowy z 
                                                          przewoźnikiem, dostępne wartości
                                                          to ALLEGRO lub CLIENT
        }
    ]
  }

Dla umowy Allegro - identyfikatory usług dostawy są jednakowe dla wszystkich sprzedawców i są one na stałe przypisane do metod dostawy, np.

  • metoda dostawy: 0e4c7d59-64b6-4b06-89c3-c1d941506dd0 ("Allegro Kurier UPS") - usługa dostawy: 0e4c7d59-64b6-4b06-89c3-c1d941506dd0 ("Allegro Kurier UPS"),
  • metoda dostawy: 199d2a2a-7c90-4ca7-aaf3-c1d941506dd0 ("Allegro Kurier UPS pobranie") - usługa dostawy: 199d2a2a-7c90-4ca7-aaf3-c1d941506dd0 ("Allegro Kurier UPS pobranie").

Dla umowy własnej - dla każdej z nich tworzymy dedykowane usługi dostawy odpowiadające metodom. Identyfikator każdej usługi (“deliveryServices.id”) otrzymuje konstrukcję: id_metody#id_umowy_wlasnej, np.

  • metoda dostawy: b20ef9e1-faa2-4f25-9032-adbea23e5cb9 ("Allegro Paczkomaty InPost pobranie") - usługa dostawy: b20ef9e1-faa2-4f25-9032-adbea23e5cb9#abcdef-ghij-klmn-opqrs123.

Jak utworzyć nową paczkę

Pamiętaj, że wybrana przez kupującego metoda dostawy ma wpływ na to, jaką usługę dostawy możesz wybrać dla danego zamówienia. Usługa dostawy odpowiada umowom podpisanym przez ciebie lub przez Allegro z firmą przewozową.

Poniższa tabela przedstawia dostępne możliwości, typ umowy (własna lub Allegro) sprawdzisz w polu owner w odpowiedzi dla GET /parcel-management/delivery-services.

Metoda dostawy wybrana przez kupującego
Dozwolona umowa własna (usługa dostawy)
Dozwolona umowa Allegro (usługa dostawy)
Allegro One Box
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
Allegro One Box
Allegro One Box, One Kurier - dostawa dzisiaj
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
Allegro One Box, One Kurier - dostawa dzisiaj
Allegro One Box, One Kurier - dostawa jutro
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
Allegro One Box, One Kurier - dostawa jutro
Allegro One Punkt
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
Allegro One Punkt
Allegro One Punkt, One Kurier
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
Allegro One Punkt, One Kurier
Allegro One Kurier - dostawa dzisiaj
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
Allegro One Kurier - dostawa dzisiaj
Allegro One Kurier - dostawa jutro
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
Allegro One Kurier - dostawa jutro
Allegro Kurier DHL
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
Allegro Kurier DHL
Allegro Kurier DPD
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
Allegro Kurier DPD
Allegro Kurier DPD pobranie
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
Allegro Kurier DPD pobranie
Allegro Odbiór w Punkcie DPD Pickup
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
Allegro Odbiór w Punkcie DPD Pickup
Allegro Odbiór w Punkcie DPD Pickup pobranie
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
Allegro Odbiór w Punkcie DPD Pickup pobranie
Allegro Kurier DPD za granicę
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
Allegro Kurier DPD za granicę
Allegro Kurier UPS
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
Allegro Kurier UPS
Allegro Kurier UPS pobranie
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
Allegro Kurier UPS pobranie
Allegro Odbiór w Punkcie UPS
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
Allegro Odbiór w Punkcie UPS
Allegro Pocztex Kurier 48
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
Allegro Pocztex Kurier 48
Allegro Punkty Poczta, Żabka, Orlen, Ruch
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
Allegro Punkty Poczta, Żabka, Orlen, Ruch
Allegro Przesyłka polecona
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
Allegro Przesyłka polecona
Allegro Pocztex Kurier
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
Allegro Pocztex Kurier
Allegro Odbiór w Punkcie Pocztex
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
Allegro Odbiór w Punkcie Pocztex
Allegro Automat Pocztex
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
Allegro Automat Pocztex
Allegro Kurier24 InPost
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
Allegro Kurier24 InPost*
Allegro Kurier24 InPost pobranie
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
Allegro Kurier24 InPost pobranie*
Allegro miniKurier24 InPost
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
Allegro miniKurier24 InPost*
Allegro miniKurier24 InPost pobranie
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
Allegro miniKurier24 InPost pobranie*
Allegro Paczkomaty InPost
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
Allegro Paczkomaty InPost*
Allegro Paczkomaty InPost pobranie
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
Allegro Paczkomaty InPost pobranie*
wszystkie pozostałe
Dozwolona umowa własna (usługa dostawy) 
dowolna
Dozwolona umowa Allegro (usługa dostawy)  
-

*Umowa Allegro Inpost wymaga dodania w ustawieniach Wysyłam z Allegro umowy własnej i wybrania opcji "Używaj oferty dla sprzedawców Allegro".

Aby utworzyć nową paczkę, skorzystaj z PUT /parcel-management/parcel-create-commands/{commandId}. Jako commandId przekaż numer UUID - wygeneruj go automatycznie we własnym zakresie. Pamiętaj, aby dla każdej nowej przesyłki, którą tworzysz, użyć nowego numeru UUID.

Kliknij, aby zobaczyć request
toggle visibility
curl -X PUT \
'https://api.allegro.pl/parcel-management/parcel-create-commands/14d3b9c4-ca3b-4e37-89c0-6f6cac24a02e' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d 
'{
  "serviceId": "0e4c7d59-64b6-4b06-89c3-c1d941506dd0",- wymagane, ID usługi dostawy, 
                                                    pobierzesz je za pomocą GET /parcels/delivery-services 
  "receiver": {                                   - dane odbiorcy
    "address": {
      "street": "Testowa 172",                    - ulica i numer budynku
      "postCode": "61-132",                       - kod pocztowy
      "city": "Poznań",                           - miasto
      "countryCode": "PL"                         - kod kraju zgodny ze
                                                  standardem ISO 3166-1 alpha-2
    },
    "email": "hamu7udk3p+17454c1b6@allegromail.pl/",- wymagany, adres e-mail. Musisz 
                                                    przekazać prawidłowy maskowany adres e-mail 
                                                    wygenerowany przez Allegro.
    "name": "Jan Kowalski",                       - imię i nazwisko
    "company": "Allegro.pl sp. z o.o.",           - nazwa firmy
    "phone": "500600700",                         - numer telefonu
    "pointId": "1234567"                          - wymagane, jeśli adresem odbiorczym jest 
                                                  punkt odbioru. ID punktu odbioru, pobierzesz 
                                                  z danych zamówienia za pomocą GET /order/checkout-forms
  },
  "pickup": {                                     - wymagane, dane nadawcy
    "address": {                                  - informacje o adresie odbioru
      "street": "Testowa 8",                      - ulica wraz z numerem budynku
      "postCode": "10-200",                       - kod pocztowy
      "city": "Warszawa",                         - miasto
      "countryCode": "PL"                         - kod kraju zgodny ze
                                                  standardem ISO 3166-1 alpha-2
    },
    "email": "email@mail.com",        
    "name": "Jan Kowalski",            
    "company": "Allegro.pl sp. z o.o.",        
    "phone": "500600700",            
    "pointId": "1234567"            
  },
  "items": [                                      - wymagane, informacje o paczkach. 
                                                  Maksymalna liczba przesyłek dla 
                                                  przewoźników to: 10 - DHL (oprócz palet), 
                                                  DPD (oprócz kopert), GLS, INPOST_KURIER, 
                                                  UPS (umowa własna), FEDEX;
                                                  1 - pozostali przewoźnicy.
    {
      "weight": {                                 - waga paczki
          "value": "12",
          "unit": "KILOGRAM"
      },                    
      "dimensions": {                             - wymiary paczki
        "height": {                               - wysokość paczki
          "value": "20",
          "unit": "CENTIMETER"
        },                
        "width": {                                - szerokość paczki
          "value": "20",
          "unit": "CENTIMETER"
        },        
        "depth": {                                - głębokość paczki
          "value": "20",
          "unit": "CENTIMETER"
        },                    
      },
      "type": "PACKAGE"                           - wymagane (jeśli nie przekażesz pola 
                                                  “type” na głównym poziomie), typ przesyłki
      "description": "Car wheels.",               - opis zawartości paczki
      "value": {                                  - deklarowana wartość paczki
        "amount": "2.50",
        "currency": "PLN"
      }
    }
  ],
  "type": "PACKAGE",                              - wymagane (jeśli nie przekażesz 
                                                  pola type na poziomie sekcji items), 
                                                  typ przesyłki
  "label": {                                      - niewymagane, informacje na etykiecie
    "sender": {                                   - informacje o nadawcy na etykiecie
      "address": {
        "street": "Testowa 8",
        "postCode": "10-200",
        "city": "Warszawa",
        "countryCode": "PL",
        "county": null                            - niewymagane, uzupełnij tylko, jeśli
                                                  wysyłasz paczkę z Irlandii, USA lub Kanady
      },
      "email": "email@mail.com",
      "name": "Jan Kowalski",
      "company": "Allegro.pl sp. z o.o.",
      "phone": "500600700"
    },
    "fileFormat": "PDF",                          - format pliku etykiety
    "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)
  },
   "additionalServices": {                        - usługi dodatkowe. Dostępne są tylko te możliwości,
                                                  które otrzymałeś w odpowiedzi dla 
                                                  GET /parcel-management/delivery-services
                                                  dla danej usługi dostawy
     "cashOnDelivery": {
       "value": {
         "amount": "2.50",
         "currency": "PLN"
       },
       "accountNumber": "12345678901234567890123456",
       "name": "Jan Kowalski",
        "express": false
      },
    "options": [
      "guarantee0930"
    ]
  }
 }'

Informacje o walidacji pola “type”:

  • jest wymagane tylko na jednym z poziomów (głównym lub w “items”),
  • jeśli pola “type” są uzupełnione na dwóch poziomach, sprawdzimy czy wszystkie pola “type” na poziomie “items” mają taką samą wartość jak pole “type” na głównym poziomie. Jeśli nie, zwrócimy błąd.

Jeżeli używasz pól pickup.pointId i receiver.pointId, wypełnij je wartością pobraną 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”

Tę wartość można również znaleźć w szczegółach zamówienia: GET /order/checkout-forms/{id}, w polu: delivery.pickupPoint.id.

Ważne! W odpowiedzi otrzymasz status 201 Created, pamiętaj jednak, że nie jest to równoznaczne z prawidłowym utworzeniem paczki. W nagłówku Retry-After zwrócimy informację o tym, za ile sekund możesz sprawdzić status zadania za pomocą GET parcel-management/parcel-create-commands/{commandId}.

Przykładowy response:

{
 "id": "14d3b9c4-ca3b-4e37-89c0-6f6cac24a02e",
 "input": {
  "serviceId": "0e4c7d59-64b6-4b06-89c3-c1d941506dd0",                     
  "receiver": {                                
    "address": {
      "street": "Testowa 172",                
      "postCode": "61-132",                    
      "city": "Poznań",                        
      "countryCode": "PL"            
    },
    "email": "hamu7udk3p+17454c1b6@allegromail.pl/",  
    "name": "Jan Kowalski",                    
    "company": "Allegro.pl sp. z o.o.",        
    "phone": "500600700",                    
    "pointId": "1234567"                    
  },
  "pickup": {                                
    "address": {                            
      "street": "Testowa 8",                
      "postCode": "10-200",                    
      "city": "Warszawa",                    
      "countryCode": "PL"                    
    },
    "email": "email@mail.com",        
    "name": "Jan Kowalski",            
    "company": "Allegro.pl sp. z o.o.",        
    "phone": "500600700",            
    "pointId": "1234567"    
  },
  "items": [                                
    {
      "weight": {                            
          "value": "12",
          "unit": "KILOGRAM"
      },                    
      "dimensions": {                        
        "height": {                            
          "value": "20",
          "unit": "CENTIMETER"
        },                
        "width": {                            
          "value": "20",
          "unit": "CENTIMETER"
        },        
        "depth": {                            
          "value": "20",
          "unit": "CENTIMETER"
        },                    
      },
      "description": "Car wheels.",   
      "value": {
        "amount": "2.50",
        "currency": "PLN"
      }
      "type": "PACKAGE"        
    }
  ],
  "type": "PACKAGE",                        
  "label": {                                
    "sender": {                                
      "address": {
        "street": "Testowa 8",
        "postCode": "10-200",
        "city": "Warszawa",
        "countryCode": "PL",
        "county": null                      
      },
      "email": "email@mail.com",
      "name": "Jan Kowalski",
      "company": "Allegro.pl sp. z o.o.",
      "phone": "500600700"
    },
    "fileFormat": "PDF",                
    "referenceNumber": "abcd1234"           
  },
   "additionalServices": {                                        
     "cashOnDelivery": {
       "value": {
         "amount": "2.50",
         "currency": "PLN"
       },
       "accountNumber": "12345678901234567890123456",
       "name": "Jan Kowalski",
        "express": false
      },
    "options": [
      "guarantee0930"
    ]
  }
 }
}

Jak sprawdzić status utworzenia paczki

Za pomocą GET /parcel-management/parcel-create-commands/{commandId} sprawdzisz status utworzenia 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 odpytać o status komendy.

Przykładowy request:

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

Przykładowy response:

  {
    "id": "14d3b9c4-ca3b-4e37-89c0-6f6cac24a02e",      - numer UUID żądania
    "parcelId": "025b773f-3f14-4410-a119-b7cf66673d87",- ID paczki 
    "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
  }

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

  {
    "id": "279b7e5a-640a-4c6b-82ae-99446a64bf52",
    "parcelId": null,
    "status": "ERROR",
    "errors": [
        {
            "code": "VALIDATION_ERROR",
            "message": "Brak numeru budynku",
            "details": null,
            "path": "receiver.street",
            "userMessage": null
        }
    ]
  }

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

  {
    "id": "610ea12b-6a5b-4ebe-9ed4-a387b6dcab7e",
    "parcelId": null,
    "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
        }
    ]
  }

Jak pobrać szczegółowe informacje o paczce

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

Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/parcel-management/parcels/025b773f-3f14-4410-a119-b7cf66673d87' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' 
Kliknij, aby zobaczyć response
toggle visibility
curl -X PUT \
'https://api.allegro.pl/parcel-management/parcel-create-commands/14d3b9c4-ca3b-4e37-89c0-6f6cac24a02e' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d 
 '{
    "parcelId": "025b773f-3f14-4410-a119-b7cf66673d87",    - ID paczki
    "serviceId": "0e4c7d59-64b6-4b06-89c3-c1d941506dd0", - ID usługi dostawy
    "label": {
        "sender": {
            "name": "Jan Kowalski",
            "company": "Allegro.pl sp. z o.o.",
            "address": {
                "street": "Testowa 10",
                "postCode": "61-132",
                "city": "POZNAŃ",
                "county": null,
                "countryCode": "PL"
            },
            "email": "email@mail.com",
            "phone": "500600700"
        },
     "fileFormat": "PDF",                         -- format pliku etykiety
     "referenceNumber": "abcd1234",               -- zewnętrzny ID / sygnatura, który nadaje
                                                  sprzedający, dzięki któremu rozpozna przesyłkę 
                                                  w swoim systemie
    },
    "receiver": {                                 -- dane odbiorcy
        "name": "Jan Kowalski",
        "company": "Allegro.pl sp. z o.o.",
        "address": {
            "street": "Testowa 7",
            "zipCode": "61-132",
            "city": "POZNAŃ",
            "county": null,
            "countryCode": "PL"
        },
        "pointId": null,
        "email": "sdasd@allegromail.pl",
        "phone": "500600700"
    },
    "pickup": {                                    -- dane nadawcy
        "name": "Jan Kowalski",
        "company": "Allegro.pl sp. z o.o.",
        "address": {
            "street": "Testowa 8",
            "zipCode": "61-132",
            "city": "POZNAŃ",
            "county": null,
            "countryCode": "PL"
        },
        "pointId": null,
        "email": "email@mail.com",
        "phone": "500600700"
    },
    "items": [                                     -- informacje o paczce
        {
            "waybill": "0000000767923Q",           -- numer listu przewozowego 
            "weight": {                            -- waga paczki
                  "value": "20",
                "unit": "KILOGRAM"
        },        ,            
            "dimensions": {                        -- wymiary paczki
                "height": {                        -- wysokość paczki
                    "value": "20",
                  "unit": "CENTIMETER"
          },        
                "width": {                         -- szerokość paczki
                    "value": "20",
                  "unit": "CENTIMETER"
          },    
                "depth": {                         -- głębokość paczki
                    "value": "20",
                  "unit": "CENTIMETER"
          },    
            },
            "description": "Car wheels.",          -- opis zawartości paczki
            "value": {                             -- deklarowana wartość paczki
                "amount": "2.5",
                "currency": "PLN"
            },
          "type": "PACKAGE"                        -- typ przesyłki
        }
    ],
    "type": "PACKAGE",                             -- typ przesyłki
    "additionalServices": {},                      -- informacje o ewentualnych usługach 
                                                   dodatkowych
    "state": null                                  -- aktualny status paczki. Dostępne wartości
                                                   to: DRAFT (wystąpi, gdy utworzysz paczkę przez 
                                                   GUI jako draft, a następnie przez API pobierzesz jej szczegóły), 
                                                   CREATED (utworzona) i CANCELLED (anulowana)    
  }'

Jak anulować paczkę

Jeżeli utworzyłeś paczkę, ale np. nieprawidłowo wypełniłeś niektóre dane, możesz ją anulować za pomocą PUT /parcel-management/parcel-cancel-commands/{commandId}. W strukturze żądania przekaż parcelId wraz z ID paczki, którą chcesz usunąć.

Przykładowy request:

  curl -X PUT \
  'https://api.allegro.pl/parcel-management/parcel-cancel-commands/14d3b9c4-ca3b-4e37-89c0-6f6cac24a02e' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d '{
    "parcelId": "0e4c7d59-64b6-4b06-89c3-c1d941506dd0" - ID paczki, którą chcesz usunąć
   }'

Ważne! W odpowiedzi otrzymasz status 201 Created, pamiętaj jednak, że nie jest to równoznaczne z prawidłowym anulowaniem paczki. W nagłówku Retry-After, zwrócimy informację o tym, za ile sekund możesz sprawdzić status za pomocą GET /parcel-management/parcel-cancel-commands/{commandId}. Status SUCCESS nie gwarantuje, że wysyłka paczki została anulowana, np. nie możesz anulować paczki odebranej przez kuriera lub nadanej w paczkomacie.

Przykładowy response:

 {
    "id": "14d3b9c4-ca3b-4e37-89c0-6f6cac24a02e",
    "input": {
        "parcelId": "0e4c7d59-64b6-4b06-89c3-c1d941506dd0"
    }
 }

Jak sprawdzić status anulowania paczki

Za pomocą GET /parcel-management/parcel-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/parcel-management/parcel-cancel-commands/7832d3ff-9dd8-4473-9f4a-ebdeb0b73261' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' 

Przykładowy response:

  {
    "id": "7832d3ff-9dd8-4473-9f4a-ebdeb0b73261",      - 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": []                                       - informacje o błędach
  }

Jak sprawdzić proponowaną datę odbioru paczek przez kuriera

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

  • parcelId - wymagany, ID paczki, który zwróciliśmy w odpowiedzi dla GET parcel-management/create-commands/{commandId}. Możesz przekazać maksymalnie 100 ID paczek, np. parcelId=0e4c7d59-64b6-4b06-89c3-c1d941506dd0&parcelId=0f6c8d59-64b6-4b06-89c3-c1d941506dd5. 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. 2020-07-10.

W odpowiedzi, w tablicy proposals, otrzymasz zbiór paczek z proponowaną datą odbioru i zakresem godzinowym. Wybrany termin przekażesz w kolejnym kroku, gdy będziesz zamawiać odbiór paczek przez kuriera.

Ważne! 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ę.

Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/parcel-management/pickup-date-proposals?parcelId=0e4c7d59-64b6-4b06-89c3-c1d941506dd0&parcelId=0f6c8d59-64b6-4b06-89c3-c1d941506dd5&readyDate=2020-07-08' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' 
Kliknij, aby zobaczyć response
toggle visibility
{
    "parcelsProposals": [            
        {
            "parcelId": "0e4c7d59-64b6-4b06-89c3-c1d941506dd0",            -- ID paczki
            "proposals": [                    -- propozycje dat i godzin odbioru paczek przez
                        kuriera
                {
                    "date": "2020-07-08",     -- data
                    "minTime": "10:00",       -- najwcześniejsza godzina odbioru
                    "maxTime": "14:00"        -- najpóźniejsza godzina odbioru
                },
                {
                    "date": "2020-07-08",
                    "minTime": "12:00",
                    "maxTime": "14:00"
                },
                {
                    "date": "2020-07-08",
                    "minTime": "14:00",
                    "maxTime": "16:00"
                },
                {
                    "date": "2020-07-08",
                    "minTime": "15:00",
                    "maxTime": "17:00"
                },
                {
                    "date": "2020-07-08",
                    "minTime": "16:00",
                    "maxTime": "18:00"
                }
            ]
        },
        {
            "parcelId": "0f6c8d59-64b6-4b06-89c3-c1d941506dd5",
            "proposals": [
                {
                    "date": "2020-07-08",
                    "minTime": "10:00",
                    "maxTime": "14:00"
                },
                {
                    "date": "2020-07-08",
                    "minTime": "12:00",
                    "maxTime": "14:00"
                },
                {
                    "date": "2020-07-08",
                    "minTime": "14:00",
                    "maxTime": "16:00"
                },
                {
                    "date": "2020-07-08",
                    "minTime": "15:00",
                    "maxTime": "17:00"
                },
                {
                    "date": "2020-07-08",
                    "minTime": "16:00",
                    "maxTime": "18:00"
                }
            ]
        }
    ]
  }

Jak zamówić odbiór paczek przez kuriera

Skorzystaj z PUT /parcel-management/parcel-pickup-request-commands/{commandId}, aby zamówić odbiór przesyłek przez kuriera. Jako commandId przekaż numer UUID - wygeneruj go automatycznie we własnym zakresie. Pamiętaj, aby przy każdym nowym żądaniu, użyć nowego numeru UUID.

Ważne! Dla przewoźników InPost, Poczta Polska, ORLEN Paczka i GLS nie możesz wybrać daty podjazdu kuriera. W tych przypadkach nie przekazuj w żądaniu pola pickupDate.

Przykładowy request:

  curl -X PUT \
  'https://api.allegro.pl/parcel-management/parcel-pickup-request-commands/deb2238a-f7ac-4e12-89c9-537583143203' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d '{
  "parcelIds": [                 - tablica z identyfikatorami paczek do odbioru przez 
                                kuriera
    "0e4c7d59-64b6-4b06-89c3-c1d941506dd0",
    "0f6c8d59-64b6-4b06-89c3-c1d941506dd5"
  ],
  "pickupDate": {                - informacje o dacie i zakresie godzinowym odbioru
                                 paczek. Przekaż tutaj dokładnie te same wartości, 
                                 które otrzymałeś w odpowiedzi dla  
                                 GET /parcel-management/pickup-date-proposals
    "date": "2020-05-01",        - data odbioru
    "minTime": "10:00",          - najwcześniejsza godzina odbioru
    "maxTime": "14:00"           - najpóźniejsza godzina odbioru
  }
 }'

Ważne! W odpowiedzi otrzymasz status 201 Created, pamiętaj jednak, że nie jest to równoznaczne z prawidłowym utworzeniem zamówienia odbioru paczek. W nagłówku Retry-After, zwrócimy informację o tym, za ile sekund możesz sprawdzić status za pomocą GET /parcel-management/parcel-pickup-request-commands{commandId}.

Przykładowy response:

 {
    "parcelIds": [
    "0e4c7d59-64b6-4b06-89c3-c1d941506dd0",
    "0f6c8d59-64b6-4b06-89c3-c1d941506dd5"
    ],
    "pickupDate": {
        "date": "2020-05-01",
        "minTime": "10:00",
        "maxTime": "14:00"
    }
 }

Jak sprawdzić status zamówienia odbioru paczek

Za pomocą GET /parcel-management/parcel-pickup-request-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/parcel-management/parcel-pickup-request-commands/deb2238a-f7ac-4e12-89c9-537583143203' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' 

Przykładowy response:

  {
    "id": "deb2238a-f7ac-4e12-89c9-537583143203",   - numer UUID żądania
    "status": "SUCCESS",                            - status zadania, dostępne wartości to:
                                                    IN_PROGRESS (zadanie w trakcie
                                                    przetwarzania), SUCCESS (zadanie 
                                                    wykonane prawidłowo),  
                                                    PARTIAL_SUCCESS (zwrócimy, gdy 
                                                    część zamówień utworzymy prawidłowo,
                                                    a dla części zwrócimy błąd), ERROR 
                                                    (wystąpił błąd)
    "errors": []                                    - informacje o błędach
  }

Jak utworzyć etykietę na paczkę

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

  • parcelId - wymagane, przekaż ID paczki.
  • pageFormat - niewymagane, format strony. Przekaż wartość "A4" lub "A6". Dotyczy tylko plików w formacie PDF.

W odpowiedzi otrzymasz plik PDF, EPL lub ZPL (w zależności od wybranego formatu na etapie tworzenia paczki), który musisz zapisać na dysku. Pamiętaj, aby prawidłowo przekazać nagłówek Accept.

Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/parcel-management/parcels/label?parcelId=0e4c7d59-64b6-4b06-89c3-c1d941506dd0&pageFormat=A4' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/pdf' \         // lub text/plain
  -H 'Content-Type: application/pdf'     // lub text/plain

Przykładowy response:

  Status 200 OK

Jak pobrać protokół nadania przesyłek

Za pomocą GET /parcel-management/parcels/protocol pobierzesz protokoły nadania przesyłek. W żądaniu, dla parametrów parcelId, przekaż ID paczek, np. parcelId=0e4c7d59-64b6-4b06-89c3-c1d941506dd0&parcelId=0f6c8d59-64b6-4b06-89c3-c1d941506dd5. 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. Pamiętaj, aby prawidłowo przekazać nagłówek Accept.

Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/parcel-management/parcels/protocol?parcelId=0e4c7d59-64b6-4b06-89c3-c1d941506dd0&parcelId=0f6c8d59-64b6-4b06-89c3-c1d941506dd5' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/pdf' \
  -H 'Content-Type: application/pdf'

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' 
Kliknij, aby zobaczyć response
toggle visibility
{
    "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 /parcel-management/delivery-services), a jako waybill przekaż numer przesyłki, który otrzymasz w odpowiedzi dla GET /parcel-management/parcels/{parcelId} w polu “items.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' 
Kliknij, aby zobaczyć response
toggle visibility
{
  "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
      }
    }
  ]
}

Lista zasobów

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

Lista zasobów podstawowych opisanych w poradniku:

  • GET /parcel-management/delivery-services - pobierz listę dostępnych usług dostawy
  • PUT /parcel-management/parcel-create-commands/{commandId} - utwórz nową paczkę
  • GET parcel-management/parcel-create-commands/{commandId} - sprawdź status utworzenia paczki
  • GET /parcel-management/parcels/{parcelId} - pobierz szczegółowe dane paczki
  • PUT parcel-management/parcel-cancel-commands/{commandId} - anuluj paczkę
  • GET /parcel-management/parcel-cancel-commands/{commandId} - sprawdź status anulowania paczki
  • GET /parcel-management/pickup-date-proposals - pobierz propozycje dat i godzin odbioru paczek przez kuriera
  • PUT /parcel-management/parcel-pickup-request-commands/{commandId} - zamów odbiór paczek przez kuriera
  • GET /parcel-management/parcel-pickup-request-commands{commandId} - sprawdź status zamówienia odbioru paczek
  • GET /parcel-management/parcels/label - pobierz etykiety
  • GET /parcel-management/parcels/protocol - pobierz protokoły nadania

Zgłoś błąd lub zasugeruj zmianę

Czy ten artykuł był dla Ciebie przydatny?