Dokumentacja API serwisu GlobKurier.pl - wersja 1

API GlobKurier jest oparte o architekturę REST. Odpowiedź zwracana jest w formacie JSON. Komunikacja z produkcyjną końcówką jest szyfrowana w SSL. Końcówka testowa działa bez szyfrowania.

Środowiska są rozdzielone. Do korzystania z API testowego wymagane jest posiadanie konta użytkownika produkcyjnego pod warunkiem, że minął dzień od rejestracji bądź aktualizacji profilu (czas propagacji na serwis testowy). Dane testowe ulegają usunięciu na koniec dnia.

Istnieje możliwość wysłania zapytania w formacie JSON z nagłówkiem Content-Type o wartości application/json. W innych przypadkach dla zapytań POST nagłówek ten powinien mieć wartość application/x-www-form-urlencoded.

Dla ułatwienia procesu integracji oraz testowania działania API dokumentacja zawiera interaktywne zapytania.

URL bazowy:

https://api.globkurier.pl/v1

URL testowy:

https://test.api.globkurier.pl/v1

API korzysta z następujących statusów odpowiedzi (RFC 2616):

Lista błędów wyświetlona jest pod dwoma kluczami:

Przykładowa odpowiedź

{
    "general": [
        "Fields postCode or city and street are missing"
    ],
    "fields": {
        "city": "This value is too short. It should have 3 characters or more.",
        "street": "This value is too short. It should have 3 characters or more."
    }
}

Język API wybieramy przesyłając w nagłówku żądania accept-language kodu języka w standardzie ISO 639-1.

Obecnie wspierane języki:

• pl
• en (domyślny)

Poprzez podanie numeru wersji przed nazwą zasobu możemy odwołać się do konkretnej wersji zasobu API. Przykładowo:

GET: http://test.api.globkurier.pl/v1/countries

Wyróżniamy 3 typy zasobów ze względu na autoryzację:

• nie wymagające autoryzacji (np. pobranie listy krajów)
• wymagające autoryzacji (np. pobranie danych swojego konta) oznaczone w dokumentacji ikoną kłódki
• z opcjonalną autoryzacją (np. wyszukiwarka produktów, która zwróci inne produkty dla gościa, a inne dla zalogowanego użytkownika) oznaczone w dokumentacji ikoną filtra

Przejdź do opisu działania autoryzacji.

Dostępne metody możemy pozyskać odpytując dowolny zasób metodą HTTP OPTIONS. Odpowiedź będzie zawierała klucze w nagłówku:

• Access-Control-Allow-Methods - dozwolone metody HTTP zasobu np. OPTIONS, GET
• Access-Control-Allow-Headers - dozwolone nagłówki zasobu np. x-auth-token, accept-language, x-currency

Pozwala to na wcześniejszą weryfikację, czy dany zasób posiada dostęp niewymagający tokenu lub posiadany token uprawnia do niego.
Próba odpytania zasobu niedozwoloną metodą zakończy się statusem błędu 405 Method Not Allowed.

Standardowy cykl użycia autoryzacji:

• Za pomocą zasobu /auth/login pobieramy token.
• Odwołując się do chronionego zasobu przekazujemy pobrany token w nagłówku żądania x-auth-token.
• Ważność tokena autoryzacyjnego to 1 dzień. Istnieją dwa sposoby na przedłużenie ważności autoryzacji:
  • uzyskanie nowego tokena za pomocą zasobu /auth/refresh z użyciem otrzymanego wcześniej tokena
  • ponowna autoryzacja za pomocą /auth/login
• Odpowiednikiem wylogowania się jest zniszczenie ważnego tokena /auth/logout.

Kolejność w schemacie jest przykładowa. Można zastosować inną jeśli odpowiada potrzebom użytkowników.

1. Autoryzacja:

   • Udzielamy możliwości autoryzacji użytkownika
   • Alternatywna opcja to składanie zamówienia jako użytkownik niezalogowany

2. Wyszukanie produktu:

   • Pobieramy listę krajów /countries
   • Użytkownik wybiera kraj nadania i odbioru oraz podaje pozostałe parametry do wyszukiwania produktów
   • Wyszukujemy listę dostępnych produktów /products
   • Użytkownik może wybrać nadanie w punkcie lub przyjazd przewoźnika po przesyłkę w zależności od tego na jaki typ nadania pozwala dany produkt. Będzie to miało wpływ na konieczne do wypełnienia pola (możliwość sprawdzenia za pomocą /order/customRequiredFields)

3. Wybór dodatków do produktu:

   • Pobieramy listę dodatków /product/addons
   • Jeśli zostały wybrane dodatki z kategorii wymienionych w tabeli dodatkowych pól do dodatków udzielamy użytkownikowi możliwości podania ich danych

4. Wybór przedziału czasowego nadania jeśli typ nadania wybrany przez klienta to PICKUP:

   • Pobieramy listę dostępnych przedziałów /order/pickupRanges
   • Wybrany przedział przekazujemy w polu pickup podczas zapisu zamówienia

5. Sprawdzenie dodatkowych pól wymaganych w procesie zamówienia:

   • /order/customRequiredFields możemy wykonywać wielokrotnie - wynik jej działania informuje nas o konieczności przekazadania dodatkowych pól w strukturze zamówienia (nie dotyczy dodatków - pola zależne od kategorii dodatku są ujęte w dokumentacji jw.)

6. Obliczanie ceny zamówienia:

   • /order/price możemy wykonywać wielokrotnie - na podstawie wyniku jej działania informujemy uzytkownika o aktualnej cenie zamówienia

7. Dane adresowe:

   • Aby zapewnić maksymalną spójność kodów pocztowych z miastem dla Polski możemy skorzystać z zasobu adresów na bazie kodów pocztowych
   • Jeśli odpowiedź /order/customRequiredFields informuje nas o tym, że wymagany jest wybór stanu/regionu nadawcy/odbiorcy korzystamy z zasobu /states
   • Jeśli użytkownik wybrał metodę nadania w punkcie możemy pobrać listę dostępnych punktów nadawczych/odbiorczych za pomocą /points

8. Wybór typu płatności:

   • Listę płatności pobieramy za pomocą zasobu /order/payments

9. Deklaracja celna:

   • Pola wymagane przez przewoźnika do złożenia deklaracji celnej przy złożeniu zamówienia /orderCustoms/carrier

10. Częściowa walidacja zamówienia:

    • Korzystając z akcji zasobu /order/validate możemy sprawdzić czy zamówienie zawiera błędy

11. Zapis zamówienia:

    • Jeśli walidacja nie wskazuje błędów można dokonać zapisu zamówienia /order

12. Pozostałe akcje po zapisie:

    • Korzystając z uzyskanego przy zapisie numeru zamówienia można wykonać operacje takie jak np. /order, /order/labels, /order/protocol,

Endpoint

GET: /products

Parametry żądania

Struktura odpowiedzi

Product

Przykładowe żądanie

GET: 

Przykładowa odpowiedź

{
    "standard": [
        {
            "id": 657,
            "carrierName": "Paczka w RUCHu",
            "carrierLogoLink": "http://www.globkurier.pl/materialy/kurier/min/20.png",
            "name": "Paczka w RUCHu do 20 kg",
            "netPrice": 6.74,
            "grossPrice": 8.29,
            "currency": "PLN",
            "collectionTypes": [
                "PICKUP",
                "POINT"
            ],
            "labels": ["Transport drogowy"],
            "protocolAvailable": true,
            "discountCodeAllowed": true,
            "deliveryTime": "2022-04-26",
            "detailsLink": "TEST",
            "promo": "NOWOŚĆ",
            "addonsCategories": []
        },
        {...},
        {...}
    ],
    "noon": [
        {
            "id": 400,
            "carrierName": "UPS",
            "carrierLogoLink": "http://www.globkurier.pl/materialy/kurier/min/28.png",
            "name": "Koperta DOX do 12:00 - UPS",
            "netPrice": 33.08,
            "grossPrice": 40.68,
            "currency": "PLN",
            "collectionTypes": [
                "POINT"
            ],
            "labels": ["Transport drogowy"],
            "protocolAvailable": true,
            "discountCodeAllowed": true,
            "deliveryTime": null,
            "detailsLink": "TEST",
            "promo": null,
            "addonsCategories": [
                "CASH_ON_DELIVERY",
                "INSURANCE",
                "UNREGISTED_USER",
                "RETURN_OF_DOCUMENTS"
            ]
        },
        {...},
        {...}
    ],
    "morning": [
        {
            "id": 401,
            "carrierName": "UPS",
            "carrierLogoLink": "http://www.globkurier.pl/materialy/kurier/min/23.png",
            "name": "Koperta DOX do 9:00 - UPS",
            "netPrice": 75.38,
            "grossPrice": 92.71,
            "currency": "PLN",
            "collectionTypes": [
                "PICKUP",
                "POINT"
            ],
            "labels": ["Transport drogowy"],
            "protocolAvailable": true,
            "discountCodeAllowed": true,
            "deliveryTime": null,
            "detailsLink": null,
            "promo": null,
            "addonsCategories": [
                "SMS_ON_PICKUP",
                "SMS_ON_DELIVERY",
                "PROOF_OD_DELIVERY"
            ]
        },
        {...},
        {...}
    ]
}

Endpoint

GET: /product/addons

Parametry żądania

Struktura odpowiedzi

Addon

Przykładowe żądanie

GET: 

Przykładowa odpowiedź

{
	"addons": [
		{
			"id": 507,
			"addonName": "Doręczenie do firmy",
			"description": null,
			"price": 0,
			"priceDescription": null,
			"category": "RECEIVER_TYPE_COMPANY",
			"isRequired": false,
			"minValue": null,
			"maxValue": null,
			"daysToReturn": null,
			"verificationRequired": false
		},
		{
			"id": 506,
			"addonName": "Doręczenie do osoby prywatnej",
			"description": null,
			"price": 0.3,
			"priceDescription": null,
			"category": "RECEIVER_TYPE_PRIVATE_PERSON",
			"isRequired": false,
			"minValue": null,
			"maxValue": null,
			"daysToReturn": null,
			"verificationRequired": false
		},
		{
			"id": 25,
			"addonName": "Element niestandardowy do 30kg",
			"description": null,
			"price": 14.89,
			"priceDescription": null,
			"category": "NOT_STANDARD",
			"isRequired": false,
			"minValue": null,
			"maxValue": null,
			"daysToReturn": null,
			"verificationRequired": false
		},
		{
			"id": 20,
			"addonName": "Pobranie COD do 20.000 zł",
			"description": null,
			"price": 0.00,
			"priceDescription": "5,6% wartości kwoty",
			"category": "CASH_ON_DELIVERY",
			"isRequired": false,
			"minValue": 0,
			"maxValue": 20000,
			"daysToReturn": 14,
			"verificationRequired": false
		},
		{
			"id": 32,
			"addonName": "Pobranie COD do 11.000 zł w 3 dni",
			"description": null,
			"price": 9,
			"priceDescription": "5,6% wartości kwoty, nie mniej niż 9,00 PLN",
			"category": "CASH_ON_DELIVERY",
			"isRequired": false,
			"minValue": 0,
			"maxValue": 11000,
			"daysToReturn": 3,
			"verificationRequired": false
		},
		{
			"id": 122,
			"addonName": "Pobranie COD do 2.000 zł w 1 dzień",
			"description": null,
			"price": 12,
			"priceDescription": "12,00 PLN +5,6% wartości kwoty",
			"category": "CASH_ON_DELIVERY",
			"isRequired": false,
			"minValue": 0,
			"maxValue": 2000,
			"daysToReturn": 1,
			"verificationRequired": false
		},
		{
			"id": 27,
			"addonName": "Powiadomienie o doręczeniu (e-mail)",
			"description": null,
			"price": 0,
			"priceDescription": null,
			"category": "MAIL_ON_DELIVERY",
			"isRequired": false,
			"minValue": null,
			"maxValue": null,
			"daysToReturn": null,
			"verificationRequired": false
		},
        {...}
	],
	"requiredAlternativeAddons": [
		[
			507,
			506
		]
	]
}

Endpoint

GET: /discountCode

Parametry żądania

Struktura odpowiedzi

Przykładowe żądanie

GET: 

Endpoint

GET: /order/pickupTimeRanges

Parametry żądania

Struktura odpowiedzi

PickupRange

Przykładowe żądanie

GET: 

Przykładowa odpowiedź

[
    {
        "date": "2060-01-01",
        "timeFrom": "08:00",
        "timeTo": "10:00"
    },
    {
        "date": "2060-01-01",
        "timeFrom": "10:00",
        "timeTo": "12:00"
    },
    {...},
    {...}
]

Wszytkie typy platności

Endpoint

GET: /order/payments

Parametry żądania

W przypadku wykorzystania zasobu do sprawdzenia listy dostępnych płatności dla produktu powiązanego z bonem jest wymagany tylko parametr productId. Innym sposobem sprawdzenia możliwości opłacenia zamówienia produktu powiązanego z bonem jest wykorzystanie zasobu /user/couponStats

Struktura odpowiedzi

Payment

Przykładowe żądanie

GET: 

Przykładowa odpowiedź

[
    {
        "id": 2,
        "name": "Płatność online",
        "enabled": true,
        "default": true,
        "price": null
    },
    {...},
    {...}
]

Endpoint pozwala pobrać numery kont bankowych do opłat dla różnych walut.

Endpoint

GET: /payments/bankAccountNumbers

Struktura odpowiedzi

BankAccountNumber

Przykładowe żądanie

GET: 

Przykładowa odpowiedź

[
    {
        "name": "mBank",
        "number": "34 1140 1078 0000 5744 9900 1006",
        "currency": "PLN"
    },
    {...},
    {...}
]

Endpoint

GET: /order/price

Parametry żądania

Odpytanie zasobu dla produktu powiązanego z bonem zwróci błąd gdyż dla takich produktów nie występuje cena zamówienia, ale ilość dostępnych do zamówienia produktów w ramach przyznanego bonu.

Struktura odpowiedzi

Przykładowe żądanie

GET: 

Przykładowa odpowiedź

{
    "totalNetPrice": 13.11,
    "netPriceWithoutFuelSurcharge": 11.71,
    "totalGrossPrice": 16.13,
    "productNetPrice": 11.59,
    "addonsNetPrice": 0,
    "vatPercent": 23,
    "discountNetPrice": 0
    "fuelSurcharge": 0
}

Pozwala ustalić czy należy przesłać dodatkowe pola z danymi korzystając z zasobu /order

Endpoint

GET: /order/customRequiredFields

Parametry żądania

Struktura odpowiedzi

Przykładowe żądanie

GET: 

Przykładowa odpowiedź

{
	"senderAddressPointId": true,
	"receiverAddressPointId": true,
	"declaredValue": false,
	"purpose": false,
	"pickupDate": false,
	"pickupTimeFrom": false,
	"pickupTimeTo": false,
	"senderStateId": false,
	"receiverStateId": false,
    "orderCustoms": {
            "fields": [
                {
                    "label": "Declared value",
                    "type": "number",
                    "placeholder": "Enter declared value",
                    "name": "declaredValue",
                    "value": null,
                    "required": true,
                    "tooltip": "Shipment's declared value",
                    "multi": null,
                    "expanded": null,
                    "options": null
                },
                {
                    "label": "terms of delivery",
                    "type": "text",
                    "placeholder": "Enter terms of delivery",
                    "name": "termsOfDelivery",
                    "value": "DDP",
                    "required": true,
                    "tooltip": "Standards used in trade contracts to define the terms of delivery of goods should be used, e.g. DDP",
                    "multi": null,
                    "expanded": null,
                    "options": null
                },
                {
                    "label": "purpose",
                    "type": "select",
                    "placeholder": null,
                    "name": "purpose",
                    "value": "samples",
                    "required": true,
                    "tooltip": "purpose of dispatch",
                    "multi": false,
                    "expanded": false,
                    "options": [
                        {
                            "name": "samples",
                            "selected": true,
                            "value": "samples",
                            "tooltip": null
                        },
                        {
                            "name": "gift",
                            "selected": false,
                            "value": "gift",
                            "tooltip": "a gift"
                        }
                    ]
                }
            ]
        }
}

Endpoint

POST: /order/validate

Niektóre Parametry żądania

Struktura treści żądania jest taka sama jak w /order
Rożnicą jest, że pola są niewymagane lub na tą chwilę nieobsługiwane przez walidację.
Poniżej znajdują się przykładowe obsługiwane pola z informacją o ich walidacji.

Przykładowe żądanie

Przykładowa odpowiedź

{
    "fields": {
        "userAddress[nip]": "Not valid TIN given. Please enter the correct details or contact us.",
        "userAddress[countryId]": "This value is not valid natural number.",
    }
}

Endpoint

POST: /order

Parametry żądania

Shipment

Address

Address/UserAddress

Pickup

Addon

Customs

Customs sender

Customs receiver

Commodity

Przykładowe żądanie

Przykładowa odpowiedź

W odpowiedzi otrzymujemy numer, hash złożonego zamówienia oraz informacje o wycenie złożonego zamówienia lub listę błędow walidacji.

{
    "number": "GK161014996110",
    "hash":  "830f3038d3efey5edfec286e10c83add99d103e4bdc237c50335724c031e395f",
    "price": {
        "currency": "PLN",
        "totalNetPrice": 123,
        "netPriceWithoutFuelSurcharge": 123,
        "totalGrossPrice": 123,
        "productNetPrice": 123,
        "addonsNetPrice": 0,
        "vatPercent": 0,
        "discountNetPrice": 0,
        "fuelSurcharge": 0
    }
}

Uproszczony formularz składania zamówienia pozwala na złożenie zamówienia bez znajomości ID produktu oraz ID kraju.

Za pomocą nazwy integracji (integrationName) oraz kodu kraju (Kod ISO, bądź kod strefy) automat sam dobierze niezbędne parametry.

Niewymagana jest także znajomość ID dodatków. Wystarczy przekazać ich kategorie, a system sam dobierze wymagane dodatki.

Poniżej znajduje się lista zmienionych pól, które uległy zmianie w stosunku do składania zamówienia.

Endpoint

POST: /order/bestPrice

Parametry żądania

Przykładowe żądanie

Przykładowa odpowiedź

W odpowiedzi otrzymujemy numer, hash złożonego zamówienia oraz informacje o wycenie złożonego zamówienia lub listę błędow walidacji.

{
    "number": "GK161014996110",
    "hash":  "830f3038d3efey5edfec286e10c83add99d103e4bdc237c50335724c031e395f",
    "price": {
        "currency": "PLN",
        "totalNetPrice": 123,
        "netPriceWithoutFuelSurcharge": 123,
        "totalGrossPrice": 123,
        "productNetPrice": 123,
        "addonsNetPrice": 0,
        "vatPercent": 0,
        "discountNetPrice": 0,
        "fuelSurcharge": 0
    }
}

Endpoint

POST: /order/productTemplate

Parametry żądania

Shipment

Struktura odpowiedzi

Przykładowe żądanie

Przykładowa odpowiedź

{"id": "1"}

Endpoint

GET: /order/productTemplate

Endpoint udostępnia paginację. Parametry z nią związane są opisane tutaj.

Dostępne filtry

Struktura odpowiedzi

ProductTemplate

Przykładowe żądanie

GET: 

Przykładowa odpowiedź

                    {
                        "offset": 0,
                        "total": 3,
                        "limit": 25,
                        "results": [
                            {
                                "id": 1,
                                "name": "test",
                                "created": "2018-09-01 12:00:00",
                                "updated": null,
                                "content": "content",
                                "length": 2,
                                "width": 3,
                                "height": 4,
                                "weight": 5.25,
                                "quantity": 6,
                                "senderCountryId": 1,
                                "receiverCountryId": 1,
                                "productId": 1,
                                "productName": "Package up to 30kg",
                                "senderAddress": null,
                                "receiverAddress": null
                            },
                            {...},
                            {...}
                        ]
                    }

Endpoint

PUT: /order/productTemplate

Parametry żądania

Shipment

Struktura odpowiedzi

Zasób zwraca status 204 po zapisaniu danych.

Przykładowe żądanie

PUT: 

Endpoint

DELETE: /order/productTemplate

Parametry żądania

Przykładowe żądanie

DELETE: 

Przykładowa odpowiedź

"OK"

Płatności online mogą być obarczone stałą prowizją 1% od wartości zamówienia. Wartość ta nie pojawia się w momencie wyświetlenia listy płatności z metody pobrania płatności.

GET: /onlinePayment/methods

[
   {
      "id" : 34,
      "imagePath" : "http://www.globkurier.pl/images/online-banks/alior.png"
      "name" : "Alior Bank",
      "isDeferred": false,
      "currencies": "PLN",
      "isAvailable": true,
      "message": null
   },
   {
      "id" : 95,
      "name" : "Karta płatnicza MasterCard"
      "imagePath" : "http://www.globkurier.pl/images/online-banks/mastercard.png",
      "isDeferred": false,
      "currencies": "EUR,USD,GBP,CZK,HUF,RON,RUB",
      "isAvailable": false,
      "message": "Ten kanał płatności nie obsługuje wybranej waluty."
   }
]

Endpoint

Nadawcy:

POST: /user/addressBook/sender

Odbiorcy:

POST: /user/addressBook/receiver

Parametry żądania

Struktura odpowiedzi

Przykładowe żądanie

Przykładowa odpowiedź

{"id": "1"}

Endpoint nadawcy

GET: /user/addressBook/senders

Endpoint odbiocy

GET: /user/addressBook/receivers

Parametry żądania

Endpoint udostępnia paginację. Parametry z nią związane są opisane tutaj.

Dostępne filtry

Struktura odpowiedzi

Jest zgodna z paginacją

W parametrze results zawierać będzie się lista kontaktów.

Struktura odpowiedzi - kontakt

Przykładowe żądanie

GET: 

Przykładowa odpowiedź

{
    "offset": 0,
    "total": 1,
    "limit": 25,
    "results": [
        {
            "id": "1",
            "name": "Test Contact",
            "email": "it@globkurier.pl",
            "street": "Testowa",
            "houseNumber": "1",
            "apartmentNumber": "25",
            "postCode": "42-226",
            "city": "Cz\u0119stochowa",
            "phone": "48111222333",
            "contactPerson": "contact person",
            "tin": "9541875594",
            "editable": "true"
        }
    ]
}

Endpoint

Nadawcy:

PUT: /user/addressBook/sender

Odbiorcy:

PUT: /user/addressBook/receiver

Parametry żądania

Struktura odpowiedzi

Zasób zwraca status 204 po zapisaniu danych.

Przykładowe żądanie

Endpoint

Nadawcy:

DELETE: /user/addressBook/sender

Obiorcy:

DELETE: /user/addressBook/receiver

Parametry żądania

Przykładowe żądanie

DELETE: 

Przykładowa odpowiedź

"OK"

Endpoint

GET: /user/profile

Struktura odpowiedzi

Notifications

CashOnDelivery

Przykładowe żądanie

GET: 

Przykładowa odpowiedź

{
    "userNumber": 1234567,
    "isAccountBlocked": false,
    "cashOnDelivery": {
        "bankAccountNumber": "",
        "name": "",
        "addressLine1": "",
        "addressLine2": ""
    },
    "address": {
        "regon": null,
        "nip": null,
        "name": "Imię",
        "surname": "Nazwisko",
        "street": "Testowa",
        "apartmentNumber": "2D",
        "houseNumber": "2",
        "city": "Katowice",
        "postCode": "42-226",
        "countryId": 1,
        "phone": "48111222333",
        "email": "test3@testmail.pl",
        "companyName": null,
        "type": "PERSON"
    },
    "subUserAddress": null,
    "taxesArePaidAbroad": false,
    "notifications": {
        "sendInvoicesToOtherEmail": false,
        "otherEmailForInvoices": null,
        "sendPaperInvoices": false,
        "sendDiscountCodes": true,
        "sendLabel": true,
        "sendInfoOnSubAccountOrderCreation": true,
        "sendInfoOnSubAccountProformaInvoiceCreation": true,
        "sendInfoOnTrackingStatusUpdate": false,
        "sendInfoOnTrackingStatusUpdateToReceiver": true,
        "sendInfoOnOrderCreation": true
    },
    "agreements": {
        "receiveCommercialInfo": true
    }
}

Endpoint

GET: /user/couponStats

Parametry żądania

Struktura odpowiedzi

Period

Przykładowe żądanie

GET: 

Przykładowa odpowiedź

{
	"isCouponPaymentAvailable": true,
	"couponGrantDate": "2015-01-12",
	"globalAllowedProductsQuantity": 12,
	"globalUsedProductsQuantity": 1,
	"firstDayOfMonthAvailableToOrder": null,
	"lastDayOfMonthAvailableToOrder": null,
	"period": {
		"allowedProductsQuantity": 2,
		"usedProductsQuantity": 1,
		"startDate": "2017-03-12",
		"endDate": "2017-04-12"
	}
}

Endpoint

POST: /user

Parametry żądania

Agreements

Kod reCAPTCHA

W celu weryfikacji człowieczeństwa osoby tworzącej konto API korzysta z mechanizmu captcha za pomoca narzędzia reCAPTCHA. Aby wygenerować kod wymagany do rejestracji, należy dodać następujący nagłówek:

<script src="//www.google.com/recaptcha/api.js?hl=pl" async defer></script>

oraz w formularzu umieścić kod reCAPTCHA i obsłużyć odpowiedź. Przykładowa obsługa może wyglądać następująco:

<script>
    function captchaResponseHandler(response) {
        console.log(response); //zapis i obsługa odpowiedzi
    }
</script>

<div class="g-recaptcha"
     data-sitekey="6LdPuicTAAAAAGBs4H_N5aPjylxnD4yiSQIN3y0n"
     data-callback="saveResponse"></div>

Pełna dokumentacja reCaptcha znajduje się tutaj.

Struktura odpowiedzi

Przykładowe żądanie

Przykładowa odpowiedź

W odpowiedzi otrzymujemy numer utworzonego konta klienta oraz aktywny token autoryzacyjny.

{
    "number": "3747813",
    "token": "1a10a42dcb5065478c6f49f68493f5ddeb31cadcfacbe5ad25aa1cd3564b895e"
}

Endpoint

GET: /user/company

Parametry żądania

Przykładowe żądanie

GET: 

Endpoint

GET: /user/invoices

Endpoint udostępnia paginację. Parametry z nią związane są opisane tutaj. Paginacja tego endpointu umożliwia jednak przeszukiwanie tylko pełnych stron. Zatem offset musi być podzielny przez liczbę wyników na stronie.

Dostępne filtry

Struktura odpowiedzi

Invoice

InvoiceEmail

Przykładowe żądanie

GET: 

Przykładowa odpowiedź

{
  "offset": 0,
  "total": 3,
  "limit": 25,
  "results": [
    {
        "hash": "104745b285bedbb667c59b135d9b9a74770af9bf",
        "link": "https://api.globkurier.pl/v1/invoice?hash=104745b285bedbb667c59b135d9b9a74770af9bf",
        "number": "1/GK/K/01/2017",
        "orderNumbers": ["GK161014996110","GK161014996111"],
        "priceGross": 65.33,
        "priceNet": 53.11,
        "vatPLN": 12.22,
        "amountToPay": 0,
        "currency": "PLN",
        "currencyRate": 1,
        "issueDate": "2017-01-31 07:00:00",
        "orderDate": "2017-01-31",
        "paymentDueDate": "2017-02-14",
        "settlementDate": "2017-02-17",
        "emails": [
            {
              "id": 1234,
              "email": "example@example.com",
              "title": "Wystawiono nowy dokument",
              "date": "2017-01-31T07:00:05",
              "typeId": 0,
              "type": "DOCUMENT_ISSUED"
            },
            {...}
        ],
        "isPayableByOnline": false,
        "isPayableByPrepaid": true
    },
    {...},
    {...}
  ]
}

Endpoint

GET: /invoice

Parametry żadania

Przykładowe żądanie

GET: 

Endpoint

GET: /invoice/email

Parametry żadania

Przykładowe żądanie

GET: 

Endpoint

GET: /user/stats

Struktura odpowiedzi

StatsSummary

StatsValue

Przykładowe żądanie

GET: 

Przykładowa odpowiedź

{
        "prepaidBalance": {
            "name": "Stan konta prepaid",
            "value": 30.00,
            "currency": "EUR"
        },
        "receivablePayment": {
            "name": "Zaległe płatności",
            "values": [
                {
                    "value": 1818.27,
                    "currency": "PLN"
                },
                {
                    "value": 10.00,
                    "currency": "EUR"
                },
            ]
        },
        "packageCountInCurrentMonth": {
            "name": "Liczba przesyłek w tym miesiącu",
            "value": 3,
            "currency": "EUR"
        },
        "savedPayments": {
            "name": "Ile zaoszczędziłeś z GlobKurier",
            "value": 300.00,
            "currency": "EUR"
        },
        "overdueCashOnDelivery": {
            "name": "Zaległe płatności przy doręczeniu",
            "values": [
                {
                    "value": 46.01,
                    "currency": "PLN"
                }
            ]
        },
        "excessPayment": {
            "name": "Nadpłata",
            "values": [
                {
                    "value": 20.1,
                    "currency": "PLN"
                }
            ]
    }
}

Metoda zachowuje się podobnie do pobierania płatności.

Zwraca listę dostępnych metod płatności dla zalogowanego użytkownika

Endpoint

GET: /user/payment/methods

Struktura odpowiedzi

Przykładowe żądanie

GET: 

Przykładowa odpowiedź

[
    {
        "id": 2,
        "name": "Płatność online",
        "enabled": true,
        "default": true,
        "price": null
    },
    {...},
    {...}
]

Zwraca informacje o metodzie płatności zapisanej przez użytkownika

Endpoint

GET: /user/payment/default

Struktura odpowiedzi

Przykładowe żądanie

GET: 

Przykładowa odpowiedź

{
    "paymentId": 2,
    "onlinePaymentId": 1
}

Endpoint

POST: /user/payment/default

W odpowiedzi zwracany jest kod 201 lub informacja o błędach dla każego z pól

Przykładowe żądanie

Endpoint

DELETE: /user/payment/default

W odpowiedzi zwracany jest jest kod 204 jeśli zapytanie jest prawidłowe.

Przykładowe żądanie

DELETE: 

Endpoint

GET: /countries

Struktura odpowiedzi

Country

Przykładowe żądanie

GET: 

Przykładowa odpowiedź

[
    {
        "id": 101,
        "name": "Angola",
        "isoCode": "AO",
        "isUEMember": false,
        "isRoadTransportAvailable": false,
        "hasStates": false,
        "hasPostCodes": false,
        "postCodeFormat" : null,
        "postCodeSamples" : null
    },
    {
        "id": 28,
        "name": "Szkocja",
        "isoCode": "GB3",
        "isUEMember": true,
        "isRoadTransportAvailable": true,
        "hasStates": false,
        "hasPostCodes": true,
        "postCodeFormat" : "a? ?aa, a?? ?aa, a?a ?aa, aa? ?aa, aa?? ?aa, aa?a ?aa",
        "postCodeSamples" : "A1 2BC, D34 5EF, G6H 7IJ, KL8 9MN, OP12 3QR, ST4U 5VW"
    },
    {...},
    {...}
]

Zwraca zakresy polskich adresów na bazie przesłanych parametrów. Funkcjonalność wspierająca automatyczne uzupełnianie miasta na bazie kodu pocztowego. Można wyszukiwać adres podając kod pocztowy lub miasto i ulicę.

Endpoint

GET: /addresses

Parametry żądania

Struktura odpowiedzi

Address

Przykładowe żądanie

GET: 

Przykładowa odpowiedź

[
    {
        "postCode": "42-110",
        "state": "śląskie",
        "city": "Popów",
        "street": "ul. Popów 48"
    },
    {...},
    {...}
]

Funkcjonalność wykorzystujemy jeśli wywołanie /customRequiredFields wskazuje iż konieczne jest podanie stanu nadawcy lub odbiorcy w procesie zapisu/walidacji zamówienia.

Endpoint

GET: /states

Parametry żądania

Struktura odpowiedzi

State

Przykładowe żądanie

GET: 

Przykładowa odpowiedź

[
    {
        "id": 49,
        "code": "AK",
        "isoCode": "US-AK",
        "name": "Alaska",
        "localName": "Alaska"
    },
    {...},
    {...}
]

Endpoint

GET: /points

Parametry żądania

Struktura odpowiedzi

Point

Przykładowe żądanie

GET: 

Przykładowa odpowiedź

[
    {
        "id": "197550",
        "address": "Elektronowa 1",
        "city": "Zielona Góra",
        "postCode": "65-900",
        "openingHours": null,
        "cashOnDeliveryAvailable": true
    },
    {...},
    {...}
]

Endpoint

GET: /order

Parametry żądania

Struktura odpowiedzi