# Poiint Business API

## 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](https://datatracker.ietf.org/doc/html/rfc7807) object. Below is an example from _CreateOrder_ operation.

```json
{
    "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).             |


Version: 0.0.1

## Servers

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

## Security

### Bearer

Access token in HTTP request header.

Type: http
Scheme: bearer
Bearer Format: JWT

### ApiKey

API key in HTTP request header.

Type: apiKey
In: header
Name: X-Api-Key

## Download OpenAPI description

[Poiint Business API](https://docs.business.poiint.sk/_bundle/openapi.yaml)

## Integration

### Create order

 - [POST /integration/v1/orders](https://docs.business.poiint.sk/openapi/integration/createorder.md): 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_.

### Submit order

 - [POST /integration/v1/orders/{id}/submit](https://docs.business.poiint.sk/openapi/integration/submitorder.md): 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.

### Print labels

 - [GET /integration/v1/orders/labels](https://docs.business.poiint.sk/openapi/integration/printlabels.md): 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.

### Refresh

 - [POST /integration/v1/refresh](https://docs.business.poiint.sk/openapi/integration/refresh.md): 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.

### Get unavailable pickup dates

 - [GET /integration/v1/unavailable-pickup-dates](https://docs.business.poiint.sk/openapi/integration/getunavailablepickupdates.md): 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.