Poiint Business API (0.0.1)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Introduction

This is the official documentation for Poiint Business API. It contains all the information required for integration of Poiint Business services into your system. In case of any questions, do not hesitate to contact our tech support.

Testing and Development

Integration with our systems can be tested against a dedicated testing environment. Access must be requested via email. You should never run your tests against Poiint Business Production API. Test API url:

https://api.integration.business.poiint.sk

The submission and label printing are the only operations that involve communication with the system of external carrier. The thing is, that our testing environment cannot communicate with the production environment of the external carrier (because client would be charged for those orders). However, since not all carriers offer a dedicated testing environment that we can integrate with our systems, we are forced to limit testing to the GLS carrier only. This means, that you should test order submission and label printing only with GLS carrier. Submission of order (or getting labels for order) that is handled by someone else than GLS will cause HTTP 500 error response. This limitation does not apply to the production environment.

Web application

Orders created during testing can be managed via Poiint Business web application available here:

https://integration.business.poiint.sk

Contacts

Technical support: it@poiint.sk

Glossary

The following list was created to clarify terminology that may appear in the documentation:

Enrichment - Represents an additional service that can be used when creating an order. These services may be charged, and their use is optional.
Cod - Abbreviation for Cash On Delivery service.
Ins - Abbreviation for Insurance service.
Icc - Abbreviation for ID Card Check service.
Pickup type:
- Regular - The courier visits the selected address at regular intervals without the need for an explicit request of the pickup.
- Irregular - The courier comes for parcels only when explicitly requested.
Delivery type:
- Home - Delivery to "hands" (on specified address).
- Parcel Shop - Delivery to pickup point (e.g. Packeta Z-Box, Z-Point).
Consignee - Recipient of the parcel.
Create order - Save order in our system.
Submit order - Send order to the carrier specified during order creation.

Carriers

Carriers in our system are identified by so called public ID. Below is a list of all carriers and their public IDs.

ID	Carrier Name
1	DPD
2	GLS
3	SPS
4	PACKETA
5	TALIANSKA POSTA HD
6	IE FEDEX HD CONNECT PLUS
7	CHORVATSKA POSTA HD
8	TR FEDEX HD ECONOMY
9	BG SPEEDY HD
10	BG SAMEDAY HD
11	IE FEDEX HD PRIORITY
12	EE VENIPAK HD
13	UA MEEST POSHTA HD
14	LV LITHUANIAN POST HD
15	EE OMNIVA HD
16	HU EXPRESS ONE HD
17	EE LITHUANIAN POST HD
18	FR COLISPRIVE DIRECT HD
19	RO FANCOURIER HD
20	IE FASTWAY HD
21	PT MRW HD
22	ES MRW HD
23	US FEDEX HD PRIORITY
24	RO SAMEDAY HD
25	FI POSTNORD HD
26	BG ECONT HD
27	SI POST HD
28	LV OMNIVA HD
29	SE POSTNORD HD
30	DK POSTNORD HD
31	GB ROYALMAIL48 HD
32	GR ACS HD
33	HU MADARSKA POSTA HD
34	BELGICKA POSTA HD
35	LT VENIPAK HD
36	GR TAXYDROMIKI HD
37	NL DHL HD
38	ES CORREOS HD
39	LV VENIPAK HD
40	TR FEDEX HD PRIORITY
41	BE HOLANDSKA POSTA HD
42	FI MATKAHUOLTO HD
43	GB ROYALMAIL24 HD
44	IT BARTOLINI HD
45	GR ELTA HD
46	IT HRPARCEL HD
47	RO CARGUS HD
48	SWISS POST HD
49	LUXEMBURSKA POSTA HD
50	AE ARAMEX HD
51	HR OVERSEAS HD
52	DE HERMES HD
53	GB FEDEX HD PRIORITY
54	US FEDEX HD ECONOMY
55	NL HOLANDSKA POSTA HD
56	LT OMNIVA HD
57	LT LITHUANIAN POST HD
58	FR COLISSIMO HD
59	GR SPEEDEX HD
60	RAKUSKA POSTA HD
61	SI EXPRESSONE HD

Security

The system is secured using API keys and JSON Web Tokens (JWT). Detailed specification of the security mechanism for each endpoint is provided in endpoint description. To be able to use most of the endpoints, you need a valid access token (JWT). The basic principle involves obtaining an access token using an API key and the Refresh operation. The obtained access token must be set in the HTTP header as Authorization: Bearer <token>. Lifespan of an access token is 4 hours. For proper functioning, it is necessary to regularly request a new token (we recommend doing so 30 minutes before the token expires).

Access Tokens

What is it for?

Authorization in following operations:
- CreateOrder
- SubmitOrder
- GetUnavailablePickupDates
- PrintLabels

What is the lifespan?

4 hours.

Where can I get it?

Response from Refresh operation.

API keys

What is it for?

Authorization in following operations:
- Refresh

What is the lifespan?

6 months.

Where can I get it?

By contacting a technical support.

FAQ

Is it possible to create multiple orders with a single request?

No, you need to call CreateOrder operation multiple times.

Is it possible to submit multiple orders with a single request?

No, you need to call SubmitOrder operation multiple times.

How should the customer of the e-shop choose a carrier?

The customer selects from carriers obtained via the Refresh operation. Only carriers that meet the order's requirements for delivery country, enrichments etc. should be offered to the customer.

Is there any address validation?

Yes, in addition to basic validation, we also check whether the zipcode actually matches the city.

Validations errors

Response body in case of a validation error have a structure of ProblemDetails object. Below is an example from CreateOrder operation.

{
    "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "errors": {
        "Body.Consignee.Name": [
            "NotEmpty"
        ],
        "Body.Consignee.Email": [
            "ValidFormat"
        ],
        "Body.DeliveryAddress.Country": [
            "NotEmpty",
            "ValidFormat"
        ]
    },
    "traceId": "00-74fd6d6a0aa9734689bc534921ff5f92-0916537dea6b633a-00"
}

As you can see, server does not return detailed messages. Instead, it returns validation requirements that caused the failure. In the example above, attribute Consignee.Name cannot be empty, Consignee.Email must be a valid email format etc. List of all validation requirements can be found below. Showing user-friendly error messages is responsibility of API consumer.

Validation Requirement	Description
`NotNull`	Value must not be null.
`NotEmpty`	Value must not be empty.
`Bigger[x]`	Value must be bigger than `x`.
`BiggerOrEq[x]`	Value must be bigger or equal to `x`.
`LessOrEq[x]`	Value must be less or equal to `x`.
`MaxLength[maxLength]`	String length must be less or equal to `maxLength`.
`ValidFormat[pattern]`	Value must match the `pattern`.
`Unique`	Value must be unique.
`ValidCurrency`	Value must be valid currency in ISO 4217 format.
`RequiredCurrency[currency]`	Value must be the currency specified by `currency` parameter.
`SupportedEnrichment`	Enrichment must be supported.
`AvailablePickupDate`	Pickup date must be a valid date for given carrier.
`Number`	Value must be a number.
`ValidCarrier`	Carrier must be valid for given use-case (order).

Download OpenAPI description

openapi.json

openapi.yaml

Servers

Mock server

https://docs.business.poiint.sk/_mock/openapi/

Integration

https://api.integration.business.poiint.sk/

Integration
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Operations

Create order

Request

Used to create an order. Created order is stored in our system, but not submitted to the carrier yet. Order submission is done in separate step using SubmitOrderEndpoint.

Security

Bearer

Headers

X-Sender-Profilestringrequired

Bodyapplication/jsonrequired

carrierPidinteger(int32)required

Public identifier of the carrier chosen for the delivery of the package. Available carriers can be obtained using RefreshEndpoint.

consigneeobject(Dtos.Consignee)required

consignee.namestring or null<= 35 charactersrequired

Name of the consignee. This can be a company name or full name of the recipient.

Example: "John Doe"

consignee.firstNamestring<= 35 charactersrequired

First name of the recipient.

Example: "John"

consignee.lastNamestring<= 35 charactersrequired

Last name of the recipient.

Example: "Doe"

consignee.emailstring(email)required

Email of the recipient.

Example: "john.doe@gmail.com"

consignee.phoneNumberstringrequired

Phone number of the recipient in international format (starting with +).

Example: "+421907654123"

parcelCountinteger(int32)required

Number of parcels in the shipment.

expectedWeightnumber(double)required

Total weight in kilograms of the shipment (sum of parcel weights).

deliveryNotestring or null<= 35 characters

Delivery note.

Example: "Please, leave it behind the door."

clientReferencestring<= 35 charactersrequired

The identifier that links the package in the Poiint system with the order in the client's e-shop.

Example: "A-1234567"

enrichmentsobject(Dtos.Enrichments)

deliveryAddressobject(Dtos.Address)

parcelShopobject(Dtos.ParcelShop)

curl -i -X POST \
  https://docs.business.poiint.sk/_mock/openapi/integration/v1/orders \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Sender-Profile: string' \
  -d '{
    "carrierPid": 0,
    "consignee": {
      "name": "John Doe",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@gmail.com",
      "phoneNumber": "+421907654123"
    },
    "parcelCount": 0,
    "expectedWeight": 0.1,
    "deliveryNote": "Please, leave it behind the door.",
    "clientReference": "A-1234567",
    "enrichments": {
      "cod": {
        "amount": 4.99,
        "currency": "EUR"
      },
      "parcelValue": {
        "amount": 4.99,
        "currency": "EUR"
      },
      "icc": true
    },
    "deliveryAddress": {
      "country": "SK",
      "zipCode": "90901",
      "city": "Skalica",
      "street": "Mallého",
      "houseNumber": "22"
    },
    "parcelShop": {
      "id": "string",
      "address": {
        "country": "SK",
        "zipCode": "90901",
        "city": "Skalica",
        "street": "Mallého",
        "houseNumber": "22"
      }
    }
  }'

Responses

Order created successfully.

Bodyapplication/json

idstring(uuid)required

Identifier of the order in Poiint Business database. This identifier can be used to submit existing order.

Example: "5f7d212d-de28-42fa-aa40-2eb0883cc4ce"

poiintIdstringrequired

Identifier of the order printed on the packet labels. This identifier can be used to track the status of the order via our official website. It has a fixed format (P + 13 digits).

Example: "P0123456789999"

Response

application/json

{
  "id": "5f7d212d-de28-42fa-aa40-2eb0883cc4ce",
  "poiintId": "P0123456789999"
}

Submit order

Request

Used to submit existing order identified by id in the route parameter. Order submission means that the order is sent to the system of a carrier specified on the order. After this step, the order can no longer be modified. Order cannot be submitted more than once. For orders with a carrier that has configured an irregular pickup type, it is necessary to specify the pickup date in a request body.

Security

Bearer

Path

idstring(uuid)required

Headers

X-Sender-Profilestringrequired

Bodyapplication/jsonrequired

pickupDatestring or nullrequired

Pickup date in format YYYY-MM-DD (the date when the courier will come for the parcel). Required only for orders with irregular pickup schedules.

Example: "2026-08-20"

curl -i -X POST \
  'https://docs.business.poiint.sk/_mock/openapi/integration/v1/orders/{id}/submit' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Sender-Profile: string' \
  -d '{
    "pickupDate": "2026-08-20"
  }'

Responses

Bodyapplication/json

Response

application/json

null

Print labels

Request

Used to print labels for given orders. Labels can be printed only for submitted orders with regular pickup. A maximum of 100 labels can be printed at a time.

Security

Bearer

Query

idArray of strings(uuid)required

Orders for which you want to print labels.

formatstring

Optional label format ("A6onA4" or "A6onA6").

starting-positioninteger(int32)

Optional starting position of the first label. Allowed values: 0 - 3.

Headers

X-Sender-Profilestringrequired

curl -i -X GET \
  'https://docs.business.poiint.sk/_mock/openapi/integration/v1/orders/labels?id=497f6eca-6276-4993-bfeb-53cbbbba6f08&format=string&starting-position=0' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'X-Sender-Profile: string'

Responses

Printing successful.

Bodyapplication/pdf

Refresh

Request

Used to obtain the access token and current configuration. Access token is required for authorization of requests for order creation and submission. The configuration provides information about delivery options of the carriers (which carriers can be used for delivery in given country). The configuration also includes information about enrichments and validation rules for the given carrier.

Security

ApiKey

Headers

X-Api-Keystringrequired

X-Sender-Profilestringrequired

curl -i -X POST \
  https://docs.business.poiint.sk/_mock/openapi/integration/v1/refresh \
  -H 'X-Api-Key: YOUR_API_KEY_HERE' \
  -H 'X-Sender-Profile: string'

Responses

Operation successful.

Bodyapplication/json

accessTokenstringrequired

JSON Web Token required for authorization of requests for order creation and submission.

apiKeysobject(RefreshEndpoint.Response.MapComponentApiKeys)required

apiKeys.dpdstringrequired

API key required for DPD map widget to work.

apiKeys.packetastringrequired

API key required for PACKETA map widget to work.

routesArray of objects(RefreshEndpoint.Response.Route)required

An array of objects, where each object contains carriers and their configuration for a single route.

routes[].countryFromstringrequired

Sender country (start of the route).

Example: "SK"

routes[].countryTostringrequired

Consignee country (end of the route).

Example: "NL"

routes[].carriersobject(RefreshEndpoint.Response.CarriersConfiguration)required

routes[].carriers.homeDeliveryArray of objects(RefreshEndpoint.Response.Carrier)required

Carriers that support home delivery on given route.

routes[].carriers.homeDelivery[].publicIdinteger(int32)required

Public identifier of the carrier. Use this value to identify the carrier in order creation process.

routes[].carriers.homeDelivery[].namestringrequired

The name of the carrier that will deliver the shipment.

Example: "DHL"

routes[].carriers.homeDelivery[].logostringrequired

URI on which logo of this carrier can be downloaded.

routes[].carriers.homeDelivery[].cooperatingCarrierNamestring or null

Name of the carrier that will pick up the shipment.

Example: "Packeta"

routes[].carriers.homeDelivery[].cooperatingCarrierLogostring or null

URI on which logo of a cooperating carrier can be downloaded.

routes[].carriers.homeDelivery[].pickupTypestringrequired

Pickup type configured for the carrier. Possible values: R (regular), I (irregular), D (drop-off)

Example: "R"

routes[].carriers.homeDelivery[].enrichmentsobject(RefreshEndpoint.Response.Enrichments)required

routes[].carriers.homeDelivery[].enrichments.maxCodobject(Dtos.Money)required

routes[].carriers.homeDelivery[].enrichments.maxParcelValueobject(Dtos.Money)required

routes[].carriers.homeDelivery[].enrichments.iccbooleanrequired

True, if ID card check is supported by the carrier on given route.

routes[].carriers.homeDelivery[].validationsobject(RefreshEndpoint.Response.Validations)required

routes[].carriers.homeDelivery[].validations.consigneePhoneNumberFormatbooleanrequired

True, if recipient's phone number format must be valid for the country. For example, if recipient's country is SK and this value is true, then recipient's phone number must start with +421 (phone number prefix for SK).

routes[].carriers.parcelShopDeliveryArray of objects(RefreshEndpoint.Response.Carrier)required

Carriers that support parcel shop delivery on given route.

routes[].carriers.parcelShopDelivery[].publicIdinteger(int32)required

Public identifier of the carrier. Use this value to identify the carrier in order creation process.

routes[].carriers.parcelShopDelivery[].namestringrequired

The name of the carrier that will deliver the shipment.

Example: "DHL"

routes[].carriers.parcelShopDelivery[].logostringrequired

URI on which logo of this carrier can be downloaded.

routes[].carriers.parcelShopDelivery[].cooperatingCarrierNamestring or null

Name of the carrier that will pick up the shipment.

Example: "Packeta"

routes[].carriers.parcelShopDelivery[].cooperatingCarrierLogostring or null

URI on which logo of a cooperating carrier can be downloaded.

routes[].carriers.parcelShopDelivery[].pickupTypestringrequired

Pickup type configured for the carrier. Possible values: R (regular), I (irregular), D (drop-off)

Example: "R"

routes[].carriers.parcelShopDelivery[].enrichmentsobject(RefreshEndpoint.Response.Enrichments)required

routes[].carriers.parcelShopDelivery[].enrichments.maxCodobject(Dtos.Money)required

routes[].carriers.parcelShopDelivery[].enrichments.maxParcelValueobject(Dtos.Money)required

routes[].carriers.parcelShopDelivery[].enrichments.iccbooleanrequired

True, if ID card check is supported by the carrier on given route.

routes[].carriers.parcelShopDelivery[].validationsobject(RefreshEndpoint.Response.Validations)required

routes[].carriers.parcelShopDelivery[].validations.consigneePhoneNumberFormatbooleanrequired

Response

application/json

{
  "accessToken": "string",
  "apiKeys": {
    "dpd": "string",
    "packeta": "string"
  },
  "routes": [
    { … }
  ]
}

Get unavailable pickup dates

Request

The function returns the days on which it is not possible to pick up the order by the carrier. Only 30 days from current date are taken into account. It is supposed to be used in combination with date picker component to ensure selection of a valid pickup date by the client. Note that, pickup date selection makes sense only for carriers that support irregular pickup type.

Security

Bearer

Query

carrier-pidinteger(int32)required

Headers

X-Sender-Profilestringrequired

curl -i -X GET \
  'https://docs.business.poiint.sk/_mock/openapi/integration/v1/unavailable-pickup-dates?carrier-pid=0' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'X-Sender-Profile: string'

Responses

Bodyapplication/json

datesArray of stringsrequired

Array of dates in format MM/DD/YYYY.

Response

application/json

{
  "dates": [
    "string"
  ]
}

Poiint Business API (0.0.1)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Introduction

Testing and Development

Web application

Contacts

Glossary

Carriers

Security

Access Tokens

API keys

FAQ

Validations errors

Integration
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Create order

Request

Responses

Was this helpful?

Submit order

Request

Responses

Was this helpful?

Print labels

Request

Responses

Was this helpful?

Refresh

Request

Responses

Was this helpful?

Get unavailable pickup dates

Request

Responses

Was this helpful?

Poiint Business API (0.0.1)CopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from Claude

Introduction

Testing and Development

Web application

Contacts

Glossary

Carriers

Security

Access Tokens

API keys

FAQ

Validations errors

IntegrationCopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from Claude

Create order

RequestExpand all

Responses

Was this helpful?

Submit order

Request

Responses

Was this helpful?

Print labels

Request

Responses

Was this helpful?

Refresh

Request

Responses

Was this helpful?

Get unavailable pickup dates

Request

Responses

Was this helpful?

Poiint Business API (0.0.1)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Integration
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Request