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 wspieramy dwa podejścia dla tworzenia przesyłek w ramach usługi “Wysyłam z Allegro”:
- nowe zasoby /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,
- dotychczasowe zasoby /parcel-management, które przestaliśmy już wspierać. Od 21.09.2023 są one oznaczone jako Deprecated, natomiast w czwartym kwartale 2024 roku zostaną całkowicie usunięte.
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ń.
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'
Przykładowy response:
{
"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": { - ubezpieczenie
"limit": 50000, - limit kwoty ubezpieczenia
"currency": "PLN" - waluta kwoty ubezpieczenia
},
"features": { - dodatkowe informacje, zwracamy tylko dla metod Allegro One
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
}
]
}
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
Dla każdej z nich tworzymy dedykowane usługi dostawy odpowiadające metodom. Identyfikator każdej usługi otrzymuje konstrukcję: id_metody#id_umowy_własnej, które zwracamy w GET /shipment-management/delivery-services, odpowiednio:
- id_metody - w polu "deliveryMethodId",
- id_umowy_własnej - w polu "credentialsId". np.
- metoda dostawy: b20ef9e1-faa2-4f25-9032-adbea23e5cb9 ("Allegro Paczkomaty InPost pobranie") - usługa dostawy: b20ef9e1-faa2-4f25-9032-adbea23e5cb9#abcdef-ghij-klmn-opqrs123.
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 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", - ulica
"streetNumber":"30", - 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", - ulica
"streetNumber":"30", - 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", - ulica
"streetNumber":"30", - 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)
"description":"Car wheels", - opis zawartości paczki
"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"
}
}
],
"insurance":{ - ubezpieczenie
"amount":"23.47", - suma ubezpieczenia
"currency":"PLN" - waluta kwoty ubezpieczenia
},
"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, EPL
"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",
"streetNumber": "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",
"streetNumber": "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",
"streetNumber": "30",
"postalCode": "10-200",
"city": "Warszawa",
"state": "AL",
"countryCode": "PL",
"email": "email@mail.com",
"phone": "500600700",
"point": "A1234567"
},
"referenceNumber": "abcd1234",
"description": "Car wheels",
"packages": [
{
"type": "DOX",
"length": {
"value": "12",
"unit": "CENTIMETER"
},
"width": {
"value": "12",
"unit": "CENTIMETER"
},
"height": {
"value": "12",
"unit": "CENTIMETER"
},
"weight": {
"value": "12.45",
"unit": "KILOGRAMS"
}
}
],
"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:
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",
"streetNumber": "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",
"streetNumber": "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",
"streetNumber": "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
"description": "Car wheels", - opis zawartości paczki
"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"
}
}
],
"insurance": { - ubezpieczenie
"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ąć.
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.
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”.
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.
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
}'
[
{
"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
}
]
}
]
}
]
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ż:
- identyfikator paczki w “shipmentId”,
- ID proponowanego czasu odbioru paczki w "pickupDateProposalId", uzyskanego za pomocą POST /shipment-management/pickup-proposals.
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”.
}
}'
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"
}
}
Jak sprawdzić status zamówienia odbioru paczek
Za pomocą GET /shipment-management/pickups/create-commands/{commandId} sprawdź status zamówienia odbioru paczek.
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), 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ą 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, EPL 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
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
}
}
]
}
Jak zarządzać przesyłkami poprzez /parcel-management/
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ń.
Pobieranie listy 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.
Utworzenie paczki
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 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 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.
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. Maksymalna liczba
paczek wchodzących w skład jednej przesyłki
(dotyczy tylko DPD i WE|DO) to: 10.
{
"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", - numer konta wskazany w przez sprzedawcę przy tworzeniu przesyłki musi
być taki sam, jak w ustawieniach wypłat Allegro
"name": "Jan Kowalski",
"express": false
},
"options": [
"guarantee0930"
]
}
}'
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"
]
}
}
}
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
}
]
}
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'
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)
}'
Anulowanie utworzonej paczki
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"
}
}
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
}
Sprawdzanie daty 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'
{
"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"
}
]
}
]
}
Zamówienie odbioru 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 i ORLEN Paczka 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"
}
}
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
}
Tworzenie etykiety
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
Pobieranie protokołu nadania
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
Lista zasobów
Pełną dokumentację zasobów w postaci pliku swagger.yaml znajdziesz tu.
Lista zasobów podstawowych opisanych w poradniku:
- GET /shipment-management/delivery-services - pobierz listę dostępnych usług dostawy,
- POST /shipment-management/shipments/create-commands - utwórz nową paczkę,
- GET /shipment-management/shipments/create-commands - sprawdź status utworzenia paczki,
- POST /shipment-management/shipments/cancel-commands - anuluj paczkę,
- GET /shipment-management/shipments/cancel-commands/{commandId} - sprawdź status anulowania paczki,
- GET /shipment-management/shipments/{shipmentId} - pobierz szczegółowe dane paczki,
- POST /shipment-management/label - utwórz etykietę,
- POST /shipment-management/protocol - pobierz protokół nadania,
- POST /shipment-management/pickup-proposals - pobierz propozycje daty odbioru paczek przez kuriera,
- POST /shipment-management/pickups/create-commands - zamów odbiór paczek przez kuriera
- GET /shipment-management/pickups/create-commands/{commandId} - sprawdź status zamówienia odbioru paczek.