Poiint Business API (0.0.1)

Copy

• 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:

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:

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.

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.

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.