[API] Tworzenie nowej przesyłki w Apilo
Spis treści
Proces tworzenia nowej przesyłki za pomocą Apilo jest wieloetapowy i wymaga uprzedniej konfiguracji konta.
Konfiguracja:
– dodanie kont integracji kurierskich do konta w Apilo za pomocą formularza pod adresem
https://{{apilo_client_account}}.apilo.pl/admin/carrier-account/
Gdy zostaną utworzone konta integracji kurierskich, można przystąpić do pobiera informacji potrzebnych do utworzenia
nowej przesyłki:
– identyfikator konta kuriera (dodany w kroku Konfiguracja powyżej)
– metoda wysyłki (jeśli inna niż default)
– opcje przesyłki i pakowania (waga, wymiary)
Jak pobrać identyfikator konta kuriera? (kontekst tworzenia nowej przesyłki w Apilo)
Służy do tego endpoint:
GET https://{{apilo_client_account}}.apilo.pl/rest/api/shipping/carrier-account/map/
Zwrócona odpowiedź:
{ "carrierAccounts": [ { "id": 1, "key": "CARRIER_ACCOUNT_143_1", "name": "AllegroBroker", "description": "Wysyłam z Allegro", "options": { "isPickupInShipmentCreation": false, "isPickupInShipmentConfirmation": true, "isShipmentConfirmationRequired": true } }, { "id": 3, "key": "CARRIER_ACCOUNT_3_3", "name": "Inpost", "description": "Inpost (Kurier, Paczkomaty, Allegro)", "options": { "isPickupInShipmentCreation": false, "isPickupInShipmentConfirmation": false, "isShipmentConfirmationRequired": false } }, ... ] }
Zwrócone identyfikatory (pole: id) posłużą za argumenty do kolejnego endpointu.
Warto jednak przeanalizować otrzymane wraz z nimi opcje:
isPickupInShipmentCreation – informuje czy podjazd kuriera w ustalonych godzinach jest możliwy do zadeklarowania już na etapie tworzenia przesyłki
isPickupInShipmentConfirmation – informuje czy podjazd kuriera w ustalonych godzinach jest możliwy do zadeklarowania na etapie potwierdzenia przesyłki
isShipmentConfirmationRequired – informuje czy wymagane jest potwierdzenie przesyłki
Wartości zwrócone dla tych opcji mają wpływ na możliwość skorzystania z funkcjonalności zamawiania podjazdu kuriera i wiążą się z wywołaniem kolejnych endpoint-ów. Na ten moment można zamawiać podjazd jedynie poprzez „Wysyłam z Allegro”.
Jak pobrać metody wysyłki? (kontekst tworzenia nowej przesyłki w Apilo)
GET https://{{apilo_client_account}}.apilo.pl/rest/api/shipping/carrier-account/{{carrier_account_id}}/method/
gdzie:
{{carrier_account_id}} - identyfikator pobrany w poprzednim endpoincie, np. 1 dla Allegro.
Nie jest to wartość stała. Identyfikatory kont integracji kurierskich są nadawane
indywidualnie dla każdego klienta Apilo, a także zależą od kolejności ich dodawania w kroku Konfiguracja powyżej.
Zwrócona odpowiedź (fragment):
{ "methods": [ { "id": "12d2c05d-5807-4fbe-8471-1ad29a637bdc", "name": "Allegro Kurier Express One pobranie" }, { "id": "02d2c05d-e7f3-494f-a597-1ad29a637bdc", "name": "Allegro Kurier Express One" }, { "id": "0099dbaa-be2e-430d-8f94-ab9c86ea6a5e", "name": "Allegro Odbiór w Punkcie Express One" }, { "id": "1099dbaa-5a98-4c2a-a7b4-ab9c86ea6a5e", "name": "Allegro Odbiór w Punkcie Express One pobranie" }, { "id": "0a6f5534-8f51-4912-ac40-2be5bbc1bd4d", "name": "Allegro Automat Express One" }, { "id": "1a6f5534-a3b3-4cc7-bc02-2be5bbc1bd4d", "name": "Allegro Automat Express One pobranie" }, { "id": "025cb739-ef8e-45c4-9e7b-ce4e7fece8be", "name": "Allegro Odbiór w Punkcie ORLEN Paczka" }, { "id": "09164667-daa5-42dc-8087-33d7485790ac", "name": "Allegro Automat ORLEN Paczka" }, { "id": "0e4c7d59-64b6-4b06-89c3-c1d941506dd0", "name": "Allegro Kurier UPS" }, { "id": "199d2a2a-7c90-4ca7-aaf3-c1d941506dd0", "name": "Allegro Kurier UPS pobranie" }, { "id": "0d69a62b-7a66-4bd1-9134-49dea68dccc8", "name": "Allegro Odbiór w Punkcie UPS" }, { "id": "0d021121-97e5-4729-9af6-a05779c6b835", "name": "Allegro MiniPrzesyłka" }, { "id": "aa1d05e0-943b-47cb-a759-9d8c16707129", "name": "Allegro Przesyłka polecona" }, { "id": "093d950b-8497-4cc7-aa2a-6081e5e7e7e2", "name": "Allegro Kurier Pocztex" }, { "id": "028e2be0-1c06-41cf-a309-ec5557273786", "name": "Allegro Odbiór w Punkcie Pocztex" }, { "id": "0fc30a71-a1c3-4572-8217-c29515a5f0d1", "name": "Allegro Automat Pocztex" }, { "id": "0660145a-f92f-417d-a88b-effb8240eb45", "name": "Allegro Odbiór w Punkcie ORLEN Paczka (ważna do 21.10.2024)" }, { "id": "04c33651-bd96-484b-a89b-06a797d8eff4", "name": "Allegro Automat ORLEN Paczka (ważna do 21.10.2024)" }, { "id": "31a306e6be3e352f452421b42ad44e22", "name": "ORLEN Paczka (Orlen sandbox)" }, { "id": "046452898438bde4c58502a5a4896dbf", "name": "ORLEN Paczka pobranie (Orlen sandbox)" }, { "id": "fcd8b669172c42e370971d860edf496f", "name": "Kurier InPost (Inpost sandbox) (KURIER)" }, { "id": "f55a99ec6a31dce861fa4ab58d897c2d", "name": "Kurier InPost pobranie (Inpost sandbox) (KURIER)" }, { "id": "24f5c55531899af0c841b52b3bbc0a54", "name": "Paczkomaty InPost (Inpost sandbox) (PACZKOMAT)" }, { "id": "e1137a63bb53d38d9ba610dc8f553e9e", "name": "Paczkomaty InPost pobranie (Inpost sandbox) (PACZKOMAT)" }, { "id": "250dbb2f9996b8308540160d1a9e1886", "name": "Allegro Kurier24 InPost (Inpost sandbox) (KURIER)" }, { "id": "6d5bbfcbe809007f4e546df77cbf5752", "name": "Allegro Kurier24 InPost pobranie (Inpost sandbox) (KURIER)" }, { "id": "2533b181a0810f248181f8bf365d7fd2", "name": "Allegro miniKurier24 InPost (Inpost sandbox) (KURIER)" }, { "id": "75f35102762de75d2a827113c9fa88b6", "name": "Allegro miniKurier24 InPost pobranie (Inpost sandbox) (KURIER)" }, { "id": "ffc173ce598becbf1dc8943bf57d6870", "name": "Allegro Paczkomaty InPost (Inpost sandbox) (PACZKOMAT)" }, { "id": "358ca81df104d7f7ae28228b959f926f", "name": "Allegro Paczkomaty InPost pobranie (Inpost sandbox) (PACZKOMAT)" },, { "id": "c3066682-97a3-42fe-9eb5-3beeccab840c", "name": "Allegro Kurier DPD" }, { "id": "259b5c7a-9056-4c74-80ec-8bdc50cb0413", "name": "Allegro Kurier DPD pobranie" }, { "id": "08e2ef8e-90c8-49db-8970-d6c2773f1530", "name": "Allegro Odbiór w Punkcie DPD Pickup" }, { "id": "1d037bcd-7e6a-4713-9015-d6c2773f1530", "name": "Allegro Odbiór w Punkcie DPD Pickup pobranie" }, { "id": "0c330aea-900f-4830-9de8-72fadd2a3916", "name": "Allegro Automat DHL BOX 24\/7" }, { "id": "a3b4db98-4a70-4542-84ee-c642604d9d8a", "name": "Allegro Kurier DHL" }, { "id": "07c12933-584e-453d-bee5-60f3f32dfc73", "name": "Allegro Odbiór w Punkcie DHL" }, { "id": "0d83955a-4297-4169-adef-9790d53b11ff", "name": "Allegro One Kurier - dostawa jutro" }, { "id": "1d83955a-69c8-407c-becc-9790d53b11ff", "name": "Allegro One Kurier pobranie - dostawa jutro" }, { "id": "08c15d0b-9b24-4b3f-89a8-7a2b502abe55", "name": "Allegro One Punkt, UPS" }, { "id": "0aafb43c-e66a-46ec-9cc4-29bb39ebb483", "name": "Allegro One Box, UPS" }, { "id": "0b9bed2c-0bc1-4e1f-9694-29bb39ebb483", "name": "Allegro One Box, One Kurier" }, { "id": "0ee3467f-5451-4060-856e-7a2b502abe55", "name": "Allegro One Punkt, One Kurier" }, { "id": "0e454c54-21dd-4e5c-9db2-0553724f9077", "name": "Allegro One Box, One Kurier - dostawa dzisiaj" }, { "id": "0b257488-c85d-4507-b967-9b45ffbfa2e8", "name": "Allegro One Box, DPD" }, { "id": "09ef5a54-c34d-41ef-908e-9b45ffbfa2e8", "name": "Allegro One Punkt, DPD" } ] }
Jak pobrać opcje przesyłki i pakowania? (kontekst tworzenia nowej przesyłki w Apilo)
GET https://{{apilo_client_account}}.apilo.pl/rest/api/shipping/carrier-account/{{carrier_account_id}}/method/{{method}}/map/
gdzie:
{{carrier_account_id}} – identyfikator konta integracji kurierskiej, np. 1 dla Allegro z przykładów powyżej
{{method}} – identyfikator metody, np. c3066682-97a3-42fe-9eb5-3beeccab840c dla Allegro Kurier DPD
Zwrócona odpowiedź:
{ "options": { "id": "options", "type": "definition", "label": "Opcje przesyłki", "multiple": false, "properties": [ { "id": "insurance", "type": "money", "label": "Wartość ubezpieczenia" }, { "id": "packageType", "type": "choice", "label": "Rodzaj przesyłki", "choices": [ { "value": "PACKAGE", "label": "Paczka" }, { "value": "DOX", "label": "Koperta (DOX)" }, { "value": "PALLET", "label": "Paleta" } ], "multiple": false }, { "id": "services", "type": "choice", "label": "Usługi dodatkowe", "choices": [ { "value": "additionalHandling", "label": "Paczka niestandardowa" }, { "value": "returnOfDocuments", "label": "Dokumenty zwrotne" }, { "value": "collectionUponDelivery", "label": "Przesyłka zwrotna" }, { "value": "guarantee0930", "label": "Doręczenie do 09:30" }, { "value": "guarantee1200", "label": "Doręczenie do 12:00" }, { "value": "guaranteeNextDay", "label": "Doręczenie w następnym dniu roboczym" }, { "value": "saturdayDelivery", "label": "Doręczenie w sobotę" }, { "value": "privateShipping", "label": "Doręczenie do osoby prywatnej" }, { "value": "documentsSupply", "label": "Dostarczenie dokumentów przewozowych przez kuriera" }, { "value": "personalDelivery", "label": "Doręczenie do rąk własnych" } ], "multiple": true }, { "id": "dropoffPoint", "type": "string", "label": "Sposób nadania" }, { "id": "receiverParcel", "type": "string", "label": "Punkt odbioru" }, { "id": "comment", "type": "string", "label": "Komentarz" } ], "required": [ "packageType" ] }, "parcels": { "id": "parcels", "type": "definition", "label": "Opcje pakowania", "multiple": true, "properties": [ { "id": "dimensions", "type": "dimensions", "label": "Wymiary" }, { "id": "weight", "type": "integer", "label": "Waga [gramy]" } ], "required": [ "dimensions", "weight" ] }, "maxParcelsCount": 1 }
UWAGA: Klucz „multiple” w ramach obiektów „options” i „parcels” (type: definition).
Oznacza, że w kolejnym endpoincie, tj. służącym do nadawania przesyłki, Apilo REST API oczekuje obiektu,
który zawiera 1 obiekt dla właściwości „options” i tablicy obiektów dla właściwości „parcels”. Najlepiej będzie to widoczne
na przykładzie w opisie kolejnego endpointu.
Jak utworzyć nową przesyłkę? (kontekst tworzenia nowej przesyłki w Apilo)
POST https://{{apilo_client_account}}.apilo.pl/rest/api/shipping/shipment/
W ramach treści żądania (body) należy przesłać obiekt JSON, który zawiera wszystkie wymagane właściwości.
Opcje dodatkowe są walidowane pod kątem poprawności, ale można je pominąć.
{ "carrierAccountId": 1, "addressReceiver": { "type": "house", "name": "Jan Kowalski", "streetName": "Kwiatowa", "streetNumber": "1", "zipCode": "01-001", "city": "Warszawa", "country": "PL", "phone": "48500600700", "email": "bb7ygt6xzx+5040fe591@user.allegrogroup.pl" }, "orderId": "AL240800057", "postDate": "2024-09-06T13:41:18+00:00", "method": "c3066682-97a3-42fe-9eb5-3beeccab840c", "options": [ { "id": "insurance", "type": "money", "value": { "amount": "2014.44", "currency": "PLN" } }, { "id": "packageType", "type": "choice", "value": ["PACKAGE"] }, { "id": "dropoffPoint", "type": "string", "value": "Allegro One Box, zielony automat||AL003KR1" }, { "id": "comment", "type": "string", "label": "Ostrożnie, paczka zawiera kruche elementy." } ], "parcels": [ { "options": [ { "id": "dimensions", "type": "dimensions", "value": { "length": 50, "width": 60, "height": 70 } }, { "id": "weight", "type": "integer", "value": 2500 } ] } ] } W odpowiedzi zostanie zwrócony ID nowoutworzonej przesyłki. { "shipments":[ { "shipmentId": 169 } ] }
W jakiej postaci przesłać wymiary ( dimensions) w parcels w akcji tworzenia paczki? (kontekst tworzenia nowej przesyłki w Apilo)
Sposób przekazania wymiarów jest zależny od integracji.
Znaczna część integracji stosuje postać:
{ "id": "dimensions", "type": "dimensions", "value": { "length": 50, "width": 60, "height": 70 } }
Jednak są wyjątki jak np. broker Allegro z metodą wysyłki Inpost Paczkomat:
{ "id": "dimensions", "type": "choice", "choices": [ { "value": "A", "label": "Gabaryt A - 64cm x 38cm x 8cm, 25kg" }, { "value": "B", "label": "Gabaryt B - 64cm x 38cm x 19cm, 25kg" }, { "value": "C", "label": "Gabaryt C - 64cm x 38cm x 41cm, 25kg" } ] }
Aby mieć pewność w jaka postać jest wymagane przez daną integrację, należy skorzystać z endpointu:
/rest/api/shipping/carrier-account/{carrierAccountId}/method/{method}/map/
Następnie zerknąć czy w polu parcels.properties[] jest obiekt z id dimensions i jaki jest jego typ.
Jeśli type = dimensions, to przesyłamy standardowy obiekt z length, width, height.
Jeśli type = choice, należy wówczas przesłać jedną z wylistowanych wartości.