OXNet REST API (latest)

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

Points

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 products.

Searches in following parameters:

  • detailedDescription
lngMin
number <double>
lngMax
number <double>
latMin
number <double>
latMax
number <double>
status
Array of strings (PointStatusEnum)
Deprecated
Items Enum: "in_construction" "active" "maintenance" "deleted"

Filter by status, not supported values

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",
  • "summary": "string",
  • "geolocation": {
    },
  • "address": {
    },
  • "detailedDescription": "string",
  • "openingHours": "string",
  • "serialNumber": "string",
  • "status": "in_construction",
  • "images": [
    ],
  • "boxQuantities": [
    ],
  • "createdDate": "2019-08-24T14:15:22Z",
  • "lastModifiedDate": "2019-08-24T14:15:22Z"
}

Availability Slots

Retrieve Availability Slots

Authorizations:
query Parameters
allowForeign
boolean
Default: false

If true try to place package 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>
until
required
string <date-time>
slotSize
number [ 0.5 .. 72 ]
Default: 1.5
pointId
required
string <uuid>
required
object

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
[
  • {
    }
]

Compute Free Box Capacity

Authorizations:
path Parameters
pointId
required
string <uuid>

Point Id

Request Body schema: application/json
from
required
string <date-time>
until
required
string <date-time>
boxVisibility
required
string (BoxVisibilityEnum)
Enum: "OWN_ONLY" "OWN_OR_SHARED"

Status:

  • OWN_ONLY - Check only my reserved boxes
  • OWN_OR_SHARED - Search in all my and all shared boxes

Responses

Request samples

Content type
application/json
{
  • "from": "2019-08-24T14:15:22Z",
  • "until": "2019-08-24T14:15:22Z",
  • "boxVisibility": "OWN_ONLY"
}

Response samples

Content type
application/json
{
  • "boxes": [
    ]
}

Packages

Retrieve package

Authorizations:
path Parameters
packageId
required
string <uuid>

Package Id

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "pointId": "20a7be04-0667-469f-8fa4-da6cf02369c8",
  • "packageNumber": "string",
  • "carrierIdentifier": "string",
  • "payment": {
    },
  • "customer": {
    },
  • "itemBatches": [
    ],
  • "status": "accepted",
  • "cancellationReason": "string",
  • "reservedFromDate": "2019-08-24T14:15:22Z",
  • "reservedUntilDate": "2019-08-24T14:15:22Z"
}

Update a package

Authorizations:
path Parameters
packageId
required
string <uuid>

Package Id

query Parameters
allowForeign
boolean
Default: false

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

header Parameters
If-Match
required
string

ETag header value from getPackage detail call

Request Body schema: application/json

Updating an existing package

pointId
required
string <uuid>
packageNumber
required
string
carrierIdentifier
required
string
object or null (PaymentDetailsBody)

Defines Payment Details

required
object (CustomerDetails)

Defines a Customer Details

required
Array of objects (ItemBatchBody) non-empty [ items ]
reservedFromDate
required
string <date-time>

Reserved From Date

reservedUntilDate
required
string <date-time>

Reserved To Date

Responses

Request samples

Content type
application/json
{
  • "pointId": "20a7be04-0667-469f-8fa4-da6cf02369c8",
  • "packageNumber": "string",
  • "carrierIdentifier": "string",
  • "payment": {
    },
  • "customer": {
    },
  • "itemBatches": [
    ],
  • "reservedFromDate": "2019-08-24T14:15:22Z",
  • "reservedUntilDate": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "pointId": "20a7be04-0667-469f-8fa4-da6cf02369c8",
  • "packageNumber": "string",
  • "carrierIdentifier": "string",
  • "payment": {
    },
  • "customer": {
    },
  • "itemBatches": [
    ],
  • "status": "accepted",
  • "cancellationReason": "string",
  • "reservedFromDate": "2019-08-24T14:15:22Z",
  • "reservedUntilDate": "2019-08-24T14:15:22Z"
}

Retrieve Package List

Authorizations:
query Parameters
search
string

Provides full text search on products.

Searches in following parameters:

  • customer.email
  • customer.name
status
Array of strings (PackageStatusEnum)
Items Enum: "accepted" "stored" "completed" "displaced" "cancelled" "deleted"

Filter by status, can be comma-separated list to include multiple values

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