Neoship Api (1.0.0)

Login to Neoship to obtain a token

Refresh JWT token after expriation

Create new package

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

Combined endpoint that creates packages and immediately prints stickers in a single call. The label PDF is saved to storage (accessible via GET /package/{id}/label) and is not returned in the response.

This endpoint combines the functionality of POST /package/bulk/{shipper_id} (package creation) and POST /package/bulk/ with action=send_print_sticker (sticker printing) into one atomic operation.

Info package

Edit package which has not been exported

Delete package which has not been exported

Downloads the label PDF for a package that has been exported (sticker printed). The label must have been previously generated via POST /package/bulk/ with action=send_print_sticker or via POST /package/bulk-create-and-print/{shipper_id}.

Cancel package. Cancels the shipment at the shipper and marks the package as cancelled. Reference number is prefixed with X. Only packages in shipping (not yet exported) or service packages can be cancelled.

List of packages

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.

Bulk action for getting stickers or acceptance protocol.

Calculate available package shipping quotes for the authenticated user.

Calculate available package shipping quotes for a selected user. The response includes purchase prices when available.

Detail about user

List of parcelshop

Detail of parcelshop

Tracking of packages by tracking number. This is usefull, if you want to show the information in your app.

Tracking of packages by reference number and user id. This tracking is returning the page with the styles, not needed parsing response or anything else.

Tracking of packages by tracking number. This tracking is returning the page with the styles, not needed parsing response or anything else.

The parcelshop picker is an embeddable map UI for selecting a delivery point. It is intended for checkout or shipment forms where the customer chooses a parcelshop.

For usage on your own domain, create a parcelshop picker API key in Neoship and store the exact parent page origin for that key, for example https://eshop.example. One key can have multiple allowed origins in Neoship.

Use https://aplikacia.neoship.sk for production and https://t-we-nshp-webapp-01-app.azurewebsites.net for testing.

JavaScript integration

Load the versioned JavaScript library on your page:

<script src="https://aplikacia.neoship.sk/parcelshop-picker/v1/library.js"></script>

Open the picker:

<button type="button" id="open-picker">Choose parcelshop</button>

<script>
  const apiKey = "XXXXXXXXXXXXX";

  document.getElementById("open-picker").addEventListener("click", () => {
    window.NeoshipParcelshopPicker.pick(apiKey, (parcelshop) => {
      if (parcelshop === null) {
        // Picker was closed without selection.
        return;
      }

      // Save parcelshop.parcelshopId into your order/package parcelshop field.
      console.log(parcelshop);
    });
  });
</script>

pick() opens the picker in a full-screen iframe dialog, validates messages from the iframe origin, dispatches the neoship:parcelshop-picker:selected browser event, and closes the previous picker before opening a new one.

Selection payload

The selected parcelshop payload has this shape:

{
  "shipperId": "3",
  "ownPlace": false,
  "parcelshopId": "12345",
  "name": "Parcelshop name",
  "street": "Main street 1",
  "zip": "81101",
  "city": "Bratislava",
  "stateCode": "SK",
  "lat": 48.1486,
  "lng": 17.1077,
  "openingHours": "Pondelok: 08:30 - 18:30; Utorok: 08:30 - 18:30; Streda: 08:30 - 18:30",
  "kind": "parcelshop",
  "boxType": "PS",
  "price": "2,90 €"
}

Use parcelshopId as the parcelshop value when creating a parcelshop package. For persisting the selected parcelshop on an order so a Neoship connector can create the shipment later, see the Storing a selected parcelshop guide.

JavaScript API

const picker = window.NeoshipParcelshopPicker.pick(apiKey, callback, options);
picker.setPrices(rules);
picker.close();
window.NeoshipParcelshopPicker.close();

You can also use object-style arguments:

window.NeoshipParcelshopPicker.pick({
  apiKey: "XXXXXXXXXXXXX",
  selectedShipper: "GLS",
  availableShippers: ["GLS", "Packeta"],
  countries: ["SK", "CZ"],
  language: "sk-SK",
  autoZoomToUser: true,
  markerIcons: "alt",
  prices: [
    { price: "3,90 €" },
    { kind: "box", price: "2,90 €" },
    { shipper: "Packeta", country: "CZ", price: "89 Kč" },
    { shipper: "SPS", price: "Zdarma" },
  ],
  onSelect: (parcelshop) => {},
  onClose: () => {},
});

The callback receives the selected parcelshop payload. If the picker is closed without selection, the callback receives null. close() closes the currently open picker, which is useful for single-page applications and host-page modal cleanup. pick() returns a handle with close() and setPrices(rules); the latter replaces the price rules while the picker is open, for example when the cart total crosses a free-shipping threshold.

Options

These options can be passed in the options object, or in the object-style pick({...}) call.

When the library is loaded from https://aplikacia.neoship.sk/parcelshop-picker/v1/library.js, the default picker iframe opens https://aplikacia.neoship.sk/neoship/parcelshop-picker/ even when the script is embedded on another domain. You can override this only with url or pickerUrl in advanced integrations.

Prices

The picker does not know your shipping prices; you pass them as rules and it shows the matching one on every place. Each rule is an object with a price text and up to three optional selectors:

When several rules match a place, the most specific one wins: shipper outranks kind, which outranks country, so shipper + kind + country beats shipper + kind, which beats shipper + country, which beats shipper alone, and a rule naming no selector is the fallback for everything. Between rules of equal specificity the first one in the array wins. A place that matches no rule shows no price.

prices: [
  { price: "3,90 €" },                                   // fallback for everything
  { kind: "box", price: "2,90 €" },                      // every locker
  { shipper: "GLS", kind: "box", price: "2,50 €" },      // GLS lockers only
  { shipper: "Packeta", country: "CZ", price: "89 Kč" }, // Packeta in Czechia
  { shipper: "SPS", price: "Zdarma" },                   // every SPS place
]

The rules are sent into the iframe with postMessage once the picker reports neoship:parcelshop-picker:ready; they must therefore be JSON-serialisable. Sending a new array replaces the previous rules, and an empty array removes all prices.

Own pickup places

Besides carrier parcelshops, the picker can offer your own pickup places, for example your store or warehouse. You manage them in Neoship under Parcelshopy → Osobný odber; nothing changes in your integration. Every picker opened with your API key shows your active places automatically, next to the carrier parcelshops:

• They appear on the map, in search results and in the detail panel like any other place, and the carrier filter gets an extra entry for them. You set its name in Parcelshopy → Nastavenia mapy; without one it reads Osobný odber in the picker's language. The same page takes your own map pin and list icon.
• The selection payload carries shipperId: "own", ownPlace: true and your place code as parcelshopId.
• The type filter treats them as parcelshop, so they stay visible unless the customer picks only other types.
• A price set on the place is shown instead of your prices rules. Places without one follow the rules like any other place; use shipper: "own" to price them separately.
• When you restrict the carriers with availableShippers, include own to keep your places; selectedShipper: "own" opens the picker on them alone.
• The price, opening hours and filter entry name can be translated in Neoship. The picker shows them in its language and falls back to the Slovak text when a translation is missing.
• They are not used for the location hints the picker suggests from the customer's position.

Manual iframe integration

The JavaScript library is recommended. If you need to render the iframe manually, use the picker page directly and handle window.postMessage yourself:

<iframe
  src="https://aplikacia.neoship.sk/neoship/parcelshop-picker/?apiKey=XXXXXXXXXXXXX&selected_shipper=GLS&available_shippers=GLS,Packeta&countries=SK,CZ&language=sk-SK&marker_icons=alt"
  title="Výber parcelshopu"
  allow="geolocation"
  style="width: 100%; height: 700px; border: 0;"
></iframe>

const pickerOrigin = "https://aplikacia.neoship.sk";
const iframe = document.querySelector("iframe");

window.addEventListener("message", (event) => {
  if (event.origin !== pickerOrigin) {
    return;
  }

  const message = event.data || {};

  if (message.type === "neoship:parcelshop-picker:ready") {
    // Optional: attach your prices once the picker is up (see Prices above).
    iframe.contentWindow.postMessage(
      { type: "neoship:parcelshop-picker:prices", detail: { prices: [{ price: "2,90 €" }] } },
      pickerOrigin,
    );
  }

  if (message.type === "neoship:parcelshop-picker:selected") {
    const parcelshop = message.detail;
    // Save parcelshop.parcelshopId into your order/package parcelshop field.
  }

  if (message.type === "neoship:parcelshop-picker:close") {
    // Close your modal or hide the iframe.
  }
});

Posted messages

The iframe sends these message types to the parent window:

• neoship:parcelshop-picker:ready - picker loaded and initialized
• neoship:parcelshop-picker:selected - user selected a parcelshop
• neoship:parcelshop-picker:error - picker initialization or data loading failed
• neoship:parcelshop-picker:close - user clicked close or pressed Escape

Received messages

The iframe accepts these message types from its parent window (iframe.contentWindow.postMessage(message, pickerOrigin)):

• neoship:parcelshop-picker:prices - detail.prices is an array of price rules as described in the Prices section above. Send it after neoship:parcelshop-picker:ready; send it again to replace the rules.