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.