Glossary

API

Application programming interface - programming gateway. Will be used to integrate customers service (online shop, etc.) with bliskapaczka.pl.

API key

Your personal and private key to access and authenticate API communication.

Operator

Specific bliskapaczka.pl partner whom parcel pick up and delivery will be delegated to.

POS or Point

Point of Service - partners point where customer can send or pick up a parcel sent using bliskapaczka.pl service.

Production environment

An environment where real-time ready to use system is hosted. Should not be use for testing purpose, every operation cause real communication with bliskapaczka.pl partners and eventually creation of real orders.

Sandbox environment

Isolated independent environment for testing purpose. None of the operations on this environment would be sent to partners production environments and would not create real orders.

Widget

JavaScript component containing a map with POSes list, used by customer to choose the place, where the parcel will be delivered to.

Overview

Bliskapaczka.pl provides an easy and convenient way for integration.
This documentation describes integration protocol {api-version} of bliskapaczka.pl based on REST API.

Integration process consists of following steps:

  1. create the account at bliskapaczka.pl services

  2. request access to API integration

  3. place bliskapaczka.pl widget on your page to provide to your clients an easy way to pick up delivery points

  4. implement communication with bliskapaczka.pl via API to be able to create order, process it and monitor its status

All those steps will be detailed described later in current documentation.

Environments:

Look here for detailed API documentation.

Contact with technical support regarding integration process integracje@bliskapaczka.pl

How to get access to API bliskapaczka.pl?

  1. Register regular account on the service:

  2. Send an email message to integracje@bliskapaczka.pl using the email your account is registered with request to provide you access to integration functionality.
    Such email could looks like:

    Hi,
    
    Please provide me the access to integration functionality on the account registered on my email.
    
    Sincerely yours,
    [name]
  3. After successful proceeding your request you should receive a confirmation email.

  4. After re-login, you should be able to find the "Integracja" tab in your account settings:

    Before generating API key
  5. Generate your personal API key using the "Wygeneruj klucz API" button.

    Please keep in mind this key is a part of sensitive data and should be kept in a private place also please do not share it with anyone. In case of suspicion that your key may be used by any unauthorized person, please contact us at integracje@bliskapaczka.pl immediately with the request to remove the old key, so you can generate a new one.
  6. New key should look like this:

    After generating API key
    You can copy the key to the clipboard using "SKOPIUJ DO SCHOWKA" button.
  7. Received key will be used to authenticate your API requests. To sign your requests please add following HTTP header to each API request:

Authorization: Bearer {apiKey}

where in place of {apiKey} you should use your own key, e.g.:

Authorization: Bearer 00d92e6b-xxxx-4318-841e-6cdc414a49d3

How to use bliskapaczka.pl Widget?

Current documentation refers to widget version: v5.4
Widget demo can be found https://widget.bliskapaczka.pl/prod/demo.html
Latest documentation can be found: https://widget.bliskapaczka.pl

  1. In order to install bliskapaczka.pl Widget on your web page include following code snippets in head section of your html document:

    <script type="text/javascript" src="https://widget.bliskapaczka.pl/v5.4/main.js"></script>
    <link rel="stylesheet" href="https://widget.bliskapaczka.pl/v5.4/main.css" />
  2. bliskapaczka.pl Widget exposes one object through global variable BPWidget. To initialize widget use method:

    BPWidget.prototype.init(element, options)

    First argument is html element that should hold widget content. Element has to have width and height defined and should be displayed on page when map is initialized. E.g.

    <div id="bpWidget" style="height: 800px; width: 1024px;"></div>
  3. To get Widget to work, you must provide google maps API key in widget options object. The widget takes an options object as the second argument of init() method. You can use example google maps api key for testing purposes:

    BPWidget.init(
      document.getElementById('bpWidget'),
      {
        googleMapApiKey: 'AIzaSyCUyydNCGhxGi5GIt5z5I-X6hofzptsRjE'
      }
    );
  4. In case you would like to display to your customers only points where the shipment can be delivered, you may use posType option:

    BPWidget.init(
      document.getElementById('bpWidget'),
      {
        googleMapApiKey: 'AIzaSyCUyydNCGhxGi5GIt5z5I-X6hofzptsRjE',
        posType: 'DELIVERY'
      }
    );
  5. To allow your customers to select point on map, provide callback function in Widget callback option:

    BPWidget.init(
      document.getElementById('bpWidget'),
      {
        googleMapApiKey: 'AIzaSyCUyydNCGhxGi5GIt5z5I-X6hofzptsRjE',
        posType: 'DELIVERY',
        callback: function(point) {
          console.log("selected point operator: ", point.operator);
          console.log("selected point code: ", point.code);
        }
      }
    )

Pricing API, configuration panel and displaying shipping prices in widget

  1. If you are able to provide parcel dimensions based on size of products, you can use our pricing API to can calculated offer of bliskapaczka.pl order

    curl -X POST https://api.sandbox-bliskapaczka.pl/{api-version}/pricing \
      -H "Content-Type: application/json" \
      -H "Accept: application/json" \
      -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx" \
      -d '{
        "parcel": {
          "dimensions": {
            "length": 20,
            "width": 20,
            "height": 40,
            "weight": 0.9
          },
          "codValue":101.50,
          "insuranceValue":101.50
        }
      }'

    In response, you receive the list of operators, with an offer for each one or information that operator is unavailable together with reason:

    [{
            "operatorName": "INPOST",
            "availabilityStatus": true,
            "serviceName": "Typ A",
            "price": {
                "net": 6.74,
                "vat": 1.55,
                "gross": 8.29
            },
            "unavailabilityReason": null
        },
        {
            "operatorName": "RUCH",
            "availabilityStatus": true,
            "serviceName": "Mini",
            "price": {
                "net": 4.06,
                "vat": 0.93,
                "gross": 4.99
            },
            "unavailabilityReason": null
        },
        {
            "operatorName": "POCZTA",
            "availabilityStatus": false,
            "serviceName": null,
            "price": null,
            "unavailabilityReason": {
                "errors": [{
                    "messageCode": "ppo.api.error.pricing.algorithm.constraints.dimensionsTooSmall",
                    "message": "Allowed parcel dimensions too small. Min dimensions: 16x10x1 cm",
                    "field": null,
                    "value": null
                }]
            }
        }
    ]

    An operator can be unavailable because of one of the following reasons:

    • provided dimensions exceeds operator limits

    • operator was disabled at bliskapaczka.pl account configuration panel

  2. You can modify the list of available operators or shipping prices depending on your needs. To change that option, you can use 'Integracja' tab of your bliskapaczka.pl account configuration panel.

    Available operators integration panel
    Prices integration panel
  3. You can manipulate operators available on bliskapaczka.pl widget or display shipment prices for end user convenience, e.g. using information from bliskapaczka.pl pricing api. To do so use operators option.

    Option operators as value can take an array of objects with following properties:

    • operator [required] - operator code name

    • price [optional] - price of the shipment, that would be displayed for this operator

      Currently supported operators: RUCH, INPOST, POCZTA, DPD.

      Example:

      BPWidget.init(
          document.getElementById('bpWidget'), {
              googleMapApiKey: 'AIzaSyCUyydNCGhxGi5GIt5z5I-X6hofzptsRjE',
              posType: 'DELIVERY',
              callback: function(point) {
                  console.log("selected point:", point);
              },
              operators: [
                  {
                      operator: "RUCH",
                      price: 5
                  },
                  {
                      operator: "INPOST"
                  }
              ]
          }
      );

Order API

  1. To create an order, first you need to gather information regarding posting/delivery points, sender and receiver data. You can take it from widget callback or from any other source. Having all required informations, you can use API to create order:

    curl -X POST https://api.sandbox-bliskapaczka.pl/{api-version}/order \
      -H "Content-Type: application/json" \
      -H "Accept: application/json" \
      -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx" \
      -d '{
        "number":"000000000P-000000000",
        "senderFirstName":"Sender",
        "senderLastName":"Sender",
        "senderPhoneNumber":"123456789",
        "senderEmail":"sender@example.com",
        "senderStreet":"Rynek",
        "senderBuildingNumber":"1",
        "senderFlatNumber":"1",
        "senderPostCode":"00-000",
        "senderCity":"Wroclaw",
        "receiverFirstName":"Receiver",
        "receiverLastName":"Receiver",
        "receiverPhoneNumber":"987654321",
        "receiverEmail":"receiver@example.com",
        "operatorName":"INPOST",
        "destinationCode":"KRA010",
        "postingCode":"KRA011",
        "additionalInformation": "Some additional information",
        "parcels":[{
          "dimensions":{
            "height":20,
            "length":20,
            "width":20,
            "weight":20
          },
          "insuranceValue":100
        }],
        "codValue":110,
        "codPayoutBankAccountNumber":"16102019120000910201486273"
      }'

    Example response:

    {
        "number": "000000001P-000000006",
        "senderFirstName": "Sender",
        "senderLastName": "Sender",
        "senderPhoneNumber": "123456789",
        "senderEmail": "sender@example.com",
        "senderStreet": "Rynek",
        "senderBuildingNumber": "1",
        "senderFlatNumber": "1",
        "senderPostCode": "00-000",
        "senderCity": "Wroclaw",
        "receiverFirstName": "Receiver",
        "receiverLastName": "Receiver",
        "receiverPhoneNumber": "987654321",
        "receiverEmail": "receiver@example.com",
        "receiverStreet": "Ulica",
        "receiverBuildingNumber": "1A",
        "receiverFlatNumber": "2B",
        "receiverPostCode": "99-999",
        "receiverCity": "Kraków",
        "receiverCountryCode": "PL",
        "operatorName": "INPOST",
        "destinationCode": "KRA010",
        "postingCode": "KRA011",
        "additionalInformation": null,
        "parcels": [{
            "dimensions": {
                "length": 20,
                "height": 20,
                "width": 20,
                "weight": 20
            },
            "insuranceValue": null
        }],
        "codValue":110,
        "codPayoutBankAccountNumber":"16102019120000910201486273",
        "status": "SAVED",
        "deliveryType": "TO_POINT",
        "creationDate": "2017-06-28T15:00:31.254",
        "adviceDate": null,
        "trackingNumber": null,
        "postingPostCode": "31-274",
        "postingCity": "Kraków",
        "postingStreet": "Opolska 9",
        "destinationPostCode": "30-624",
        "destinationCity": "Kraków",
        "destinationStreet": "Malborska 130",
        "orderItems": [],
        "price": null
    }

    An order created this way will be in state SAVED, which means that it is still available for modifications. It can be done via user interface on bliskapaczka.pl or by sending same request with modified values, and field number set to value received in response.

  2. To advise an order, first you need to gather information regarding posting/delivery points, sender, receiver. You can take them from widget callback or from any other source. Having all required informations, you can use API to advise order:

    curl -X POST https://api.sandbox-bliskapaczka.pl/{api-version}/order/advice \
      -H "Content-Type: application/json" \
      -H "Accept: application/json" \
      -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx" \
      -d '{
        "number":"000000000P-000000000",
        "senderFirstName":"Sender",
        "senderLastName":"Sender",
        "senderPhoneNumber":"123456789",
        "senderEmail":"sender@example.com",
        "senderStreet":"Rynek",
        "senderBuildingNumber":"1",
        "senderFlatNumber":"1",
        "senderPostCode":"00-000",
        "senderCity":"Wroclaw",
        "receiverFirstName":"Receiver",
        "receiverLastName":"Receiver",
        "receiverPhoneNumber":"987654321",
        "receiverEmail":"receiver@example.com",
        "operatorName":"INPOST",
        "destinationCode":"KRA010",
        "postingCode":"KRA011",
        "additionalInformation": "Some additional information",
        "parcels":[{
          "dimensions":{
            "height":20,
            "length":20,
            "width":20,
            "weight":20
          }
        }],
        "codValue":110,
        "codPayoutBankAccountNumber":"16102019120000910201486273"
      }'

    Example response:

    {
        "number": "000000001P-000000007",
        "senderFirstName": "Sender",
        "senderLastName": "Sender",
        "senderPhoneNumber": "123456789",
        "senderEmail": "sender@example.com",
        "senderStreet": "Rynek",
        "senderBuildingNumber": "1",
        "senderFlatNumber": "1",
        "senderPostCode": "00-000",
        "senderCity": "Wroclaw",
        "receiverFirstName": "Receiver",
        "receiverLastName": "Receiver",
        "receiverPhoneNumber": "987654321",
        "receiverEmail": "receiver@example.com",
        "receiverStreet": "Ulica",
        "receiverBuildingNumber": "1A",
        "receiverFlatNumber": "2B",
        "receiverPostCode": "99-999",
        "receiverCity": "Kraków",
        "receiverCountryCode": "PL",
        "operatorName": "INPOST",
        "destinationCode": "KRA010",
        "postingCode": "KRA011",
        "additionalInformation": null,
        "parcels": [{
            "dimensions": {
                "length": 20,
                "height": 20,
                "width": 20,
                "weight": 20
            },
            "insuranceValue": null
        }],
        "codValue":110,
        "codPayoutBankAccountNumber":"16102019120000910201486273",
        "status": "PROCESSING",
        "deliveryType": "TO_POINT",
        "creationDate": "2017-06-28T15:13:35.592",
        "adviceDate": null,
        "trackingNumber": null,
        "postingPostCode": "31-274",
        "postingCity": "Kraków",
        "postingStreet": "Opolska 9",
        "destinationPostCode": "30-624",
        "destinationCity": "Kraków",
        "destinationStreet": "Malborska 130",
        "orderItems": [{
            "pricelistItemType": "SHIPMENT",
            "serviceName": "Typ C",
            "price": {
                "net": 8.35,
                "vat": 1.92,
                "gross": 10.27
            }
        }],
        "price": null
    }

    An order is in state PROCESSING, which means that it is not available for modifications and advising process has been started.

  3. You can retrieve order information from API using order number provided in save/advice operation response:

    curl -X GET https://api.sandbox-bliskapaczka.pl/{api-version}/order/000000001P-000000007 \
      -H "Accept: application/json" \
      -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

    Example response:

    {
        "number": "000000001P-000000007",
        "senderFirstName": "Sender",
        "senderLastName": "Sender",
        "senderPhoneNumber": "123456789",
        "senderEmail": "sender@example.com",
        "senderStreet": "Rynek",
        "senderBuildingNumber": "1",
        "senderFlatNumber": "1",
        "senderPostCode": "00-000",
        "senderCity": "Wroclaw",
        "receiverFirstName": "Receiver",
        "receiverLastName": "Receiver",
        "receiverPhoneNumber": "987654321",
        "receiverEmail": "receiver@example.com",
        "receiverStreet": "Ulica",
        "receiverBuildingNumber": "1A",
        "receiverFlatNumber": "2B",
        "receiverPostCode": "99-999",
        "receiverCity": "Kraków",
        "receiverCountryCode": "PL",
        "operatorName": "INPOST",
        "destinationCode": "KRA010",
        "postingCode": "KRA010",
        "additionalInformation": null,
        "parcels": [{
            "dimensions": {
                "length": 20,
                "height": 20,
                "width": 20,
                "weight": 20
            },
            "insuranceValue": null
        }],
        "codValue":110,
        "codPayoutBankAccountNumber":"16102019120000910201486273",
        "status": "READY_TO_SEND",
        "deliveryType": "TO_POINT",
        "creationDate": "2017-06-28T15:30:04.078",
        "adviceDate": "2017-06-28T15:30:10.39",
        "trackingNumber": "2065149336",
        "postingPostCode": "30-624",
        "postingCity": "Kraków",
        "postingStreet": "Malborska 130",
        "destinationPostCode": "30-624",
        "destinationCity": "Kraków",
        "destinationStreet": "Malborska 130",
        "orderItems": [{
            "pricelistItemType": "SHIPMENT",
            "serviceName": "Typ C",
            "price": {
                "net": 8.35,
                "vat": 1.92,
                "gross": 10.27
            }
        }],
        "price": {
            "net": 8.35,
            "vat": 1.92,
            "gross": 10.27
        }
    }
  4. You can retrieve order waybill document from api using order number provided in save/advice operation response:

    curl -X GET https://api.sandbox-bliskapaczka.pl/{api-version}/order/000000001P-000000007/waybill \
      -H "Accept: application/json" \
      -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

    Example response:

    {
        "url": "https://storage.googleapis.com/test.cloud.senditstatic.pl/ppo/inpost/waybill/2017/06/26/000000001P-000000008.pdf?GoogleAccessId=storage@archiwum-140107.iam.gserviceaccount.com&Expires=1499299200&Signature=N50f96tIEP4RHsAvpFBRhjNp%2Fw8z5gS%2B0yzQnc8%2BTFOw9u9HLgulq6GZXpPPxQfzp1GxbeHIehNigYQYIOIi3juxbxTydhlLUGC0dwdpuoNrvJUrSH%2BKhNufo7LrGU3GNCG6cMUIv1XhnA%2BY3SKul1Ee4nfzGjHOD%2FMZJYJOkcZYJDO6krH%2FDB%2FL36ylE2cVJR53%2F4H%2FhajljMH8r80He8OFY8e8q7UZoZx9oQiyaDftaoJfqB5PItJewuNqd8Zyx8lOwFyactGkU9kVisnf%2FN%2Fz2fp6BnNVzhdXQCYCwKVURaVWyY5UJg4fG86qfyNczC60uOWo4e%2F08%2FQqLMQkFQ%3D%3D"
    }

    Response JSON contains signed URL to google storage, where waybill is available for download. URL has the lifetime of 7 days, after this time it is required to generate a new one. Waybill is stored in google storage in PDF format.

  5. You can retrieve order tracking from api using order number provided in save/advice operation response:

    curl -X GET https://api.sandbox-bliskapaczka.pl/{api-version}/order/000000001P-000000007/tracking \
      -H "Accept: application/json" \
      -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

    Example response:

    {
        "changes": [{
                "dateTime": "2017-06-28T15:30:04.033",
                "status": "SAVED"
            },
            {
                "dateTime": "2017-06-28T15:30:04.11",
                "status": "PAYMENT_CONFIRMED"
            },
            {
                "dateTime": "2017-06-28T15:30:04.121",
                "status": "PROCESSING"
            },
            {
                "dateTime": "2017-06-28T15:30:04.161",
                "status": "ADVISING"
            },
            {
                "dateTime": "2017-06-28T15:30:10.39",
                "status": "READY_TO_SEND"
            }
        ]
    }

Order statuses

NEW

Unsaved order.

SAVED

Order is saved, but it is not validated. It still can be incomplete, any field can be modified and whole order saved again as many times as needed. No information has been sent to operator yet.

WAITING_FOR_PAYMENT

Waiting for confirmation from external payment service that user successfully paid for order.

PAYMENT_CONFIRMED

Payment was confirmed by external payment service.

PAYMENT_REJECTED

Payment was rejected by external payment service.

PAYMENT_CANCELLATION_ERROR

An error occurred when trying to cancel payment in external payment service.

PROCESSING

Order is preparing to send to an operator system.

ADVISING

Order is registering in an operator system.

ERROR

An error occurred when registering an order in an operator system.

READY_TO_SEND

Order was registered in an operator system and waybill was generated. Order can be delivered to a posting point.

POSTED

Order was delivered to a posting point.

ON_THE_WAY

Order was taken from a posting point and it is traveling to a destination point.

READY_TO_PICKUP

Order is waiting for pick up in a destination point.

OUT_FOR_DELIVERY

Order was handed to deliver it to a receiver.

DELIVERED

Order was delivered to a receiver.

REMINDER_SENT

Order is waiting at a destination point to be collected. A reminder has been sent to a receiver.

PICKUP_EXPIRED

Receiver did not collect order in given time.

AVIZO

Avizo left

CLAIMED

Order was claimed.

RETURNED

Order was not taken by a receiver and it was returned to a sender.

ARCHIVED

Order was not collected by a receiver and it was moved to archive.

OTHER

Order is in unknown status.

MARKED_FOR_CANCELLATION

Order was marked to be canceled. Waiting 24h to confirm cancellation.

CANCELED

Order was canceled.

WAITING_FOR_PAYOUT

Order has been delivered. Waiting for payout to be sent (only for orders with COD).

PAYOUT_SENT

Payout was sent (only for orders with COD).

Order operations

Save

Advice

Cancel

End state

SAVED

+

+

+

-

WAITING_FOR_PAYMENT

-

-

+

-

PAYMENT_CONFIRMED

-

-

+

-

PAYMENT_REJECTED

-

-

+

-

PAYMENT_CANCELLATION_ERROR

-

-

-

-

PROCESSING

-

-

+

-

ADVISING

-

-

-

-

ERROR

-

-

+

-

READY_TO_SEND

-

-

+

-

POSTED

-

-

-

-

ON_THE_WAY

-

-

-

-

READY_TO_PICKUP

-

-

-

-

OUT_FOR_DELIVERY

-

-

-

-

DELIVERED

-

-

-

+

REMINDER_SENT

-

-

-

-

PICKUP_EXPIRED

-

-

-

-

AVIZO

-

-

-

-

CLAIMED

-

-

-

+

RETURNED

-

-

-

-

ARCHIVED

-

-

-

+

OTHER

-

-

-

-

MARKED_FOR_CANCELLATION

-

-

-

-

CANCELED

-

-

-

-

API Description

This section contains detailed API description for all available endpoints.

v2

Common model:

Operator

RUCH

Ruch

POCZTA

Poczta Polska

INPOST

Inpost

DPD

DPD

UPS

UPS

FEDEX

FedEx

GLS

GLS

XPRESS

X-press Couriers

PricelistItemType

SHIPMENT

Shipment

INSURANCE

Insurance

COD

Cash on delivery

DeliveryType

P2P

Shipment from drop off to destination point.

D2P

Shipment from sender address to destination point.

P2D

Shipment from drop off point to receiver address.

D2D

Shipment from sender to receiver address.

ServiceType

LOCAL

Local

COUNTRY

Country

INTERNATIONAL

International

VOIVODESHIP

Voivodeship

ECOMMERCE

E-commerce

Error Reason

INVALID_DESTINATION_POINT

Chosen destination point is invalid

INVALID_POSTING_POINT

Chosen posting point is invalid

OPERATOR_VALIDATION_ERROR

Order was rejected by operator validation

GENERIC_ADVICE_ERROR

Something went wrong on the operator side and we were not able to distinguish what

AUTHORIZATION_ERROR

Wrong own agreement credentials were used for the order

LABEL_GENERATION_ERROR

Generating waybill failed

WAYBILL_PROCESS_ERROR

Processing of the waybill failed

BACKEND_ERROR

Something went terribly wrong on our side

Config

Configuration options declared in user panel.

Model:

Config
Name Type

configModel

OperatorConfig[]

OperatorConfig
Name Type

operator

Operator

cod

number

prices

Map<DeliveryType>,PriceLevel>

PriceLevel
Name Type

maxWeight

number

price

number

ReturnPoint
Name Type

operator

Operator

code

string

Get
GET /v2/config

Returns configuration options.

Try it out:

curl -X GET https://api.sandbox-bliskapaczka.pl/v2/config \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

Example response:

{
	"configModel": [
		{
			"operator": "RUCH",
			"cod": null,
			"prices": {
				"TO_DOOR": null,
				"TO_POINT": [
					{
						"maxWeight": 5,
						"price": 5
					}
				]
			}
		},
		{
			"operator": "POCZTA",
			"cod": null,
			"prices": {
				"TO_DOOR": null,
				"TO_POINT": [
					{
						"maxWeight": 5,
						"price": 5
					}
				]
			}
		},
		{
			"operator": "DPD",
			"cod": null,
			"prices": {
				"TO_DOOR": [
					{
						"maxWeight": 5,
						"price": 5
					}
				],
				"TO_POINT": [
					{
						"maxWeight": 5,
						"price": 5
					}
				]
			}
		},
		{
			"operator": "GLS",
			"cod": null,
			"prices": {
				"TO_DOOR": [
					{
						"maxWeight": 5,
						"price": 5
					}
				],
				"TO_POINT": null
			}
		},
		{
			"operator": "FEDEX",
			"cod": null,
			"prices": {
				"TO_DOOR": [
					{
						"maxWeight": 5,
						"price": 5
					}
				],
				"TO_POINT": null
			}
		},
		{
			"operator": "INPOST",
			"cod": null,
			"prices": {
				"TO_DOOR": [
					{
						"maxWeight": 5,
						"price": 5
					}
				],
				"TO_POINT": [
					{
						"maxWeight": 5,
						"price": 5
					}
				]
			}
		}
	]
}
Get return config
GET /v2/config/returns

Returns configuration options for return orders.

Try it out:

curl -X GET https://api.sandbox-bliskapaczka.pl/v2/config/returns \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

Example response:

{
	"returnPoints": [
		{
			"operator": "RUCH",
			"code": "WR-547950-72-59"
		},
		{
			"operator": "POCZTA",
			"code": "275425"
		},
		{
			"operator": "DPD",
			"code": "PL11776"
		},
		{
			"operator": "INPOST",
			"code": "POP-WRO46"
		}
	]
}

Health

Bliskapaczka.pl api health check.

GET /health

Returns service status

Try it out:

curl -X GET https://api.sandbox-bliskapaczka.pl/health

Example response:

{
    "status": "OK"
}

Order

Bliskapaczka.pl order api.

Model:

Order
Name Type Description

number

string

Optional order number. If left empty, will be generated. Otherwise existing order will be used.

senderFirstName

string

max length 30

senderLastName

string

max length 30

senderPhoneNumber

string

max length 30

senderEmail

string

max length 60, valid value: email address
e.g. john@example.com

senderStreet

string

max length 30

senderBuildingNumber

string

max length 10

senderFlatNumber

string

max length 10

senderPostCode

string

max length 10

senderCity

string

max length 30

countryCode

string

Optional ISO 3166-1 alfa-2 country code max lenght 2

receiverFirstName

string

max length 30

receiverLastName

string

max length 30

receiverPhoneNumber

string

max length 30

receiverEmail

string

max length 60, valid value: email address
e.g. john@example.com

receiverStreet

string

required only for *_TO_DOOR parcels
max length 30

receiverBuildingNumber

string

required only for *_TO_DOOR parcels
max length 10

receiverFlatNumber

string

required only for *_TO_DOOR parcels
max length 10

receiverPostCode

string

required only for *_TO_DOOR parcels
max length 10

receiverCity

string

required only for *_TO_DOOR parcels
max length 30

receiverCountryCode

string

used only for *_TO_DOOR parcels
ISO 3166-1 alfa-2 country code
max lenght 2
default: "PL"

operatorName

Operator

available operator

destinationCode

string

required only for *_TO_POINT parcels
max length 50

postingCode

string

required only for POINT_TO_* parcels
max length 50

additionalInformation

string

max length 100

reference

string

max length 30

codValue

decimal(10,2)

nullable
min value 0.01

parcels

Parcel

 

codPayoutBankAccountNumber

string

nullable
bankAccountNumber needed when codValue given and not having own agreement for given operator

chooseDestinationPoint

boolean

used only for *_TO_POINT parcels

serviceType

ServiceType

optional service type

serviceId

string

optional service identifier
defined by operator

errorReason

string

advice error reason

Order model representation has changed. The new approach is to use a list of parcels instead of a single Parcel entity. The api will support the old concept only for so long. Please migrate as this backward compatibility will be removed in the future.

Parcel
Name Type Description

dimensions.height

decimal(10,2)

min value 0.01

dimensions.length

decimal(10,2)

min value 0.01

dimensions.width

decimal(10,2)

min value 0.01

dimensions.weight

decimal(10,2)

min value 0.01

insuranceValue

decimal(10,2)

nullable
min value 0.01

OrderStatusChanges
Name Type

number

string

changes

OrderStatusChange[]

OrderStatusChange
Name Type

dateTime

DateTime

status

OrderStatus

Save
POST /v2/order

Save order. Updates existing when body parameter "number" is provided or creates new one.

Try it out:

curl -X POST https://api.sandbox-bliskapaczka.pl/v2/order \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "senderFirstName":"Sender",
    "senderLastName":"Sender",
    "senderPhoneNumber":"123456789",
    "senderEmail":"sender@example.com",
    "senderStreet":"Rynek",
    "senderBuildingNumber":"1",
    "senderFlatNumber":"1",
    "senderPostCode":"00-000",
    "senderCity":"Wroclaw",
    "countryCode":"PL",
    "receiverFirstName":"Receiver",
    "receiverLastName":"Receiver",
    "receiverPhoneNumber":"987654321",
    "receiverEmail":"receiver@example.com",
    "receiverStreet":"Aleje Jerozolimskie",
    "receiverBuildingNumber":"2A",
    "receiverFlatNumber":"3",
    "receiverPostCode":"11-111",
    "receiverCity":"Warszawa",
    "receiverCountryCode":"PL",
    "operatorName":"INPOST",
    "destinationCode":"KRA010",
    "postingCode":"KRA011",
    "additionalInformation": "Some additional information",
    "reference": "Some reference",
    "parcels":[{
      "dimensions":{
        "height":20,
        "length":20,
        "width":20,
        "weight":20
      },
      "insuranceValue":150
    }],
    "codValue":110.50,
    "codPayoutBankAccountNumber":"16102019120000910201486273",
    "deliveryType":"P2P"
  }'

Example response:

{
    "number": "000000001P-000000072",
    "senderFirstName": "Sender",
    "senderLastName": "Sender",
    "senderPhoneNumber": "123456789",
    "senderEmail": "sender@example.com",
    "senderStreet": "Rynek",
    "senderBuildingNumber": "1",
    "senderFlatNumber": "1",
    "senderPostCode": "00-000",
    "senderCity": "Wroclaw",
    "receiverFirstName": "Receiver",
    "receiverLastName": "Receiver",
    "receiverPhoneNumber": "987654321",
    "receiverEmail": "receiver@example.com",
    "receiverStreet": "Ulica",
    "receiverBuildingNumber": "1A",
    "receiverFlatNumber": "2B",
    "receiverPostCode": "99-999",
    "receiverCity": "Kraków",
    "receiverCountryCode": "PL",
    "operatorName": "INPOST",
    "destinationCode": "KRA010",
    "postingCode": "KRA011",
    "additionalInformation": "Some additional information",
    "reference": "Some reference",
    "parcels": [{
        "dimensions": {
            "length": 20,
            "height": 20,
            "width": 20,
            "weight": 20
        },
        "insuranceValue": 150
    }],
    "codValue":110.50,
    "codPayoutBankAccountNumber":"16102019120000910201486273",
    "chooseDestinationPoint": false,
    "status": "SAVED",
    "deliveryType": "P2P",
    "creationDate": "2017-11-28T13:04:32.071",
    "adviceDate": null,
    "trackingNumber": null,
    "postingPostCode": "31-274",
    "postingCity": "Kraków",
    "postingStreet": "Opolska 9",
    "destinationPostCode": "30-624",
    "destinationCity": "Kraków",
    "destinationStreet": "Malborska 130",
    "orderItems": [],
    "price": null
}
Advice
POST /v2/order/advice

Advice order. Updates existing when body parameter "number" is provided or creates new one.

Try it out:

curl -X POST https://api.sandbox-bliskapaczka.pl/v2/order/advice \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "senderFirstName":"Sender",
    "senderLastName":"Sender",
    "senderPhoneNumber":"123456789",
    "senderEmail":"sender@example.com",
    "senderStreet":"Rynek",
    "senderBuildingNumber":"1",
    "senderFlatNumber":"1",
    "senderPostCode":"00-000",
    "senderCity":"Wroclaw",
    "countryCode":"PL",
    "receiverFirstName":"Receiver",
    "receiverLastName":"Receiver",
    "receiverPhoneNumber":"987654321",
    "receiverEmail":"receiver@example.com",
    "receiverStreet":"Aleje Jerozolimskie",
    "receiverBuildingNumber":"2A",
    "receiverFlatNumber":"3",
    "receiverPostCode":"11-111",
    "receiverCity":"Warszawa",
    "receiverCountryCode":"PL",
    "operatorName":"INPOST",
    "destinationCode":"KRA010",
    "postingCode":"KRA011",
    "additionalInformation": "Some additional information",
    "reference": "Some reference",
    "parcels":[{
      "dimensions":{
        "height":20,
        "length":20,
        "width":20,
        "weight":20
      },
      "insuranceValue": 1200.00
    }],
    "codValue":110,
    "codPayoutBankAccountNumber":"16102019120000910201486273",
    "deliveryType":"P2P",
    "serviceId": "SAME_DAY_18_22"
  }'

Example response:

{
    "number": "000000001P-000000073",
    "senderFirstName": "Sender",
    "senderLastName": "Sender",
    "senderPhoneNumber": "123456789",
    "senderEmail": "sender@example.com",
    "senderStreet": "Rynek",
    "senderBuildingNumber": "1",
    "senderFlatNumber": "1",
    "senderPostCode": "00-000",
    "senderCity": "Wroclaw",
    "receiverFirstName": "Receiver",
    "receiverLastName": "Receiver",
    "receiverPhoneNumber": "987654321",
    "receiverEmail": "receiver@example.com",
    "receiverStreet": "Ulica",
    "receiverBuildingNumber": "1A",
    "receiverFlatNumber": "2B",
    "receiverPostCode": "99-999",
    "receiverCity": "Kraków",
    "receiverCountryCode": "PL",
    "operatorName": "INPOST",
    "destinationCode": "KRA010",
    "postingCode": "KRA011",
    "additionalInformation": "Some additional information",
    "reference": "Some reference",
    "parcels": [{
        "dimensions": {
            "length": 20,
            "height": 20,
            "width": 20,
            "weight": 20
        },
        "insuranceValue": null
    }],
    "codValue":110,
    "codPayoutBankAccountNumber":"16102019120000910201486273",
    "chooseDestinationPoint": false,
    "status": "PROCESSING",
    "deliveryType": "P2P",
    "creationDate": "2017-11-28T14:45:29.195",
    "adviceDate": null,
    "trackingNumber": null,
    "postingPostCode": "31-274",
    "postingCity": "Kraków",
    "postingStreet": "Opolska 9",
    "destinationPostCode": "30-624",
    "destinationCity": "Kraków",
    "destinationStreet": "Malborska 130",
    "orderItems": [{
        "itemType": "SHIPMENT",
        "price": {
            "net": 8.25,
            "vat": 1.90,
            "gross": 10.15
        }
    }],
    "price": {
        "net": 8.25,
        "vat": 1.90,
        "gross": 10.15
    }
}
Confirm
POST /v2/orders/confirm?operatorName=$operator

Confirms orders for given "operator". Currently supported only for POCZTA.
Sends the parcels buffer to Poczta Institution with PNI saved in own agreement configuration panel in bliskapaczka.pl

Try it out:

curl -X POST https://api.sandbox-bliskapaczka.pl/v2/orders/confirm?operatorName=POCZTA \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

Response: no body

Get order
GET /v2/order/$number

Returns order by given order number.

Try it out:

curl -X GET https://api.sandbox-bliskapaczka.pl/v2/order/000000001P-000000002 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

Example response:

{
    "number": "000000001P-000000002",
    "senderFirstName": "IamTest",
    "senderLastName": "IamTest",
    "senderPhoneNumber": "123456789",
    "senderEmail": "testuser@example.com",
    "senderStreet": "Testowa",
    "senderBuildingNumber": "1",
    "senderFlatNumber": "2",
    "senderPostCode": "12-345",
    "senderCity": "Testowe",
    "receiverFirstName": "IamTest",
    "receiverLastName": "IamTest",
    "receiverPhoneNumber": "696452246",
    "receiverEmail": "testuser@example.com",
    "receiverStreet": "Ulica",
    "receiverBuildingNumber": "1A",
    "receiverFlatNumber": "2B",
    "receiverPostCode": "99-999",
    "receiverCity": "Kraków",
    "receiverCountryCode": "PL",
    "operatorName": "RUCH",
    "destinationCode": "BD-388553-45-18",
    "postingCode": "BD-619544-42-08",
    "additionalInformation": null,
    "parcels": [{
        "dimensions": {
            "length": 20,
            "height": 20,
            "width": 20,
            "weight": 10
        },
        "insuranceValue": null
    }],
    "codValue": null,
    "codPayoutBankAccountNumber":"16102019120000910201486273",
    "chooseDestinationPoint": false,
    "status": "READY_TO_SEND",
    "deliveryType": "P2P",
    "creationDate": "2017-01-19T09:34:28.37",
    "adviceDate": "2017-01-19T09:35:08.179",
    "trackingNumber": "3400013623451",
    "postingPostCode": null,
    "postingCity": null,
    "postingStreet": null,
    "destinationPostCode": null,
    "destinationCity": "Inowrocław",
    "destinationStreet": null,
    "orderItems": [{
        "itemType": "SHIPMENT",
        "price": {
            "net": 10.00,
            "vat": 2.30,
            "gross": 12.30
        }
    }],
    "price": {
        "net": 10.00,
        "vat": 2.30,
        "gross": 12.30
    }
}
Get order list
GET /v2/order

Returns paged and filtered order list.

Query parameters:

Name Type Description

page

Number

Required
indexed from 0

size

Number

Required
minimum 1

numbers

String[]

Optional

status

OrderStatus

Optional

operatorName

Operator

Optional

trackingNumber

String

Optional

receiverFirstName

String

Optional

receiverLastName

String

Optional

creationDateFrom

DateTime

Optional

creationDateTo

DateTime

Optional

isAllegro

boolean

Optional

allegroOfferId

String

Optional

allegroTransactionId

String

Optional

Try it out:

curl -X GET https://api.sandbox-bliskapaczka.pl/v2/order?size=10&page=0&numbers=000000000P-000000000,000000000P-000000001 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

  curl --request GET \
    --url 'https://api.sandbox-bliskapaczka.pl/v2/order?numbers=000000000P-000000000&size=10&page=0' \
      -H "Accept: application/json" \
      -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

Example response:

{
	"content": [
		{
			"status": "SAVED",
			"number": "000000001P-Z00000001",
			"creationDate": "2018-03-08T13:41:48.059",
			"adviceDate": null,
			"trackingNumber": null,
			"senderFirstName": "Jacek",
			"senderLastName": "Leszczynski",
			"receiverFirstName": "Eastend",
			"receiverLastName": "Buty",
			"operatorName": "INPOST",
			"destinationCode": "KRA010",
			"postingCode": null,
			"paymentType": "POST",
			"userId": 1
		},
		{
			"status": "SAVED",
			"number": "000000000P-000000000",
			"creationDate": "2016-07-21T16:10:53.72",
			"adviceDate": null,
			"trackingNumber": null,
			"senderFirstName": "Test",
			"senderLastName": "Test",
			"receiverFirstName": null,
			"receiverLastName": null,
			"operatorName": null,
			"destinationCode": null,
			"postingCode": null,
			"paymentType": "POST",
			"userId": 1
		}
	],
	"totalElements": 2
}
Get waybill
GET /v2/order/$number/waybill

Returns url to waybill file of order with given order number.

Unavailable for orders in statuses
  • NEW

  • SAVED

  • WAITING_FOR_PAYMENT

  • PAYMENT_CONFIRMED

  • PAYMENT_REJECTED

  • PAYMENT_CANCELLATION_ERROR

  • PROCESSING

  • ADVISING

  • ERROR

  • CANCELED

Try it out:

curl -X GET https://api.sandbox-bliskapaczka.pl/v2/order/000000001P-000000002/waybill \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

Example response:

[
  {
    "url" : "https://storage.googleapis.com/test.cloud.senditstatic.pl/ppo/ruch/waybill/2017/01/03/000000001P-000000002.pdf?GoogleAccessId=storage@archiwum-140107.iam.gserviceaccount.com&Expires=1512471128&Signature=k1aQ3MKqI37Kg8mnbMwxJ8danOGEKgwXFmUb2Lg6szxStoGl5OLmlDugCTVMA8YUNVR%2FTz"
  },
  {
    "url" : "https://storage.googleapis.com/test.cloud.senditstatic.pl/ppo/ruch/waybill/2017/01/03/000000001P-000000002.pdf?GoogleAccessId=storage@archiwum-140107.iam.gserviceaccount.com&Expires=1512471128&Signature=k1aQ3MKqI37Kg8mnbMwxJ8danOGEKgwXFmUb2Lg6szxStoGl5OLmlDugCTVMA8YUNVR%2FTz"
  }
]
Get tracking
GET /v2/order/$number/tracking

Returns order status changes by given order number.

Try it out:

curl -X GET https://api.sandbox-bliskapaczka.pl/v2/order/000000001P-000000002/tracking \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

Example response:

{
    "number": "000000001P-000000002",
    "changes": [{
        "dateTime": "2017-11-21T12:10:55.971",
        "status": "SAVED"
    }, {
        "dateTime": "2017-11-21T12:10:56.208",
        "status": "PAYMENT_CONFIRMED"
    }, {
        "dateTime": "2017-11-21T12:10:56.208",
        "status": "PROCESSING"
    }, {
        "dateTime": "2017-11-21T12:10:56.37",
        "status": "ADVISING"
    }, {
        "dateTime": "2017-11-21T12:11:40.233",
        "status": "READY_TO_SEND"
    }]
}
Cancel
POST /v2/order/$number/cancel

Cancel order. Triggers cancellation process. When orders is already advised its status is changed to MARKED_FOR_CANCELLATION for 24 hours, then operator status is checked whether the order was sent and if not its status is changed to CANCELLED

Try it out:

curl -X POST https://api.sandbox-bliskapaczka.pl/v2/order/000000001P-000000072/cancel \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

Example response:

{
    "number": "000000001P-000000072",
    "senderFirstName": "Sender",
    "senderLastName": "Sender",
    "senderPhoneNumber": "123456789",
    "senderEmail": "sender@example.com",
    "senderStreet": "Rynek",
    "senderBuildingNumber": "1",
    "senderFlatNumber": "1",
    "senderPostCode": "00-000",
    "senderCity": "Wroclaw",
    "receiverFirstName": "Receiver",
    "receiverLastName": "Receiver",
    "receiverPhoneNumber": "987654321",
    "receiverEmail": "receiver@example.com",
    "receiverStreet": "Ulica",
    "receiverBuildingNumber": "1A",
    "receiverFlatNumber": "2B",
    "receiverPostCode": "99-999",
    "receiverCity": "Kraków",
    "receiverCountryCode": "PL",
    "operatorName": "INPOST",
    "destinationCode": "KRA010",
    "postingCode": "KRA011",
    "additionalInformation": null,
    "parcels": [{
        "dimensions": {
            "length": 20,
            "height": 20,
            "width": 20,
            "weight": 20
        },
        "insuranceValue": null
    }],
    "codValue":110,
    "codPayoutBankAccountNumber":"16102019120000910201486273",
    "chooseDestinationPoint": false,
    "status": "MARKED_FOR_CANCELLATION",
    "deliveryType": "TO_POINT",
    "creationDate": "2017-11-28T14:45:29.195",
    "adviceDate": null,
    "trackingNumber": null,
    "postingPostCode": "31-274",
    "postingCity": "Kraków",
    "postingStreet": "Opolska 9",
    "destinationPostCode": "30-624",
    "destinationCity": "Kraków",
    "destinationStreet": "Malborska 130",
    "orderItems": [{
        "itemType": "SHIPMENT",
        "price": {
            "net": 8.25,
            "vat": 1.90,
            "gross": 10.15
        }
    }],
    "price": {
        "net": 8.25,
        "vat": 1.90,
        "gross": 10.15
    }
}
Retry
POST /v2/order/$number/retry

Retry order advice. Used to trigger order processing when given order is in ERROR status and that error reason allows for this action.

Available for orders in status ERROR with reasons:
  • GENERIC_ADVICE_ERROR

  • AUTHORIZATION_ERROR

  • LABEL_GENERATION_ERROR

  • WAYBILL_PROCESS_ERROR

  • BACKEND_ERROR

Try it out:

curl -X POST https://api.sandbox-bliskapaczka.pl/v2/order/000000001P-000000072/retry \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

Response: no body

GET /v2/order/$number/accessLink

It is possible to let end user choose parcel destination. This endpoint Returns order with access link that can be sent to end user to pick destination point. Bliskapaczka.pl post about the feature

Try it out:

curl -X GET https://api.sandbox-bliskapaczka.pl/v2/order/000000001P-000000002/accessLink \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

Example response:

{
    "number": "000000001P-000000002",
    "senderFirstName": "IamTest",
    "senderLastName": "IamTest",
    "senderPhoneNumber": "123456789",
    "senderEmail": "testuser@example.com",
    "senderStreet": "Testowa",
    "senderBuildingNumber": "1",
    "senderFlatNumber": "2",
    "senderPostCode": "12-345",
    "senderCity": "Testowe",
    "receiverFirstName": "IamTest",
    "receiverLastName": "IamTest",
    "receiverPhoneNumber": "912345678",
    "receiverEmail": "testuser@example.com",
    "receiverStreet": "Ulica",
    "receiverBuildingNumber": "1A",
    "receiverFlatNumber": "2B",
    "receiverPostCode": "99-999",
    "receiverCity": "Kraków",
    "receiverCountryCode": "PL",
    "operatorName": null,
    "destinationCode": null,
    "postingCode": null,
    "additionalInformation": null,
    "parcels": [{
        "dimensions": {
            "length": 10,
            "height": 10,
            "width": 10,
            "weight": 10
        },
        "insuranceValue": null
    }],
    "codValue":110,
    "codPayoutBankAccountNumber":"16102019120000910201486273",
    "chooseDestinationPoint": true,
    "status": "SAVED",
    "deliveryType": "TO_POINT",
    "creationDate": "2017-11-28T12:52:02.441",
    "adviceDate": null,
    "trackingNumber": null,
    "postingPostCode": null,
    "postingCity": null,
    "postingStreet": null,
    "destinationPostCode": null,
    "destinationCity": null,
    "destinationStreet": null,
    "orderItems": [],
    "price": null,
    "tokenLink": "https://sandbox-bliskapaczka.pl/wybierz-punkt/115b902709f34c1eb417fc22125dce84"
}
Notify
POST /v2/order/$number/notify

Sends email notification to end user to choose destination point.

Try it out:

curl -X POST https://api.sandbox-bliskapaczka.pl/v2/order/000000001P-000000072/notify \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

Example response:

{
    "number": "000000001P-000000072",
    "senderFirstName": "IamTest",
    "senderLastName": "IamTest",
    "senderPhoneNumber": "123456789",
    "senderEmail": "testuser@example.com",
    "senderStreet": "Testowa",
    "senderBuildingNumber": "1",
    "senderFlatNumber": "2",
    "senderPostCode": "12-345",
    "senderCity": "Testowe",
    "receiverFirstName": "Marcin",
    "receiverLastName": "dfgfd",
    "receiverPhoneNumber": "912345678",
    "receiverEmail": "marcin.architek@sendit.pl",
    "receiverStreet": "Ulica",
    "receiverBuildingNumber": "1A",
    "receiverFlatNumber": "2B",
    "receiverPostCode": "99-999",
    "receiverCity": "Kraków",
    "receiverCountryCode": "PL",
    "operatorName": null,
    "destinationCode": null,
    "postingCode": null,
    "additionalInformation": null,
    "parcels": [{
        "dimensions": {
            "length": 10,
            "height": 10,
            "width": 10,
            "weight": 10
        },
        "insuranceValue": null
    }],
    "codValue":110,
    "codPayoutBankAccountNumber":"16102019120000910201486273",
    "chooseDestinationPoint": true,
    "status": "SAVED",
    "deliveryType": "TO_POINT",
    "creationDate": "2017-11-28T15:14:13.761",
    "adviceDate": null,
    "trackingNumber": null,
    "postingPostCode": null,
    "postingCity": null,
    "postingStreet": null,
    "destinationPostCode": null,
    "destinationCity": null,
    "destinationStreet": null,
    "orderItems": [],
    "price": null,
    "tokenLink": "https://sandbox-bliskapaczka.pl/wybierz-punkt/96b3e12da0704357a335e05beda47c8d"
}
Return
POST /v2/order/return

Save return order. Updates existing order when body parameter "number" is provided or creates new one.
Return order is an order paid by the user but sent by the end user (customer).

Try it out:

curl -X POST https://api.sandbox-bliskapaczka.pl/v2/order/return \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "senderFirstName": "Sender",
    "senderLastName": "Sender",
    "senderPhoneNumber": "123456789",
    "senderEmail": "sender@example.com",
    "senderStreet": "Rynek",
    "senderBuildingNumber": "1",
    "senderFlatNumber": "1",
    "senderPostCode": "00-000",
    "senderCity": "Wroclaw",
    "receiverFirstName": "Receiver",
    "receiverLastName": "Receiver",
    "receiverPhoneNumber": "987654321",
    "receiverEmail": "receiver@example.com",
    "operatorName": "INPOST",
    "destinationCode": "KRA010",
    "additionalInformation": "Some additional information",
    "reference": "Some reference",
    "parcel": {
        "dimensions": {
            "height": 20,
            "length": 20,
            "width": 20,
            "weight": 20
        }
    },
    "insuranceValue": 1000
}'

Example response:

{
	"number": "000000001P-Z00000001",
	"returnLink": "https://bliskapaczka.pl/zwrot/bacb02ceee564703abd84077ea21809c"
}
Available services
POST /v2/order/services

Returns services available for posted order details.

Try it out:

curl -X POST https://api.sandbox-bliskapaczka.pl/v2/order/services \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
	"senderFirstName":"Sender",
	"senderLastName":"Sender",
	"senderPhoneNumber":"666777888",
	"senderEmail":"sender@example.com",
	"senderStreet":"Rynek",
	"senderBuildingNumber":"1",
	"senderFlatNumber":"1",
	"senderPostCode":"53-019",
	"senderCity":"Wrocław",
	"receiverFirstName":"Receiver",
	"receiverLastName":"Receiver",
	"receiverPhoneNumber":"987654321",
	"receiverEmail":"receiver@example.com",
	"receiverStreet":"Wagonowa",
	"receiverBuildingNumber":"2b",
	"receiverFlatNumber":null,
	"receiverPostCode":"53-019",
	"receiverCity":"Wrocław",
	"operatorName":"XPRESS",
	"parcels":[
		{
			"dimensions":{
				"height":20,
				"length":20,
				"width":20,
				"weight":20
			},
			"insuranceValue":150
		}
	],
	"codValue":11.1,
	"codPayoutBankAccountNumber":"61109010140000071219812874",
	"deliveryType": "D2D",
	"serviceType": "COUNTRY"
}'

Example response:

[
    "SAME_DAY_18_22"
]

Pricing

Bliskapaczka.pl pricing api.

To point

Bliskapaczka.pl to point pricing api.

POST /v2/pricing/

Returns pricing for given parcel according to the user configuration from https://bliskapaczka.pl/panel/narzedzia/integracja.

Try it out:

  curl -X POST https://api.sandbox-bliskapaczka.pl/v2/pricing \
    -H 'authorization: Bearer xxxx-xxxx-xxxx-xxxx' \
    -H 'content-type: application/json' \
    -d '{
  	"parcel":{
  		"dimensions":{
  			"length":10,
  			"width":10,
  			"height":10,
  			"weight":1
  		},
  		"insuranceValue":10
  	},
  	"codValue":10
  }'

Example response:

[
	{
		"operatorName": "DPD",
		"operatorFullName": "DPD",
		"availabilityStatus": true,
		"price": {
			"net": 4.07,
			"vat": 0.93,
			"gross": 5.00
		},
		"unavailabilityReason": null
	},
	{
		"operatorName": "RUCH",
		"operatorFullName": "Ruch",
		"availabilityStatus": true,
		"price": {
			"net": 4.07,
			"vat": 0.93,
			"gross": 5.00
		},
		"unavailabilityReason": null
	},
	{
		"operatorName": "INPOST",
		"operatorFullName": "Inpost",
		"availabilityStatus": true,
		"price": {
			"net": 4.07,
			"vat": 0.93,
			"gross": 5.00
		},
		"unavailabilityReason": null
	},
	{
		"operatorName": "POCZTA",
		"operatorFullName": "Poczta Polska",
		"availabilityStatus": false,
		"price": null,
		"unavailabilityReason": {
			"errors": [
				{
					"messageCode": "pl.bliskapaczka.pricing.unavailable.noShipmentOffer",
					"message": "No shipment offer available",
					"field": null,
					"value": null
				}
			]
		}
	}
]
To door

Bliskapaczka.pl to door pricing api.

POST /v2/pricing/todoor

Returns pricing for given courier parcel according to the user configuration from https://bliskapaczka.pl/panel/narzedzia/integracja.

Try it out:

  curl -X POST https://api.sandbox-bliskapaczka.pl/v2/pricing/todoor \
    -H 'authorization: Bearer xxxx-xxxx-xxxx-xxxx' \
    -H 'content-type: application/json' \
    -d '{
  	"parcel":{
  		"dimensions":{
  			"length":10,
  			"width":10,
  			"height":10,
  			"weight":1
  		},
  		"insuranceValue":10
  	},
  	"codValue":10
  }'

Example response:

[
	{
		"operatorName": "DPD",
		"operatorFullName": "DPD",
		"availabilityStatus": true,
		"price": {
			"net": 4.07,
			"vat": 0.93,
			"gross": 5.00
		},
		"unavailabilityReason": null
	},
	{
		"operatorName": "INPOST",
		"operatorFullName": "Inpost",
		"availabilityStatus": true,
		"price": {
			"net": 4.07,
			"vat": 0.93,
			"gross": 5.00
		},
		"unavailabilityReason": null
	},
	{
		"operatorName": "GLS",
		"operatorFullName": "GLS",
		"availabilityStatus": false,
		"price": null,
		"unavailabilityReason": {
			"errors": [
				{
					"messageCode": "pl.bliskapaczka.pricing.unavailable.noShipmentOffer",
					"message": "No shipment offer available",
					"field": null,
					"value": null
				}
			]
		}
	}
]

Report

Bliskapaczka.pl reports utilities.

Pickup confirmation
GET /v2/report/pickupconfirmation

Query parameters:

Name Type Description

numbers

String[]

required
order numbers for pickup report

Returns pickup confirmation report for given order numbers

Given order numbers must:
  • have same operatorName

  • be in "READY_TO_SEND" status

Try it out:

curl -X GET https://api.sandbox-bliskapaczka.pl/v2/report/pickupconfirmation?numbers=000000001P-0000000001,000000001P-0000000002 \
  -H "Accept: application/pdf" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

Response: PDF

Pickup confirmation for operator
GET /v2/report/pickupconfirmation/$operator

Query parameters:

Name Type Description

startPeriod

DateTime

Optional

endPeriod

DateTime

Optional

Returns pickup confirmation report for given operator orders in status 'READY_TO_SEND'.

Try it out:

curl -X GET https://api.sandbox-bliskapaczka.pl/v2/report/pickupconfirmation/ruch?startPeriod=2017-10-23T12:00:00 \
  -H "Accept: application/pdf" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

Response: PDF

v1

Common model:

Operator

RUCH

Ruch

POCZTA

Poczta Polska

INPOST

Inpost

DPD

DPD

UPS

UPS

FEDEX

FedEx

GLS

GLS

XPRESS

X-press Couriers

PricelistItemType

SHIPMENT

Shipment

INSURANCE

Insurance

COD

Cash on delivery

DeliveryType

TO_POINT

Shipment to destination point.

TO_DOOR

Shipment to receiver address.

ServiceType

LOCAL

Local

COUNTRY

Country

INTERNATIONAL

International

VOIVODESHIP

Voivodeship

ECOMMERCE

E-commerce

Error Reason

INVALID_DESTINATION_POINT

Chosen destination point is invalid

INVALID_POSTING_POINT

Chosen posting point is invalid

OPERATOR_VALIDATION_ERROR

Order was rejected by operator validation

GENERIC_ADVICE_ERROR

Something went wrong on the operator side and we were not able to distinguish what

AUTHORIZATION_ERROR

Wrong own agreement credentials were used for the order

LABEL_GENERATION_ERROR

Generating waybill failed

WAYBILL_PROCESS_ERROR

Processing of the waybill failed

BACKEND_ERROR

Something went terribly wrong on our side

Config

Configuration options declared in user panel.

Model:

Config
Name Type

configModel

OperatorConfig[]

OperatorConfig
Name Type

operator

Operator

cod

number

prices

Map<DeliveryType>,PriceLevel>

PriceLevel
Name Type

maxWeight

number

price

number

ReturnPoint
Name Type

operator

Operator

code

string

Get
GET /v1/config

Returns configuration options.

Try it out:

curl -X GET https://api.sandbox-bliskapaczka.pl/v1/config \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

Example response:

{
	"configModel": [
		{
			"operator": "RUCH",
			"cod": null,
			"prices": {
				"TO_DOOR": null,
				"TO_POINT": [
					{
						"maxWeight": 5,
						"price": 5
					}
				]
			}
		},
		{
			"operator": "POCZTA",
			"cod": null,
			"prices": {
				"TO_DOOR": null,
				"TO_POINT": [
					{
						"maxWeight": 5,
						"price": 5
					}
				]
			}
		},
		{
			"operator": "DPD",
			"cod": null,
			"prices": {
				"TO_DOOR": [
					{
						"maxWeight": 5,
						"price": 5
					}
				],
				"TO_POINT": [
					{
						"maxWeight": 5,
						"price": 5
					}
				]
			}
		},
		{
			"operator": "GLS",
			"cod": null,
			"prices": {
				"TO_DOOR": [
					{
						"maxWeight": 5,
						"price": 5
					}
				],
				"TO_POINT": null
			}
		},
		{
			"operator": "FEDEX",
			"cod": null,
			"prices": {
				"TO_DOOR": [
					{
						"maxWeight": 5,
						"price": 5
					}
				],
				"TO_POINT": null
			}
		},
		{
			"operator": "INPOST",
			"cod": null,
			"prices": {
				"TO_DOOR": [
					{
						"maxWeight": 5,
						"price": 5
					}
				],
				"TO_POINT": [
					{
						"maxWeight": 5,
						"price": 5
					}
				]
			}
		}
	]
}
Get return config
GET /v1/config/returns

Returns configuration options for return orders.

Try it out:

curl -X GET https://api.sandbox-bliskapaczka.pl/v1/config/returns \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

Example response:

{
	"returnPoints": [
		{
			"operator": "RUCH",
			"code": "WR-547950-72-59"
		},
		{
			"operator": "POCZTA",
			"code": "275425"
		},
		{
			"operator": "DPD",
			"code": "PL11776"
		},
		{
			"operator": "INPOST",
			"code": "POP-WRO46"
		}
	]
}

Health

Bliskapaczka.pl api health check.

GET /health

Returns service status

Try it out:

curl -X GET https://api.sandbox-bliskapaczka.pl/health

Example response:

{
    "status": "OK"
}

Order

Bliskapaczka.pl order api.

Model:

Order
Name Type Description

number

string

Optional order number. If left empty, will be generated. Otherwise existing order will be used.

senderFirstName

string

max length 30

senderLastName

string

max length 30

senderPhoneNumber

string

max length 30

senderEmail

string

max length 60, valid value: email address
e.g. john@example.com

senderStreet

string

max length 30

senderBuildingNumber

string

max length 10

senderFlatNumber

string

max length 10

senderPostCode

string

max length 10

senderCity

string

max length 30

receiverFirstName

string

max length 30

receiverLastName

string

max length 30

receiverPhoneNumber

string

max length 30

receiverEmail

string

max length 60, valid value: email address
e.g. john@example.com

receiverStreet

string

required only for TO_DOOR parcels
max length 30

receiverBuildingNumber

string

required only for TO_DOOR parcels
max length 10

receiverFlatNumber

string

required only for TO_DOOR parcels
max length 10

receiverPostCode

string

required only for TO_DOOR parcels
max length 10

receiverCity

string

required only for TO_DOOR parcels
max length 30

receiverCountryCode

string

used only for TO_DOOR parcels
ISO 3166-1 alfa-2 country code
max lenght 2
default: "PL"

operatorName

Operator

available operator

destinationCode

string

required only for TO_POINT parcels
max length 50

postingCode

string

required only for TO_POINT parcels
max length 50

additionalInformation

string

max length 100

codValue

decimal(10,2)

nullable
min value 0.01

parcels

Parcel

 

codPayoutBankAccountNumber

string

nullable
bankAccountNumber needed when codValue given and not having own agreement for given operator

chooseDestinationPoint

boolean

used only for TO_POINT parcels

serviceType

ServiceType

optional service type

serviceId

string

optional service identifier
defined by operator

errorReason

string

advice error reason

Order model representation has changed. The new approach is to use a list of parcels instead of a single Parcel entity. The api will support the old concept only for so long. Please migrate as this backward compatibility will be removed in the future.

Parcel
Name Type Description

dimensions.height

decimal(10,2)

min value 0.01

dimensions.length

decimal(10,2)

min value 0.01

dimensions.width

decimal(10,2)

min value 0.01

dimensions.weight

decimal(10,2)

min value 0.01

insuranceValue

decimal(10,2)

nullable
min value 0.01

OrderStatusChanges
Name Type

number

string

changes

OrderStatusChange[]

OrderStatusChange
Name Type

dateTime

DateTime

status

OrderStatus

Save
POST /v1/order

Save order. Updates existing when body parameter "number" is provided or creates new one.

Try it out:

curl -X POST https://api.sandbox-bliskapaczka.pl/v1/order \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "senderFirstName":"Sender",
    "senderLastName":"Sender",
    "senderPhoneNumber":"123456789",
    "senderEmail":"sender@example.com",
    "senderStreet":"Rynek",
    "senderBuildingNumber":"1",
    "senderFlatNumber":"1",
    "senderPostCode":"00-000",
    "senderCity":"Wroclaw",
    "receiverFirstName":"Receiver",
    "receiverLastName":"Receiver",
    "receiverPhoneNumber":"987654321",
    "receiverEmail":"receiver@example.com",
    "operatorName":"INPOST",
    "destinationCode":"KRA010",
    "postingCode":"KRA011",
    "additionalInformation": "Some additional information",
    "parcels":[{
      "dimensions":{
        "height":20,
        "length":20,
        "width":20,
        "weight":20
      },
      "insuranceValue":150
    }],
    "codValue":110.50,
    "codPayoutBankAccountNumber":"16102019120000910201486273"
  }'

Example response:

{
    "number": "000000001P-000000072",
    "senderFirstName": "Sender",
    "senderLastName": "Sender",
    "senderPhoneNumber": "123456789",
    "senderEmail": "sender@example.com",
    "senderStreet": "Rynek",
    "senderBuildingNumber": "1",
    "senderFlatNumber": "1",
    "senderPostCode": "00-000",
    "senderCity": "Wroclaw",
    "receiverFirstName": "Receiver",
    "receiverLastName": "Receiver",
    "receiverPhoneNumber": "987654321",
    "receiverEmail": "receiver@example.com",
    "receiverStreet": "Ulica",
    "receiverBuildingNumber": "1A",
    "receiverFlatNumber": "2B",
    "receiverPostCode": "99-999",
    "receiverCity": "Kraków",
    "receiverCountryCode": "PL",
    "operatorName": "INPOST",
    "destinationCode": "KRA010",
    "postingCode": "KRA011",
    "additionalInformation": null,
    "parcels": [{
        "dimensions": {
            "length": 20,
            "height": 20,
            "width": 20,
            "weight": 20
        },
        "insuranceValue": 150
    }],
    "codValue":110.50,
    "codPayoutBankAccountNumber":"16102019120000910201486273",
    "chooseDestinationPoint": false,
    "status": "SAVED",
    "deliveryType": "TO_POINT",
    "creationDate": "2017-11-28T13:04:32.071",
    "adviceDate": null,
    "trackingNumber": null,
    "postingPostCode": "31-274",
    "postingCity": "Kraków",
    "postingStreet": "Opolska 9",
    "destinationPostCode": "30-624",
    "destinationCity": "Kraków",
    "destinationStreet": "Malborska 130",
    "orderItems": [],
    "price": null
}
Advice
POST /v1/order/advice

Advice order. Updates existing when body parameter "number" is provided or creates new one.

Try it out:

curl -X POST https://api.sandbox-bliskapaczka.pl/v1/order/advice \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "senderFirstName":"Sender",
    "senderLastName":"Sender",
    "senderPhoneNumber":"123456789",
    "senderEmail":"sender@example.com",
    "senderStreet":"Rynek",
    "senderBuildingNumber":"1",
    "senderFlatNumber":"1",
    "senderPostCode":"00-000",
    "senderCity":"Wroclaw",
    "receiverFirstName":"Receiver",
    "receiverLastName":"Receiver",
    "receiverPhoneNumber":"987654321",
    "receiverEmail":"receiver@example.com",
    "operatorName":"INPOST",
    "destinationCode":"KRA010",
    "postingCode":"KRA011",
    "additionalInformation": "Some additional information",
    "parcels":[{
      "dimensions":{
        "height":20,
        "length":20,
        "width":20,
        "weight":20
      },
      "insuranceValue": 1200.00
    }],
    "codValue":110,
    "codPayoutBankAccountNumber":"16102019120000910201486273",
    "serviceId": "SAME_DAY_18_22"
  }'

Example response:

{
    "number": "000000001P-000000073",
    "senderFirstName": "Sender",
    "senderLastName": "Sender",
    "senderPhoneNumber": "123456789",
    "senderEmail": "sender@example.com",
    "senderStreet": "Rynek",
    "senderBuildingNumber": "1",
    "senderFlatNumber": "1",
    "senderPostCode": "00-000",
    "senderCity": "Wroclaw",
    "receiverFirstName": "Receiver",
    "receiverLastName": "Receiver",
    "receiverPhoneNumber": "987654321",
    "receiverEmail": "receiver@example.com",
    "receiverStreet": "Ulica",
    "receiverBuildingNumber": "1A",
    "receiverFlatNumber": "2B",
    "receiverPostCode": "99-999",
    "receiverCity": "Kraków",
    "receiverCountryCode": "PL",
    "operatorName": "INPOST",
    "destinationCode": "KRA010",
    "postingCode": "KRA011",
    "additionalInformation": "Some additional information",
    "parcels": [{
        "dimensions": {
            "length": 20,
            "height": 20,
            "width": 20,
            "weight": 20
        },
        "insuranceValue": null
    }],
    "codValue":110,
    "codPayoutBankAccountNumber":"16102019120000910201486273",
    "chooseDestinationPoint": false,
    "status": "PROCESSING",
    "deliveryType": "TO_POINT",
    "creationDate": "2017-11-28T14:45:29.195",
    "adviceDate": null,
    "trackingNumber": null,
    "postingPostCode": "31-274",
    "postingCity": "Kraków",
    "postingStreet": "Opolska 9",
    "destinationPostCode": "30-624",
    "destinationCity": "Kraków",
    "destinationStreet": "Malborska 130",
    "orderItems": [{
        "itemType": "SHIPMENT",
        "price": {
            "net": 8.25,
            "vat": 1.90,
            "gross": 10.15
        }
    }],
    "price": {
        "net": 8.25,
        "vat": 1.90,
        "gross": 10.15
    }
}
Confirm
POST /v1/orders/confirm?operatorName=$operator

Confirms orders for given "operator". Currently supported only for POCZTA.
Sends the parcels buffer to Poczta Institution with PNI saved in own agreement configuration panel in bliskapaczka.pl

Try it out:

curl -X POST https://api.sandbox-bliskapaczka.pl/v1/orders/confirm?operatorName=POCZTA \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

Response: no body

Get order
GET /v1/order/$number

Returns order by given order number.

Try it out:

curl -X GET https://api.sandbox-bliskapaczka.pl/v1/order/000000001P-000000002 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

Example response:

{
    "number": "000000001P-000000002",
    "senderFirstName": "IamTest",
    "senderLastName": "IamTest",
    "senderPhoneNumber": "123456789",
    "senderEmail": "testuser@example.com",
    "senderStreet": "Testowa",
    "senderBuildingNumber": "1",
    "senderFlatNumber": "2",
    "senderPostCode": "12-345",
    "senderCity": "Testowe",
    "receiverFirstName": "IamTest",
    "receiverLastName": "IamTest",
    "receiverPhoneNumber": "696452246",
    "receiverEmail": "testuser@example.com",
    "receiverStreet": "Ulica",
    "receiverBuildingNumber": "1A",
    "receiverFlatNumber": "2B",
    "receiverPostCode": "99-999",
    "receiverCity": "Kraków",
    "receiverCountryCode": "PL",
    "operatorName": "RUCH",
    "destinationCode": "BD-388553-45-18",
    "postingCode": "BD-619544-42-08",
    "additionalInformation": null,
    "parcels": [{
        "dimensions": {
            "length": 20,
            "height": 20,
            "width": 20,
            "weight": 10
        },
        "insuranceValue": null
    }],
    "codValue": null,
    "codPayoutBankAccountNumber":"16102019120000910201486273",
    "chooseDestinationPoint": false,
    "status": "READY_TO_SEND",
    "deliveryType": "TO_POINT",
    "creationDate": "2017-01-19T09:34:28.37",
    "adviceDate": "2017-01-19T09:35:08.179",
    "trackingNumber": "3400013623451",
    "postingPostCode": null,
    "postingCity": null,
    "postingStreet": null,
    "destinationPostCode": null,
    "destinationCity": "Inowrocław",
    "destinationStreet": null,
    "orderItems": [{
        "itemType": "SHIPMENT",
        "price": {
            "net": 10.00,
            "vat": 2.30,
            "gross": 12.30
        }
    }],
    "price": {
        "net": 10.00,
        "vat": 2.30,
        "gross": 12.30
    }
}
Get order list
GET /v1/order

Returns paged and filtered order list.

Query parameters:

Name Type Description

page

Number

Required
indexed from 0

size

Number

Required
minimum 1

numbers

String[]

Optional

status

OrderStatus

Optional

operatorName

Operator

Optional

trackingNumber

String

Optional

receiverFirstName

String

Optional

receiverLastName

String

Optional

creationDateFrom

DateTime

Optional

creationDateTo

DateTime

Optional

isAllegro

boolean

Optional

allegroOfferId

String

Optional

allegroTransactionId

String

Optional

Try it out:

curl -X GET https://api.sandbox-bliskapaczka.pl/v1/order?size=10&page=0&numbers=000000000P-000000000,000000000P-000000001 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

  curl --request GET \
    --url 'http://https://api.sandbox-bliskapaczka.pl/v1/order?numbers=000000000P-000000000&size=10&page=0' \
      -H "Accept: application/json" \
      -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

Example response:

{
	"content": [
		{
			"status": "SAVED",
			"number": "000000001P-Z00000001",
			"creationDate": "2018-03-08T13:41:48.059",
			"adviceDate": null,
			"trackingNumber": null,
			"senderFirstName": "Jacek",
			"senderLastName": "Leszczynski",
			"receiverFirstName": "Eastend",
			"receiverLastName": "Buty",
			"operatorName": "INPOST",
			"destinationCode": "KRA010",
			"postingCode": null,
			"paymentType": "POST",
			"userId": 1
		},
		{
			"status": "SAVED",
			"number": "000000000P-000000000",
			"creationDate": "2016-07-21T16:10:53.72",
			"adviceDate": null,
			"trackingNumber": null,
			"senderFirstName": "Test",
			"senderLastName": "Test",
			"receiverFirstName": null,
			"receiverLastName": null,
			"operatorName": null,
			"destinationCode": null,
			"postingCode": null,
			"paymentType": "POST",
			"userId": 1
		}
	],
	"totalElements": 2
}
Get waybill
GET /v1/order/$number/waybill

Returns url to waybill file of order with given order number.

Unavailable for orders in statuses
  • NEW

  • SAVED

  • WAITING_FOR_PAYMENT

  • PAYMENT_CONFIRMED

  • PAYMENT_REJECTED

  • PAYMENT_CANCELLATION_ERROR

  • PROCESSING

  • ADVISING

  • ERROR

  • CANCELED

Try it out:

curl -X GET https://api.sandbox-bliskapaczka.pl/v1/order/000000001P-000000002/waybill \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

Example response:

{
  "url" : "https://storage.googleapis.com/test.cloud.senditstatic.pl/ppo/ruch/waybill/2017/01/03/000000001P-000000002.pdf?GoogleAccessId=storage@archiwum-140107.iam.gserviceaccount.com&Expires=1512471128&Signature=k1aQ3MKqI37Kg8mnbMwxJ8danOGEKgwXFmUb2Lg6szxStoGl5OLmlDugCTVMA8YUNVR%2FTz"
}
Get tracking
GET /v1/order/$number/tracking

Returns order status changes by given order number.

Try it out:

curl -X GET https://api.sandbox-bliskapaczka.pl/v1/order/000000001P-000000002/tracking \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

Example response:

{
    "number": "000000001P-000000002",
    "changes": [{
        "dateTime": "2017-11-21T12:10:55.971",
        "status": "SAVED"
    }, {
        "dateTime": "2017-11-21T12:10:56.208",
        "status": "PAYMENT_CONFIRMED"
    }, {
        "dateTime": "2017-11-21T12:10:56.208",
        "status": "PROCESSING"
    }, {
        "dateTime": "2017-11-21T12:10:56.37",
        "status": "ADVISING"
    }, {
        "dateTime": "2017-11-21T12:11:40.233",
        "status": "READY_TO_SEND"
    }]
}
Save (to door)
POST /v1/order/todoor

Save "to door" order. Updates existing when body parameter "number" is provided or creates new one.
This feature is experimental and disabled by default. To use it, please contact us on: integracje@bliskapaczka.pl.

Try it out:

curl -X POST https://api.sandbox-bliskapaczka.pl/v1/order/todoor \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "senderFirstName":"Sender",
    "senderLastName":"Sender",
    "senderPhoneNumber":"123456789",
    "senderEmail":"sender@example.com",
    "senderStreet":"Rynek",
    "senderBuildingNumber":"1",
    "senderFlatNumber":"1",
    "senderPostCode":"00-000",
    "senderCity":"Wroclaw",
    "receiverFirstName":"Receiver",
    "receiverLastName":"Receiver",
    "receiverPhoneNumber":"987654321",
    "receiverEmail":"receiver@example.com",
    "receiverStreet":"Testowa",
    "receiverBuildingNumber":"1",
    "receiverFlatNumber":null,
    "receiverPostCode":"12-345",
    "receiverCity":"Testowe",
    "receiverCountryCode":"PL",
    "additionalInformation":"Some additional information",
    "operatorName":"DPD",
    "parcels":[{
      "dimensions":{
        "height":20,
        "length":20,
        "width":20,
        "weight":20
      },
      "insuranceValue":110
    }],
    "codValue":150,
    "codPayoutBankAccountNumber":"16102019120000910201486273"
  }'

Example response:

{
    "number": "000000001P-000000072",
    "senderFirstName": "Sender",
    "senderLastName": "Sender",
    "senderPhoneNumber": "123456789",
    "senderEmail": "sender@example.com",
    "senderStreet": "Rynek",
    "senderBuildingNumber": "1",
    "senderFlatNumber": "1",
    "senderPostCode": "00-000",
    "senderCity": "Wroclaw",
    "receiverFirstName": "Receiver",
    "receiverLastName": "Receiver",
    "receiverPhoneNumber": "987654321",
    "receiverEmail": "receiver@example.com",
    "receiverStreet":"Testowa",
    "receiverBuildingNumber":"1",
    "receiverFlatNumber":null,
    "receiverPostCode":"12-345",
    "receiverCity":"Testowe",
    "operatorName": "DPD",
    "additionalInformation": null,
    "parcels": [{
        "dimensions": {
            "length": 20,
            "height": 20,
            "width": 20,
            "weight": 20
        },
        "insuranceValue": 110
    }],
    "codValue":110,
    "codPayoutBankAccountNumber":"16102019120000910201486273",
    "chooseDestinationPoint": false,
    "status": "SAVED",
    "deliveryType": "TO_DOOR",
    "creationDate": "2017-11-28T13:04:32.071",
    "adviceDate": null,
    "trackingNumber": null,
    "postingPostCode": "31-274",
    "postingCity": "Kraków",
    "postingStreet": "Opolska 9",
    "destinationPostCode": "30-624",
    "destinationCity": "Kraków",
    "destinationStreet": "Malborska 130",
    "orderItems": [],
    "price": null
}
Advice (to door)
POST /v1/order/advice/todoor

Advice "to door" order. Updates existing order when body parameter "number" is provided or creates new one.
This feature is experimental and disabled by default. To use it, please contact us on: integracje@bliskapaczka.pl.

Try it out:

curl -X POST https://api.sandbox-bliskapaczka.pl/v1/order/advice/todoor \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "senderFirstName":"Sender",
    "senderLastName":"Sender",
    "senderPhoneNumber":"123456789",
    "senderEmail":"sender@example.com",
    "senderStreet":"Rynek",
    "senderBuildingNumber":"1",
    "senderFlatNumber":"1",
    "senderPostCode":"00-000",
    "senderCity":"Wroclaw",
    "receiverFirstName":"Receiver",
    "receiverLastName":"Receiver",
    "receiverPhoneNumber":"987654321",
    "receiverEmail":"receiver@example.com",
    "receiverStreet":"Testowa",
    "receiverBuildingNumber":"1",
    "receiverFlatNumber":null,
    "receiverPostCode":"12-345",
    "receiverCity":"Testowe",
    "receiverCountryCode":"PL",
    "operatorName":"DPD",
    "additionalInformation": "Some additional information",
    "parcels":[{
      "dimensions":{
        "height":20,
        "length":20,
        "width":20,
        "weight":20
      },
      "insuranceValue":1200.00
    }],
    "codValue":110,
    "serviceId": "SAME_DAY_18_22"
  }'

Example response:

{
    "number": "000000001P-000000073",
    "senderFirstName": "Sender",
    "senderLastName": "Sender",
    "senderPhoneNumber": "123456789",
    "senderEmail": "sender@example.com",
    "senderStreet": "Rynek",
    "senderBuildingNumber": "1",
    "senderFlatNumber": "1",
    "senderPostCode": "00-000",
    "senderCity": "Wroclaw",
    "receiverFirstName": "Receiver",
    "receiverLastName": "Receiver",
    "receiverPhoneNumber": "987654321",
    "receiverEmail": "receiver@example.com",
    "receiverStreet":"Testowa",
    "receiverBuildingNumber":"1",
    "receiverFlatNumber":null,
    "receiverPostCode":"12-345",
    "receiverCity":"Testowe",
    "operatorName": "DPD",
    "additionalInformation": "Some additional information",
    "parcels": [{
        "dimensions": {
            "length": 20,
            "height": 20,
            "width": 20,
            "weight": 20
        },
        "insuranceValue": null
    }],
    "codValue":110,
    "codPayoutBankAccountNumber":"16102019120000910201486273",
    "chooseDestinationPoint": false,
    "status": "PROCESSING",
    "deliveryType": "TO_DOOR",
    "creationDate": "2017-11-28T14:45:29.195",
    "adviceDate": null,
    "trackingNumber": null,
    "postingPostCode": "31-274",
    "postingCity": "Kraków",
    "postingStreet": "Opolska 9",
    "destinationPostCode": "30-624",
    "destinationCity": "Kraków",
    "destinationStreet": "Malborska 130",
    "orderItems": [{
        "itemType": "SHIPMENT",
        "price": {
            "net": 8.25,
            "vat": 1.90,
            "gross": 10.15
        }
    }],
    "price": {
        "net": 8.25,
        "vat": 1.90,
        "gross": 10.15
    }
}
Cancel
POST /v1/order/$number/cancel

Cancel order. Triggers cancellation process. When orders is already advised its status is changed to MARKED_FOR_CANCELLATION for 24 hours, then operator status is checked whether the order was sent and if not its status is changed to CANCELLED

Try it out:

curl -X POST https://api.sandbox-bliskapaczka.pl/v1/order/000000001P-000000072/cancel \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

Example response:

{
    "number": "000000001P-000000072",
    "senderFirstName": "Sender",
    "senderLastName": "Sender",
    "senderPhoneNumber": "123456789",
    "senderEmail": "sender@example.com",
    "senderStreet": "Rynek",
    "senderBuildingNumber": "1",
    "senderFlatNumber": "1",
    "senderPostCode": "00-000",
    "senderCity": "Wroclaw",
    "receiverFirstName": "Receiver",
    "receiverLastName": "Receiver",
    "receiverPhoneNumber": "987654321",
    "receiverEmail": "receiver@example.com",
    "receiverStreet": "Ulica",
    "receiverBuildingNumber": "1A",
    "receiverFlatNumber": "2B",
    "receiverPostCode": "99-999",
    "receiverCity": "Kraków",
    "receiverCountryCode": "PL",
    "operatorName": "INPOST",
    "destinationCode": "KRA010",
    "postingCode": "KRA011",
    "additionalInformation": null,
    "parcels": [{
        "dimensions": {
            "length": 20,
            "height": 20,
            "width": 20,
            "weight": 20
        },
        "insuranceValue": null
    }],
    "codValue":110,
    "codPayoutBankAccountNumber":"16102019120000910201486273",
    "chooseDestinationPoint": false,
    "status": "MARKED_FOR_CANCELLATION",
    "deliveryType": "TO_POINT",
    "creationDate": "2017-11-28T14:45:29.195",
    "adviceDate": null,
    "trackingNumber": null,
    "postingPostCode": "31-274",
    "postingCity": "Kraków",
    "postingStreet": "Opolska 9",
    "destinationPostCode": "30-624",
    "destinationCity": "Kraków",
    "destinationStreet": "Malborska 130",
    "orderItems": [{
        "itemType": "SHIPMENT",
        "price": {
            "net": 8.25,
            "vat": 1.90,
            "gross": 10.15
        }
    }],
    "price": {
        "net": 8.25,
        "vat": 1.90,
        "gross": 10.15
    }
}
Retry
POST /v1/order/$number/retry

Retry order advice. Used to trigger order processing when given order is in ERROR status and that error reason allows for this action.

Available for orders in status ERROR with reasons:
  • GENERIC_ADVICE_ERROR

  • AUTHORIZATION_ERROR

  • LABEL_GENERATION_ERROR

  • WAYBILL_PROCESS_ERROR

  • BACKEND_ERROR

Try it out:

curl -X POST https://api.sandbox-bliskapaczka.pl/v1/order/000000001P-000000072/retry \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

Response: no body

GET /v1/order/$number/accessLink

It is possible to let end user choose parcel destination. This endpoint Returns order with access link that can be sent to end user to pick destination point. Bliskapaczka.pl post about the feature

Try it out:

curl -X GET https://api.sandbox-bliskapaczka.pl/v1/order/000000001P-000000002/accessLink \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

Example response:

{
    "number": "000000001P-000000002",
    "senderFirstName": "IamTest",
    "senderLastName": "IamTest",
    "senderPhoneNumber": "123456789",
    "senderEmail": "testuser@example.com",
    "senderStreet": "Testowa",
    "senderBuildingNumber": "1",
    "senderFlatNumber": "2",
    "senderPostCode": "12-345",
    "senderCity": "Testowe",
    "receiverFirstName": "IamTest",
    "receiverLastName": "IamTest",
    "receiverPhoneNumber": "912345678",
    "receiverEmail": "testuser@example.com",
    "receiverStreet": "Ulica",
    "receiverBuildingNumber": "1A",
    "receiverFlatNumber": "2B",
    "receiverPostCode": "99-999",
    "receiverCity": "Kraków",
    "receiverCountryCode": "PL",
    "operatorName": null,
    "destinationCode": null,
    "postingCode": null,
    "additionalInformation": null,
    "parcels": [{
        "dimensions": {
            "length": 10,
            "height": 10,
            "width": 10,
            "weight": 10
        },
        "insuranceValue": null
    }],
    "codValue":110,
    "codPayoutBankAccountNumber":"16102019120000910201486273",
    "chooseDestinationPoint": true,
    "status": "SAVED",
    "deliveryType": "TO_POINT",
    "creationDate": "2017-11-28T12:52:02.441",
    "adviceDate": null,
    "trackingNumber": null,
    "postingPostCode": null,
    "postingCity": null,
    "postingStreet": null,
    "destinationPostCode": null,
    "destinationCity": null,
    "destinationStreet": null,
    "orderItems": [],
    "price": null,
    "tokenLink": "https://sandbox-bliskapaczka.pl/wybierz-punkt/115b902709f34c1eb417fc22125dce84"
}
Notify
POST /v1/order/$number/notify

Sends email notification to end user to choose destination point.

Try it out:

curl -X POST https://api.sandbox-bliskapaczka.pl/v1/order/000000001P-000000072/notify \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

Example response:

{
    "number": "000000001P-000000072",
    "senderFirstName": "IamTest",
    "senderLastName": "IamTest",
    "senderPhoneNumber": "123456789",
    "senderEmail": "testuser@example.com",
    "senderStreet": "Testowa",
    "senderBuildingNumber": "1",
    "senderFlatNumber": "2",
    "senderPostCode": "12-345",
    "senderCity": "Testowe",
    "receiverFirstName": "Marcin",
    "receiverLastName": "dfgfd",
    "receiverPhoneNumber": "912345678",
    "receiverEmail": "marcin.architek@sendit.pl",
    "receiverStreet": "Ulica",
    "receiverBuildingNumber": "1A",
    "receiverFlatNumber": "2B",
    "receiverPostCode": "99-999",
    "receiverCity": "Kraków",
    "receiverCountryCode": "PL",
    "operatorName": null,
    "destinationCode": null,
    "postingCode": null,
    "additionalInformation": null,
    "parcels": [{
        "dimensions": {
            "length": 10,
            "height": 10,
            "width": 10,
            "weight": 10
        },
        "insuranceValue": null
    }],
    "codValue":110,
    "codPayoutBankAccountNumber":"16102019120000910201486273",
    "chooseDestinationPoint": true,
    "status": "SAVED",
    "deliveryType": "TO_POINT",
    "creationDate": "2017-11-28T15:14:13.761",
    "adviceDate": null,
    "trackingNumber": null,
    "postingPostCode": null,
    "postingCity": null,
    "postingStreet": null,
    "destinationPostCode": null,
    "destinationCity": null,
    "destinationStreet": null,
    "orderItems": [],
    "price": null,
    "tokenLink": "https://sandbox-bliskapaczka.pl/wybierz-punkt/96b3e12da0704357a335e05beda47c8d"
}
Return
POST /v1/order/return

Save return order. Updates existing order when body parameter "number" is provided or creates new one.
Return order is an order paid by the user but sent by the end user (customer).

Try it out:

curl -X POST https://api.sandbox-bliskapaczka.pl/v1/order/return \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "senderFirstName": "Sender",
    "senderLastName": "Sender",
    "senderPhoneNumber": "123456789",
    "senderEmail": "sender@example.com",
    "senderStreet": "Rynek",
    "senderBuildingNumber": "1",
    "senderFlatNumber": "1",
    "senderPostCode": "00-000",
    "senderCity": "Wroclaw",
    "receiverFirstName": "Receiver",
    "receiverLastName": "Receiver",
    "receiverPhoneNumber": "987654321",
    "receiverEmail": "receiver@example.com",
    "operatorName": "INPOST",
    "destinationCode": "KRA010",
    "additionalInformation": "Some additional information",
    "parcel": {
        "dimensions": {
            "height": 20,
            "length": 20,
            "width": 20,
            "weight": 20
        }
    },
    "insuranceValue": 1000
}'

Example response:

{
	"number": "000000001P-Z00000001",
	"returnLink": "https://bliskapaczka.pl/zwrot/bacb02ceee564703abd84077ea21809c"
}
Available services
POST /v1/order/services

Returns services available for posted order details.

Try it out:

curl -X POST https://api.sandbox-bliskapaczka.pl/v1/order/services \
  -H "Accept: application/json" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
	"senderFirstName":"Sender",
	"senderLastName":"Sender",
	"senderPhoneNumber":"666777888",
	"senderEmail":"sender@example.com",
	"senderStreet":"Rynek",
	"senderBuildingNumber":"1",
	"senderFlatNumber":"1",
	"senderPostCode":"53-019",
	"senderCity":"Wrocław",
	"receiverFirstName":"Receiver",
	"receiverLastName":"Receiver",
	"receiverPhoneNumber":"987654321",
	"receiverEmail":"receiver@example.com",
	"receiverStreet":"Wagonowa",
	"receiverBuildingNumber":"2b",
	"receiverFlatNumber":null,
	"receiverPostCode":"53-019",
	"receiverCity":"Wrocław",
	"operatorName":"XPRESS",
	"parcels":[
		{
			"dimensions":{
				"height":20,
				"length":20,
				"width":20,
				"weight":20
			},
			"insuranceValue":150
		}
	],
	"codValue":11.1,
	"codPayoutBankAccountNumber":"61109010140000071219812874",
	"serviceType": "COUNTRY"
}'

Example response:

[
    "SAME_DAY_18_22"
]

Pricing

Bliskapaczka.pl pricing api.

To point

Bliskapaczka.pl to point pricing api.

POST /v1/pricing/

Returns pricing for given parcel according to the user configuration from https://bliskapaczka.pl/panel/narzedzia/integracja.

Try it out:

  curl -X POST https://api.sandbox-bliskapaczka.pl/v1/pricing \
    -H 'authorization: Bearer xxxx-xxxx-xxxx-xxxx' \
    -H 'content-type: application/json' \
    -d '{
  	"parcel":{
  		"dimensions":{
  			"length":10,
  			"width":10,
  			"height":10,
  			"weight":1
  		},
  		"insuranceValue":10
  	},
  	"codValue":10
  }'

Example response:

[
	{
		"operatorName": "DPD",
		"operatorFullName": "DPD",
		"availabilityStatus": true,
		"price": {
			"net": 4.07,
			"vat": 0.93,
			"gross": 5.00
		},
		"unavailabilityReason": null
	},
	{
		"operatorName": "RUCH",
		"operatorFullName": "Ruch",
		"availabilityStatus": true,
		"price": {
			"net": 4.07,
			"vat": 0.93,
			"gross": 5.00
		},
		"unavailabilityReason": null
	},
	{
		"operatorName": "INPOST",
		"operatorFullName": "Inpost",
		"availabilityStatus": true,
		"price": {
			"net": 4.07,
			"vat": 0.93,
			"gross": 5.00
		},
		"unavailabilityReason": null
	},
	{
		"operatorName": "POCZTA",
		"operatorFullName": "Poczta Polska",
		"availabilityStatus": false,
		"price": null,
		"unavailabilityReason": {
			"errors": [
				{
					"messageCode": "pl.bliskapaczka.pricing.unavailable.noShipmentOffer",
					"message": "No shipment offer available",
					"field": null,
					"value": null
				}
			]
		}
	}
]
To door

Bliskapaczka.pl to door pricing api.

POST /v1/pricing/todoor

Returns pricing for given courier parcel according to the user configuration from https://bliskapaczka.pl/panel/narzedzia/integracja.

Try it out:

  curl -X POST https://api.sandbox-bliskapaczka.pl/v1/pricing/todoor \
    -H 'authorization: Bearer xxxx-xxxx-xxxx-xxxx' \
    -H 'content-type: application/json' \
    -d '{
  	"parcel":{
  		"dimensions":{
  			"length":10,
  			"width":10,
  			"height":10,
  			"weight":1
  		},
  		"insuranceValue":10,
  	},
  	"codValue":10
  }'

Example response:

[
	{
		"operatorName": "DPD",
		"operatorFullName": "DPD",
		"availabilityStatus": true,
		"price": {
			"net": 4.07,
			"vat": 0.93,
			"gross": 5.00
		},
		"unavailabilityReason": null
	},
	{
		"operatorName": "INPOST",
		"operatorFullName": "Inpost",
		"availabilityStatus": true,
		"price": {
			"net": 4.07,
			"vat": 0.93,
			"gross": 5.00
		},
		"unavailabilityReason": null
	},
	{
		"operatorName": "GLS",
		"operatorFullName": "GLS",
		"availabilityStatus": false,
		"price": null,
		"unavailabilityReason": {
			"errors": [
				{
					"messageCode": "pl.bliskapaczka.pricing.unavailable.noShipmentOffer",
					"message": "No shipment offer available",
					"field": null,
					"value": null
				}
			]
		}
	}
]

Report

Bliskapaczka.pl reports utilities.

Pickup confirmation
GET /v1/report/pickupconfirmation

Query parameters:

Name Type Description

numbers

String[]

required
order numbers for pickup report

Returns pickup confirmation report for given order numbers

Given order numbers must:
  • have same operatorName

  • be in "READY_TO_SEND" status

Try it out:

curl -X GET https://api.sandbox-bliskapaczka.pl/v1/report/pickupconfirmation?numbers=000000001P-0000000001,000000001P-0000000002 \
  -H "Accept: application/pdf" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

Response: PDF

Pickup confirmation for operator
GET /v1/report/pickupconfirmation/$operator

Query parameters:

Name Type Description

startPeriod

DateTime

Optional

endPeriod

DateTime

Optional

Returns pickup confirmation report for given operator orders in status 'READY_TO_SEND'.

Try it out:

curl -X GET https://api.sandbox-bliskapaczka.pl/v1/report/pickupconfirmation/ruch?startPeriod=2017-10-23T12:00:00 \
  -H "Accept: application/pdf" \
  -H "Authorization: Bearer xxxx-xxxx-xxxx-xxxx"

Response: PDF

Release notes

v2

New delivery types

Delivery types P2P, D2P, P2D and D2D are now available. TO_POINT and TO_DOOR are no longer available.

"todoor" endpoints removed

Dedicated endpoints to save or advice shipments to door were removed. Generic save and advice endpoints should be used instead. A proper delivery type is required in the request body.

Waybills collection returned instead of single waybill

When asking for a waybill for a shipment, the collection is returned instead of a single object. It allows to handle shipments with multiple parcels.

"Reference" field in order

When saving or advising an order, a reference can be added to it. This reference is passed on to operators and can be used to link Bliska Paczka order with an external order.