OXNet REST API (3.0.3)

Download OpenAPI specification:Download

Welcome to the OXNet developer docs. You'll find comprehensive guides and documentation to help you start working with OXNet as quickly as possible, as well as support if you get stuck. Let's jump right in!

How to start

The only option for integration into the system is after business negotiations and agreement on the parameters of the contract. You can contact our business via e-mail jakub.schwarz@oxpoint.cz. Then, you will be redirected to the communication with the technical team, which will set up the necessary data in the system according to the agreed contract and provide you with access. Development and testing take place compared to the staging environment, to which the technical team of the OX Point will send you access.

Dictionary

parcel = package; in some cases, you may encounter parcel and package terms that are interchangeable in our system. The preferred variant is the unification of terminology on parcels.

Security

Most of the endpoints are secured by access token mechanism. Access token can be obtained via Authentication API. Credentials for authentication API are distributed individually according to discussion with technical team. Access token is authentication with limited time to live. Information about expiration period is returned in authentication endpoint response. After expiration access token is no longer valid and new access token needs to be requested.

Etag

Some API endpoints are protected with ETag validation against concurrent calls. Selected modification endpoints require HTTP Header “If-Match”. The value needs to exactly equal to latest version of ETag of related entity. ETag is value can be obtained via HTTP header by both read and write operations. Write operation returns ETag value of entity after successful applying the requested modifications. ETag value after successful modification can then be used for next modification call. In order to get latest possible ETag value read operation can be used and ETag value of latest version of entity is returned together with the entity content.

Callbacks

Callback is a notification from OXNet system to defined HTTP endpoint. Notifications are triggered on different type of events or are scheduled. Check specific notification type below to get more details about behavior. Each notification is sent via HTTPS as POST, it also contains a time stamp and a shared key signature. Timeout for individual call is 5 seconds. Retry mechanism is applied and takes at minimum 1 hours. Undelivered notifications are kept for several days in Dead Letter Queue for manual resending in case of solving technical issues with technical team. Callbacks are protected by API key signatures. Callbacks are also called webhooks in OXnet system. See webhook API definition.

Point / box visibility

According to contract type of registered party some endpoint restricts the view on reservation capacity entities (point and boxes) in OXNet system. Selected endpoints contains "allowForeign" or "boxVisibility" parameter to influence the view. Some contract types restrict the usage, the other can take advantage to use it in order to to prefer certain type of points and boxes.

Workflow

Parcel status

  • ACCEPTED (parcel successfully created via REST API)
  • STORING (parcel is in the process of storing into box by courier)
  • STORED (parcel successfully stored by courier)
  • COMPLETED (parcel successfully picked up by the recipient)
  • DISPLACED (parcel picked up by the courier instead of recipient)
  • CANCELLED (parcel cancelled from state ACCEPTED by external party via REST API or internally after long-time expired reservations)

OX Point kiosk GUI features

  • Storing successfully created parcel by QR code or after courier login
  • Courier can change the storage box if it is not suitable for parcel storing
  • Courier can add more boxes for storing parcel items, usually in case of having multiple items which cannot all fit to reserved boxes
  • Picking up stored parcel by recipient via PIN code
  • Picking up expired parcels by courier of carrier entity

Authentication

basicAuth

Basic authentication is used for Authentication API endpoint. It is sent in HTTP header "Authorization" with value "Basic <base64(username:password)>". Username and password is documented in specific endpoint from Authentication API.

Security Scheme Type HTTP
HTTP Authorization Scheme basic

bearerAuth

Bearer type authentication is sent in HTTP header "Authorization" with value "Bearer <access_token>". Access token can be obtained via Authentication API. Most of API is secured with access token expected as Bearer authentication. Access token has limited life-time. After expiration access token needs to be requested again via Authentication API endpoint.

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

Authentication API

Get access token for vendor project API client

Get access token which is restricted to vendor project. Username and password in request body is sensitive information specific for each vendor project.

Besides username and password in request body the endpoint is secured also with Basic authentication which uses hard-coded username "vendorapi" and password "" (empty password) which when base64-encoded is sent as HTTP header "Authorization" with value "Basic dmVuZG9yYXBpOg==".

Access token is of type JWT and has limited life-time. Expiration time is encoded in absolute time inside JWT body and relative expiration time is also returned in response body. After expiration all endpoints secured by it will return 401. New access token can be obtained by another call.

Authorizations:
Request Body schema: application/x-www-form-urlencoded

Vendor project API client credentials

grant_type
string

Only "password" grant type is supported.

username
string

API client username

password
string

API client password

Responses

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "expires_in": 0,
  • "token_type": "string"
}

Service Health

Health check

Returns a service status

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "stable": true,
  • "versionInfo": "string"
}

Points

Retrieve point list (deprecated) Deprecated

Get list of points

Authorizations:
query Parameters
allowForeign
boolean
Default: false

If true show all available boxes at points. If false show just exclusive boxes at points.

search
string

Provides full text search on items.

lngMin
number <double>

Minimal point location longitude

lngMax
number <double>

Maximal point location longitude

latMin
number <double>

Minimal point location latitude

latMax
number <double>

Maximal point location latitude

status
Array of strings (PointStatusEnum)
Deprecated
Items Enum: "in_construction" "active" "maintenance"

Filter by status

paymentTerminal
Array of strings (PaymentTerminalStatusEnum)
Items Enum: "none" "active" "in_construction"

Filter by payment terminal status

pageSize
integer [ 1 .. 1000 ]
Default: 20

Number of items in a page, default page size is 20, maximum 1000

pageNumber
integer >= 0
Default: 0

Page number, default is 0

sort
string

Sort criteria, format: '?sort=<propertyA>[,<propertyB>][,(asc|desc)]',

sort parameter can be used several times in one query

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "paging": {
    }
}

Retrieve point list

Get list of points

Authorizations:
query Parameters
allowForeign
boolean
Default: false

If true show all available boxes at points. If false show just exclusive boxes at points.

search
string

Provides full text search on items.

lngMin
number <double>

Minimal point location longitude

lngMax
number <double>

Maximal point location longitude

latMin
number <double>

Minimal point location latitude

latMax
number <double>

Maximal point location latitude

status
Array of strings (PointStatusEnum)
Items Enum: "in_construction" "active" "maintenance"

Filter by status

paymentTerminal
Array of strings (PaymentTerminalStatusEnum)
Items Enum: "none" "active" "in_construction"

Filter by payment terminal status

pageSize
integer [ 1 .. 1000 ]
Default: 20

Number of items in a page, default page size is 20, maximum 1000

pageNumber
integer >= 0
Default: 0

Page number, default is 0

sort
string

Sort criteria, format: '?sort=<propertyA>[,<propertyB>][,(asc|desc)]',

sort parameter can be used several times in one query

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "paging": {
    }
}

Retrieve point

Get point detailed information

Authorizations:
path Parameters
pointId
required
string <uuid>

Point ID

query Parameters
allowForeign
boolean
Default: false

If true show all available boxes at points. If false show just exclusive boxes at points.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "businessId": "string",
  • "summary": "string",
  • "geolocation": {
    },
  • "address": {
    },
  • "detailedDescription": "string",
  • "openingHoursSpecification": "string",
  • "openingHours": {
    },
  • "serialNumber": "string",
  • "status": "in_construction",
  • "paymentTerminal": "none",
  • "images": [
    ],
  • "boxQuantities": [
    ],
  • "createdDate": "2019-08-24T14:15:22Z",
  • "lastModifiedDate": "2019-08-24T14:15:22Z",
  • "outageReason": "string",
  • "timeZone": "string"
}

Retrieve point outage list

Get list of point outages

Authorizations:
query Parameters
allowForeign
required
boolean

If true show outages of all available points. If false just show outages of exclusive points.

search
string

Provides full text search on items.

pointId
string <uuid>

Filter by point ID

pageSize
integer [ 1 .. 1000 ]
Default: 20

Number of items in a page, default page size is 20, maximum 1000

pageNumber
integer >= 0
Default: 0

Page number, default is 0

sort
string

Sort criteria, format: '?sort=<propertyA>[,<propertyB>][,(asc|desc)]',

sort parameter can be used several times in one query

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "paging": {
    }
}

Availability Slots

Retrieve availability slots

Get a list of selected time windows with availability information, maximum time span (from to until) is one year

Authorizations:
query Parameters
allowForeign
boolean
Default: false

If true try to place parcel into all available boxes with preferrence to reserved boxes. If false only reserved boxes are considered.

Request Body schema: application/json
from
required
string <date-time>

Filter slots available from this time onward

until
required
string <date-time>

Filter slots available up to this time

slotSize
number [ 0.5 .. 72 ]
Default: 1.5

Length of each slot in hours

pointId
required
string <uuid>

ID of point to search in

required
object

How many boxes of which sizes are needed

Responses

Request samples

Content type
application/json
{
  • "from": "2019-08-24T14:15:22Z",
  • "until": "2019-08-24T14:15:22Z",
  • "slotSize": 1.5,
  • "pointId": "20a7be04-0667-469f-8fa4-da6cf02369c8",
  • "requestedBoxes": {
    }
}

Response samples

Content type
application/json
[
  • {
    }
]