Versions Compared

Old Version 7

changes.mady.by.user Michał Machowski

Saved on

compared with

New Version 8

changes.mady.by.user Michał Machowski

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Sercem Platformy Usług Zintegrowanych są przesyłki. Na definicję przesyłki składają się:

  • dane nadawcy i odbiorcy 

  • paczka (jedna lub więcej), która będzie fizycznie przesyłana 

  • wybrana usługa (opcjonalnie usługi dodatkowe)

  • inne dodatkowe atrybuty w zależności od preferencji użytkownika, np.:

    • Ubezpieczenie

    • Pobranie

Aby utworzyć przesyłkę gotową do nadania, wymagane są 3 kroki:

  1. Utworzenie przesyłki, na co składa się podanie danych nadawcy, odbiorcy oraz informacji o paczce (fioletowe figury na poniższym diagramie),

  2. Pobranie informacji o dostępnych usługach dla utworzonego wcześniej obiektu przesyłki (niebieskie figury na poniższym diagramie),

  3. Zakupienie etykiety poprzez wskazanie określonej usługi, dostępnej dla przesyłki, która została utworzona w kroku 1 (zielona figura na poniższym diagramie) 

Info

Ceny usług mogą różnić się w zależności od wymiarów paczki oraz parametrów przesyłki, zdefiniowanych podczas jej tworzenia.

Listę wszystkich usług można znaleźć na stronie [1.9.1] Rozmiary i usługi dla przesyłek

Dostępność usług zależy od przewoźników z którymi dana organizacja podpisała umowy.

Dla Klientów, których umowa pozwala na utworzenie debetu w systemie InPost (klient debetowy), nie będą zwracane ceny w odpowiedzi JSON, na wysłane żądanie do API.

Na tej stronie

Table of Contents


Diagram tworzenia przesyłki

Image RemovedImage Added

Struktura

Zasób Shipment  posiada następujące atrybuty:

Atrybut

Typ

Opis

id

Integer

Tylko do odczytu. Identyfikator przesyłki w platformie Ship X.

status

String

Tylko do odczytu. Aktualny status przesyłki.

custom_attributes

CustomAttributes

Dodatkowe, opcjonalne atrybuty dla przesyłki.

parcels

Array[Parcel]

Lista paczek w ramach przesyłki.

created_at

DateTime

Tylko do odczytu. Data utworzenia przesyłki w systemie Ship X.

created_by_id

Integer

Id użytkownika, który utworzył przesyłkę, jeśli użytkownik jest zalogowany.

sender

Peer

Dane nadawcy.

receiver

Peer

Dane odbiorcy.

cod

MoneyData

Pobranie za przesyłkę.

insurance

MoneyData

Ubezpieczenie przesyłki.

additional_services

Array[String]

Usługi dodatkowe wybrane przy tworzeniu przesyłki (różne oferty mogą zawierać różne usługi dodatkowe).

Dostępne usługi dodatkowe: sms, email, saturday. [1.9.1] Rozmiary i usługi dla przesyłek

reference

String

Dodatkowy opis dla przesyłki, np. numer zamówienia lub ID klienta.

is_return

Bool

Określa czy przesyłka jest zwrotna.

offers

Array[Offer]

Lista dostępnych usług wraz z cenami, które możliwe są do nabycia w ramach tej przesyłki.

selected_offer

Offer

Usługa, która została wybrana podczas kupowania etykiety dla przesyłki.

transactions

Array[Transaction]

Lista transakcji płatniczych związanych z daną przesyłką.

tracking_number

String

Numer trackingowy przesyłki (identyfikator na poziomie systemu logistycznego).

sending_method

String

Powielenie pola z custom_attributes.

external_customer_id 

String

Identyfikator broker'a generującego przesyłki w ramach innej organizacji.

Atrybuty obiektu Parcel

Atrybut

Typ

Opis

id

String

Wymagany przy tworzeniu przesyłki z wieloma paczkami. Unikalny identyfikator danej paczki w ramach przesyłki, który pozwala zwrócić użytkownikowi informację o błędach walidacji przypisanych do konkretnej paczki. Id nie jest zapisywany w bazie danych i nie jest zwracany jak atrybut utworzonej paczki.

template

String

Nazwa predefiniowanego szablonu wymiarów i wagi paczki. Listę predefiniowanych szablonów wymiarów i rozmiarów paczek można znaleźć na stronie [1.9.1] Rozmiary i usługi dla przesyłek .

dimensions

Object

Wymiary paczki.

  • length - długość

  • width - szerokość

  • height - wysokość

  • unit - jednostka, w której podane są wymiary. Aktualnie tylko mm (millimetry)

Uzupełniane automatycznie w przypadku wybrania prawidłowego szablonu template.

weight

Object

Waga paczki

  • amount - waga,

  • unit - jednostka, w której podana jest waga paczki. Aktualnie tylko kg (kilogramy)

Uzupełniana automatycznie w przypadku wybrania prawidłowego szablonu template.

tracking_number

String

Numer danej przesyłki. Nadawany w trakcie kupowania wybranej oferty.

is_non_standard

Bool

Ustawiany na true jeżeli przesyłka jest niestandardowa. Parametr można ustawić tylko dla przesyłek kurierskich.

Paczka realizowana tylko w ramach usług kurierskich w serwisie krajowym, której jeden z wymiarów przekracza 120 cm lub której suma wymiarów (długość + szerokość + wysokość) przekracza 220 cm. Paczką niestandardową są również: elementy o kształcie okrągłym, cylindrycznym lub owalnym, o nieregularnych kształtach lub/i z wystającymi elementami.
Opcja paczek niestandardowych nie dotyczy paczek dłużycowych.

Struktura obiektu Offer

Atrybut

Typ

Opis

id

Integer

Unikalny identyfikator usługi oferowanej w ramach przesyłki

service

Service

Obiekt oferowanej usługi.

carrier

Carrier

Obiekt przewoźnika.

additional_services

Array[String]

Usługi dodatkowe wybrane przy tworzeniu przesyłki - dostępne w danej ofercie.

status

String

Status oferty. Możliwe statusy oferty: in_preparation, available, unavailable, selected, bought, expired  

expires_at 

DateTime

Data i godzina do której możliwe jest zakupienie oferty.

rate

Decimal

Cena za usługę.

currency

String

Waluta, w której podana jest cena za usługę.

unavailability_reasons

Array

Przyczyny niedostępności danej oferty.

Struktura obiektu Service

Atrybut

Typ

Opis

id

String

Identyfikator usługi

name

String

Nazwa usługi

description 

String

Opis usługi

Struktura obiektu Carrier

Atrybut

Typ

Opis

id

String

Identyfikator przewoźnika

name 

String

Nazwa przewoźnika

description 

String

Opis przewoźnika

Struktura obiektu Transaction

Atrybut

Typ

Opis

id 

String

Identyfikator transakcji

status

String

Status transakcji. Możliwe statusy: initiated, success, failure

created_at

DateTime

Data utworzenia transakcji.

updated_at

DateTime

Data ostatniej modyfikacji transakcji.

offer_id

Integer

Id oferty, której transakcja dotyczy.

Atrybuty obiektu Peer

Atrybut

Typ

Opis

id 

String

Identyfikator obiektu Peer

name 

String

Nazwa

company_name

String

Nazwa firmy

first_name

String

Imię

last_name

String

Nazwisko

email

String

Adres e-mail

phone

String

Numer telefonu

address

Address

Adres

Atrybuty obiektu Address

Note

Atrybut line1 i line2 jest jeszcze wspierany, jednak zalecane jest używanie street i building_number.

Atrybut

Typ

Opis

id 

String

Identyfikator obiektu adres

line1

String

Pierwsza linia adresu

line2

String

Druga linia adresu

street 

String

Nazwa ulicy

building_number 

String

Numer domu

city

String

Miasto

post_code

String

Kod pocztowy

country_code

String

Kod kraju

Atrybuty obiektu MoneyData

Atrybut

Typ

Opis

amount

Decimal

Kwota

currency

String

Waluta

Atrybuty obiektu CustomAttributes

Atrybut

Typ

Opis

target_point

String

Nazwa punktu docelowego, do którego ma zostać dostarczona przesyłka, z którego podejmie ją odbiorca, np. nazwa paczkomatuPaczkomat®.

Tylko przesyłki paczkomatowePaczkomat®.

sending_method 

String

[1.8.1] Sposób nadania

Wymagane dla przesyłek Allegro.

dropoff_point

String

Nazwa punktu nadawczego, do którego nadawca dostarczy przesyłkę do wysłania, np. nazwa paczkomatuPaczkomat®.

Wymagane przy podaniu metody nadania pok, courier_pok, parcel_locker.

allegro_transaction_id

String

Numer transakcji formularza posprzedażowego Allegro, w którym kupujący wybrał formę dostawy Allegro Paczkomaty Paczkomat® InPost. Podanie tego parametru skutkuje koniecznością podania parametru allegro_user_id.

allegro_user_id

String

Numer użytkownika Allegro, w ramach transkacji określonej parameterem allegro_user_id, który jest sprzedającym. Podanie tego parametru skutkuje koniecznością podania parametru allegro_transaction_id.

dispatch_order_id 

Integer

Numer zlecenia odbioru.

Atrybut tylko do odczytu, występuje gdy przesyłka posiada zdefiniowane zlecenie odbioru.

Przykład zasobu Shipment w formacie JSON (przesyłka paczkomatowaPaczkomat®). 

Code Block
languagejson
{
	"href": "https://api-shipx-pl.easypack24.net/v1/organizations/1/shipments/1234567890",
	"id": "1234567890",
	"status": "offers_prepared",
	"parcels": [
		{
			"id": "small package",
			"template": "small",
			"dimensions": {
				"length": "80",
				"width": "360",
				"height": "640",
				"unit": "mm"
			},
			"weight": {
				"amount": "25",
				"unit": "kg"
			},
			"tracking_number": null,
            "is_non_standard": false
		}
	],
	"custom_attributes": {
		"target_point": "KRA010",
		"dropoff_point": null,
		"sending_method": "parcel_locker",
        "dispatch_order_id": 1
	},
	"sender": {
		"id": "123",
		"name": "Nazwa",
		"company_name": "InPost S.A.",
		"first_name": "Jan",
		"last_name": "Nowak",
		"email": "sender@email.com",
		"phone": "888000000",
		"address": {
			"id": "123",
			"street": "Malborska",
			"building_number": "130",
			"city": "Kraków",
			"post_code": "30-624",
			"country_code": "PL"
		}
	},
	"receiver": {
		"id": "123",
		"name": "Nazwa",
		"company_name": null,
		"first_name": null,
		"last_name": null,
		"email": "sender@email.com",
		"phone": "888000000",
		"address": null
	},
	"created_at": "2015-09-06T19:21:00.000+02:00",
	"cod": {
		"amount": 12.50,
		"currency": "PLN"
	},
	"insurance": {
		"amount": 25,
		"currency": "PLN"
	},
	"additional_services": [],
	"reference": "Order No. 12345",
	"is_return": false,
	"tracking_number": null,
    "created_by_id": 3,
    "offers": [
        {
          "id": 1278,
          "carrier": {
              "id": "inpost_locker",
              "name": "InPost Paczkomaty",
			  "description": "InPost Paczkomaty - Przesyłki paczkomatowe."
          },
          "service": {
              "id": "inpost_locker_standard",
              "name": "Paczkomatowa Standardowa",
			  "description": "Przesyłka paczkomatowa standardowa."
          },
          "status": "available",
          "expires_at": "2015-09-06T19:21:00.000+02:00",
          "rate": 2.02,
          "currency": "PLN",
          "unavailability_reasons": null
        }
	],
	"selected_offer": null,
	"transactions": [],
	"sending_method": "parcel_locker",
	"external_customer_id": "8877xxx",
}

Uwierzytelnianie

Dostęp do zasobu wymaga podania prawidłowego i ważnego access tokenu.

Lista przesyłek Organizacji

Lista przesyłek w ramach określonej organizacji.

Info

Aby pobrać listę przesyłek dla określonej organizacji, użytkownik musi być jej członkiem.

Code Block
languagejson
GET /v1/organizations/:organization/shipments


Przykładowe zapytanie

Code Block
languagejson
curl -X GET https://api-shipx-pl.easypack24.net/v1/organizations/1/shipments -H 'Authorization: Bearer token' -H 'Content-Type: application/json'


Odpowiedź

Code Block
languagejson
HTTP/1.1 200 OK 
Content-Type: application/json  
{ 
"href": "https://api-shipx-pl.easypack24.net/v1/organizations/1/shipments", 
  "count": 15, 
  "per_page": 30, 
  "page": 1, 
  "items": [{
    "href": "https://api-shipx-pl.easypack24.net/v1/organizations/1/shipments/1234567890",
    "id": "1234567890",
    "status": "offers_prepared",
    "parcels": [
        {
            "id": "small package",
            "template": "small",
            "dimensions": {
                "length": "80",
                "width": "360",
                "height": "640",
                "unit": "mm"
            },
            "weight": {
                "amount": "25",
                "unit": "kg"
            },
            "tracking_number": null,
            "is_non_standard": false
        }
    ],
    "custom_attributes": {
        "target_point": "KRA010",
        "dropoff_point": null,
        "sending_method": "parcel_locker",
        "dispatch_order_id": 1
    },
    "sender": {
        "id": "123",
        "name": "Nazwa",
        "company_name": "InPost S.A.",
        "first_name": "Jan",
        "last_name": "Nowak",
        "email": "sender@email.com",
        "phone": "888000000",
        "address": {
            "id": "123",
            "street": "Malborska",
            "building_number": "130",
            "city": "Kraków",
            "post_code": "30-624",
            "country_code": "PL"
        }
    },
    "receiver": {
        "id": "123",
        "name": "Nazwa",
        "company_name": null,
        "first_name": null,
        "last_name": null,
        "email": "sender@email.com",
        "phone": "888000000",
        "address": null
    },
    "created_at": "2015-09-06T19:21:00.000+02:00",
    "cod": {
        "amount": 12.50,
        "currency": "PLN"
    },
    "insurance": {
        "amount": 25,
        "currency": "PLN"
    },
    "additional_services": [],
    "reference": "Order No. 12345",
    "is_return": false,
    "tracking_number": null,
    "created_by_id": 3,
    "offers": [
        {
            "id": 1278,
            "carrier": {
                "id": "inpost_locker",
                "name": "InPost Paczkomaty",
                "description": "InPost Paczkomaty - Przesyłki paczkomatowe."
            },
            "service": {
                "id": "inpost_locker_standard",
                "name": "Paczkomatowa Standardowa",
                "description": "Przesyłka paczkomatowa standardowa."
            },
            "status": "available",
            "expires_at": "2015-09-06T19:21:00.000+02:00",
            "rate": 2.02,
            "currency": "PLN",
            "unavailability_reasons": null
        }
    ],
    "selected_offer": null,
    "transactions": [],
    "sending_method": "parcel_locker",
    "external_customer_id": "8877xxx",
  }]
}
Warning

Informacje o błędach

Błędy jakie mogą wystąpić podczas pobierania listy przesyłek:

  • resource_not_found - organizacja, dla której użytkownik chce pobrać listę przesyłek nie istnieje lub nie ma do niej dostępu.