This API documentation describes the individual integration options with the Neoship
URL address for production API: https://apiserver.neoship.sk/api
URL address for test API: http://server.neoship.sk/api
1. Obtain the token
The first step is to authenticate the user using its credentials via login.
2. Use the token
Simply pass the token on each request to header
Authorization: Bearer {token}
Note about token expiration
Each request after token expiration (3600 seconds) will result in a 401 response. Redo the authentication process to obtain a new token or you can refresh our expired token.
Security Scheme Type | HTTP |
---|---|
HTTP Authorization Scheme | bearer |
Bearer format | "JWT" |
Login to Neoship to obtain a token
username | string non-empty Name of user for log into application (usually email) |
password | string non-empty The user password used for login |
{- "username": "username@login.com",
- "password": "AC123456"
}
{- "token": "eyjiioajsiodj...",
- "refresh_token": "23165c5..."
}
Refresh JWT token after expriation
refresh_token | string non-empty Refresh token returned in succesfull login action |
{- "refresh_token": "85fc4162fa3195bfa662b9bd759b3dae2e3a..."
}
{- "token": "eyjiioajsiodj...",
- "refresh_token": "23165c5..."
}
Create new package
shipper_id required | integer The id of shipper: |
Echo payload
reference_number | string non-empty Reference number of package |
sender_name | string non-empty Full name of the sender |
sender_company | string Company of the sender |
sender_street | string non-empty Street of the sender (house number can be INCLUDED depends on situation) |
sender_house_number | string House number of the sender |
sender_city | string non-empty City of the sender |
sender_zip | string non-empty Postal code of the sender |
sender_state_code | string non-empty State code of the sender |
sender_email | string non-empty Email of the sender |
sender_phone | string non-empty Phone of the sender |
receiver_name | string non-empty Full name of the receiver |
receiver_company | string Company of the receiver |
receiver_street | string non-empty Street of the receiver (house number can be INCLUDED depends of situation) |
receiver_house_number | string House number of the receiver |
receiver_city | string non-empty City of the receiver |
receiver_zip | string non-empty Postal code of the receiver |
receiver_state_code | string non-empty State code of the receiver |
receiver_email | string non-empty Email of the receiver |
receiver_phone | string non-empty Phone of the receiver |
cod_price | number Amount of cash on delivery (In the currency of the destination country) |
cod_currency_code | string Currency of cash on delivery |
cod_reference | string Reference of cash on delivery (REQUIRED in DPD if defined, possible define in GLS and 123Kuriér) |
insurance | number Amount of insurance (EUR) |
reverse | boolean non-empty Reverse shipment |
parcelshop | string ID of parcelshop (Required for parcelshop package) |
count_of_packages | number The number of packages to be created. |
weight | number Weight of package in kilograms (for Packeta only). Allowed range is 0 < weight <= 10. |
carrier_type | number ID of carrier type for address delivery (for Packeta only). |
{- "reference_number": "AC123456",
- "sender_name": "John Doe",
- "sender_company": "John Doe",
- "sender_street": "Charles street",
- "sender_house_number": "3852/9",
- "sender_city": "Bratislava",
- "sender_zip": 81101,
- "sender_state_code": "SK",
- "sender_email": "test@neoship.sk",
- "sender_phone": "0900123456",
- "receiver_name": "John Doe",
- "receiver_company": "John Doe",
- "receiver_street": "Charles street",
- "receiver_house_number": "3852/9",
- "receiver_city": "Bratislava",
- "receiver_zip": 81101,
- "receiver_state_code": "SK",
- "receiver_email": "test@neoship.sk",
- "receiver_phone": "0900123456",
- "cod_price": 55.25,
- "cod_currency_code": "EUR",
- "cod_reference": 984686,
- "insurance": 230.2,
- "reverse": false,
- "parcelshop": "PS-BBMK0269",
- "count_of_packages": 2,
- "weight": 1,
- "carrier_type": 131
}
{- "id": 42,
- "reference_number": "AC123456"
}
Bulk action to create new packages. Packages are created only if all values are valid. If one package is invalid no one package is created
shipper_id required | integer The id of shipper: |
Echo payload
reference_number | string non-empty Reference number of package |
sender_name | string non-empty Full name of the sender |
sender_company | string Company of the sender |
sender_street | string non-empty Street of the sender (house number can be INCLUDED depends on situation) |
sender_house_number | string House number of the sender |
sender_city | string non-empty City of the sender |
sender_zip | string non-empty Postal code of the sender |
sender_state_code | string non-empty State code of the sender |
sender_email | string non-empty Email of the sender |
sender_phone | string non-empty Phone of the sender |
receiver_name | string non-empty Full name of the receiver |
receiver_company | string Company of the receiver |
receiver_street | string non-empty Street of the receiver (house number can be INCLUDED depends of situation) |
receiver_house_number | string House number of the receiver |
receiver_city | string non-empty City of the receiver |
receiver_zip | string non-empty Postal code of the receiver |
receiver_state_code | string non-empty State code of the receiver |
receiver_email | string non-empty Email of the receiver |
receiver_phone | string non-empty Phone of the receiver |
cod_price | number Amount of cash on delivery (In the currency of the destination country) |
cod_currency_code | string Currency of cash on delivery |
cod_reference | string Reference of cash on delivery (REQUIRED in DPD if defined, possible define in GLS and 123Kuriér) |
insurance | number Amount of insurance (EUR) |
reverse | boolean non-empty Reverse shipment |
parcelshop | string ID of parcelshop (Required for parcelshop package) |
count_of_packages | number The number of packages to be created. |
weight | number Weight of package in kilograms (for Packeta only). Allowed range is 0 < weight <= 10. |
carrier_type | number ID of carrier type for address delivery (for Packeta only). |
[- {
- "reference_number": "AC123456",
- "sender_name": "John Doe",
- "sender_company": "John Doe",
- "sender_street": "Charles street",
- "sender_house_number": "3852/9",
- "sender_city": "Bratislava",
- "sender_zip": 81101,
- "sender_state_code": "SK",
- "sender_email": "test@neoship.sk",
- "sender_phone": "0900123456",
- "receiver_name": "John Doe",
- "receiver_company": "John Doe",
- "receiver_street": "Charles street",
- "receiver_house_number": "3852/9",
- "receiver_city": "Bratislava",
- "receiver_zip": 81101,
- "receiver_state_code": "SK",
- "receiver_email": "test@neoship.sk",
- "receiver_phone": "0900123456",
- "cod_price": 55.25,
- "cod_currency_code": "EUR",
- "cod_reference": 984686,
- "insurance": 230.2,
- "reverse": false,
- "parcelshop": "PS-BBMK0269",
- "count_of_packages": 2,
- "weight": 1,
- "carrier_type": 131
}
]
[- {
- "id": 42,
- "reference_number": "AC123456"
}
]
Info package
package_id required | string Id of package |
{- "id": 42,
- "reference_number": "AC123456",
- "sender_name": "John Doe",
- "sender_company": "John Doe",
- "sender_street": "Charles street",
- "sender_house_number": "3852/9",
- "sender_city": "Bratislava",
- "sender_zip": 81101,
- "sender_state_code": "SK",
- "sender_email": "test@neoship.sk",
- "sender_phone": "0900123456",
- "receiver_name": "John Doe",
- "receiver_company": "John Doe",
- "receiver_street": "Charles street",
- "receiver_house_number": "3852/9",
- "receiver_city": "Bratislava",
- "receiver_zip": 81101,
- "receiver_state_code": "SK",
- "receiver_email": "test@neoship.sk",
- "receiver_phone": "0900123456",
- "cod_price": 55.25,
- "cod_currency_code": "EUR",
- "cod_reference": 984686,
- "insurance": 230.2,
- "reverse": false,
- "parcelshop": "PS-BBMK0269",
- "weight": 3.8,
- "tracking_number": "Z123654987",
- "cod_payment": 1,
- "shipper": {
- "id": 2,
- "name": "Slovak Parcel Service",
- "shortcut": "SPS"
}, - "statuses": [
- {
- "status_type": {
- "id": 251,
- "name": "Exportovaná"
}
}
], - "is_service": false,
- "price_vat": 4.59,
- "invoice_number": 4110075779,
- "invoice_date": "2021-08-04T00:00:00.000Z"
}
Edit package which has not been exported
package_id required | string Id of package |
Echo payload
reference_number | string non-empty Reference number of package |
sender_name | string non-empty Full name of the sender |
sender_company | string Company of the sender |
sender_street | string non-empty Street of the sender |
sender_house_number | string House number of the sender |
sender_city | string non-empty City of the sender |
sender_zip | string non-empty Postal code of the sender |
sender_state_code | string non-empty State code of the sender |
sender_email | string non-empty Email of the sender |
sender_phone | string non-empty Phone of the sender |
receiver_name | string non-empty Full name of the receiver |
receiver_company | string Company of the receiver |
receiver_street | string non-empty Street of the receiver |
receiver_house_number | string House number of the receiver |
receiver_city | string non-empty City of the receiver |
receiver_zip | string non-empty Postal code of the receiver |
receiver_state_code | string non-empty State code of the receiver |
receiver_email | string non-empty Email of the receiver |
receiver_phone | string non-empty Phone of the receiver |
cod_price | number Amount of cash on delivery (In the currency of the destination country) |
cod_currency_code | string Currency of cash on delivery |
cod_reference | string Reference of cash on delivery (REQUIRED in DPD if defined, possible define in GLS and 123Kuriér) |
insurance | number Amount of insurance (EUR) |
reverse | boolean non-empty Reverse shipment |
parcelshop | string ID of parcelshop (Required for parcelshop package) |
count_of_packages | number The number of packages to be created. |
weight | number Weight of package in kilograms (for Packeta only). Allowed range is 0 < weight <= 10. |
carrier_type | number ID of carrier type for address delivery (for Packeta only). |
{- "reference_number": "AC123456",
- "sender_name": "John Doe",
- "sender_company": "John Doe",
- "sender_street": "Charles street",
- "sender_house_number": "3852/9",
- "sender_city": "Bratislava",
- "sender_zip": 81101,
- "sender_state_code": "SK",
- "sender_email": "test@neoship.sk",
- "sender_phone": "0900123456",
- "receiver_name": "John Doe",
- "receiver_company": "John Doe",
- "receiver_street": "Charles street",
- "receiver_house_number": "3852/9",
- "receiver_city": "Bratislava",
- "receiver_zip": 81101,
- "receiver_state_code": "SK",
- "receiver_email": "test@neoship.sk",
- "receiver_phone": "0900123456",
- "cod_price": 55.25,
- "cod_currency_code": "EUR",
- "cod_reference": 984686,
- "insurance": 230.2,
- "reverse": false,
- "parcelshop": "PS-BBMK0269",
- "count_of_packages": 2,
- "weight": 1,
- "carrier_type": 131
}
{- "cod_price": [
- "Cannot be blank"
], - "sender_zip": [
- "Not valid postal code"
], - "...": [ ]
}
List of packages
page | integer The number of page |
rows_per_page | integer The numbers of items to return |
reference_number | string Packages with the specified reference number |
tracking_number | string Packages with the specified tracking number |
{- "rows": [
- {
- "id": 42,
- "reference_number": "AC123456",
- "sender_name": "John Doe",
- "sender_company": "John Doe",
- "sender_street": "Charles street",
- "sender_house_number": "3852/9",
- "sender_city": "Bratislava",
- "sender_zip": 81101,
- "sender_state_code": "SK",
- "sender_email": "test@neoship.sk",
- "sender_phone": "0900123456",
- "receiver_name": "John Doe",
- "receiver_company": "John Doe",
- "receiver_street": "Charles street",
- "receiver_house_number": "3852/9",
- "receiver_city": "Bratislava",
- "receiver_zip": 81101,
- "receiver_state_code": "SK",
- "receiver_email": "test@neoship.sk",
- "receiver_phone": "0900123456",
- "cod_price": 55.25,
- "cod_currency_code": "EUR",
- "cod_reference": 984686,
- "insurance": 230.2,
- "reverse": false,
- "parcelshop": "PS-BBMK0269",
- "weight": 3.8,
- "tracking_number": "Z123654987",
- "cod_payment": 1,
- "shipper": {
- "id": 2,
- "name": "Slovak Parcel Service",
- "shortcut": "SPS"
}, - "statuses": [
- {
- "status_type": {
- "id": 251,
- "name": "Exportovaná"
}
}
], - "is_service": false
}
], - "count": 22
}
List of packages by the list of reference numbers. If the list of reference numbers contains invalid reference numbers, the packages corresponding to invalid reference numbers are not included in response content.
Echo payload
reference_numbers | array List of reference numbers. |
{- "reference_numbers": [
- "AB123456",
- "BC987654",
- "..."
]
}
[- {
- "id": 42,
- "reference_number": "AC123456",
- "sender_name": "John Doe",
- "sender_company": "John Doe",
- "sender_street": "Charles street",
- "sender_house_number": "3852/9",
- "sender_city": "Bratislava",
- "sender_zip": 81101,
- "sender_state_code": "SK",
- "sender_email": "test@neoship.sk",
- "sender_phone": "0900123456",
- "receiver_name": "John Doe",
- "receiver_company": "John Doe",
- "receiver_street": "Charles street",
- "receiver_house_number": "3852/9",
- "receiver_city": "Bratislava",
- "receiver_zip": 81101,
- "receiver_state_code": "SK",
- "receiver_email": "test@neoship.sk",
- "receiver_phone": "0900123456",
- "cod_price": 55.25,
- "cod_currency_code": "EUR",
- "cod_reference": 984686,
- "insurance": 230.2,
- "reverse": false,
- "parcelshop": "PS-BBMK0269",
- "weight": 3.8,
- "tracking_number": "Z123654987",
- "cod_payment": 1,
- "shipper": {
- "id": 2,
- "name": "Slovak Parcel Service",
- "shortcut": "SPS"
}, - "statuses": [
- {
- "status_type": {
- "id": 251,
- "name": "Exportovaná"
}
}
], - "is_service": false
}
]
Bulk action for getting stickers or acceptance protocol.
Echo payload
action | string non-empty
send_print_sticker send_print_sticker daily_closing packeta_acceptance_protocol k123_acceptance_protocol |
GLS (string) or SPS (string) or Packeta (string) or Packeta HD (string) or 123Kuriér (string) or DPD (string) Type of format sticker to print | |
sticker_position | number or null Enum: 1 2 3 4 Sticker position if shipper support this option |
reference_numbers | array non-empty Array of packages reference numbers to print |
pickup_date | date non-empty ONLY 123Kuriér accepted |
{- "action": "send_print_sticker",
- "print_type": "A4_2x2",
- "sticker_position": 1,
- "reference_numbers": [
- "ASD1354"
], - "pickup_date": "2022-02-22"
}
{- "labels": "JVBERi0xLjUKJfLz9PX2CjEgMCBvYmoKPD...",
- "errors": [
- {
- "reference_number": "AC123456",
- "package_id": 42,
- "shipper_id": 1,
- "errors": [
- "Cod not allowed for 'Client Id'",
- "..."
]
}
], - "tracking": {
- "<package_id>": {
- "reference_number": "ASD1354",
- "tracking_number": "Z1234567890"
}
}
}
{- "id": 4,
- "username": "AC123456",
- "roles": [ ],
- "credit": 1234.95,
- "variable_number": 2236345,
- "address": {
- "name": "John Doe",
- "company": "John Doe",
- "street": "Charles street",
- "city": "Bratislava",
- "zip": 81101,
- "email": "test@neoship.sk",
- "phone": "0900123456",
- "tin": 534353,
- "oin": 448164,
- "vatin": 146846
}, - "invoice_address": {
- "name": "John Doe",
- "company": "John Doe",
- "street": "Charles street",
- "city": "Bratislava",
- "zip": 81101,
- "email": "test@neoship.sk",
- "phone": "0900123456",
- "tin": 534353,
- "oin": 448164,
- "vatin": 146846
}
}
List of parcelshop
shipper_id required | integer The id of shipper: |
[- {
- "id": 42,
- "parcelshop_id": "AC123456",
- "name": "Tesco Galanta (TABAK PRESS)",
- "street": "Galanta street",
- "city": "Galanta",
- "zip": 81101,
- "state_code": "SK",
- "shipper": "GLS",
- "shipper_id": 2
}
]
Detail of parcelshop
id required | integer Id of parcelshop |
{- "id": 42,
- "parcelshop_id": "AC123456",
- "name": "Tesco Galanta (TABAK PRESS)",
- "street": "Galanta street",
- "city": "Galanta",
- "zip": 81101,
- "state_code": "SK",
- "shipper": "GLS",
- "shipper_id": 2
}
Tracking of packages by tracking number. This is usefull, if you want to show the information in your app.
tracking_number required | string Tracking number of package |
{- "logo": "https:storage.cloud.com/app/logo.png",
- "weight": 2,
- "sender": "SK 02901 Martin",
- "receiver": "SK 03601 Martin",
- "reference_number": 2236345,
- "statuses": {
- "created_at": "2021-09-09T00:00:00.000Z",
- "center": "SPS Hub",
- "name": "Doruceny"
}
}
We provide public iframe of parcelshops, which is also possible to use in many cases for example for showing available list of parcelshops in shopping cart. Depends on language, you have to define callbacks for handle slected parlceshops and then parse and update response data to your order.
shipper_id required | integer The id of shipper: |