Kvikk API

Base URL

All API URLs referenced in this documentation start with the following base part:

https://api.kvikk.hu/v1

Authentication

To authenticate with the APIs, specify the “X-API-KEY” header with each request. The value of the header must be a valid API key. Example:

X-API-KEY: eyJraWQiOiI0...

Date Format

The api returns JSON for all API calls. Every returned date is using the ISO 8601, for example:

2024-08-01 10:18:42.697Z

API Conventions

The Kvikk API is built on HTTP. Our API is RESTful:

/something is equivalent to /something/.
URL paths, URL query parameter names, and JSON field names are case sensitive.
The HTTP status indicates whether an operation failed or succeeded, with extra information included in the HTTP response body.
All APIs return standard error code formats.
Unexpected query parameters are NOT ignored.
Unexpected JSON fields in the request body are NOT ignored.
Uses built-in HTTP capabilities for passing parameters and authentication.
Always returns JSON.

Every response looks like this:

{
  "status": "success",
  "code": "shipment_created",
  "message": "Shipment successfully created",
  "data": Object...
}

Errors

Kvikk returns standard HTTP response codes.

Code	Description
200	Everything worked as expected
201	The requested resource is created
204	The requested resource is deleted
400	Bad Request - Often missing a required parameter
401	Unauthorized - No valid API key provided
403	Request Failed - Parameters were valid but request failed
404	Not Found - The requested item doesn’t exist
409	Duplicate - The requested resource already exists
500, 502, 503, 504	Server Errors - something is wrong on the server end

Shipments ¶

API endpoints related to shipment management.

Create shipment ¶

Create shipment
POST`/shipment/`

Create a new shipment. When you create the shipment, in response you will receive a 2 trakcing numbers(one generated by Kvikk, you can use this to later manage the shipment) and one that was generated by the courier. You can use the same endpoint to generate home delivery and delivery point shipments. In response, you will get the generated PDF shipping label as a base64 pdf to store it.

The generated tracking number follows this format: M{12 digits}. The first letter identifies the courier: M=MPL, P=Packeta, E=Express One, F=FámaFutár.

Body parameters

Name	Type	Required	Description
name	string	Yes	Customer’s name
phone	string or number	Yes	Customer’s phone number. Will be validated and transformed automatically to +36 format
email	string	Yes	Customer’s email address
courier	string	Yes	Courier’s ID. Available values: mpl, expressone, packeta, famafutar
deliveryPointType	string	Yes for delivery point	Type of the delivery point. Set in case the shipment is delivered to a delivery point location instead of home delivery. Available values: mpl_posta, mpl_postapont, mpl_automata, packeta_zbox, packeta_zpont, expressone_omv, expressone_alzabox
deliveryPointID	string	Yes for delivery point	Delivery point ID. Set in case the shipment is delivered to a delivery point location instead of home delivery.
address	string	Yes for home delivery	Shipping address
city	string	Yes for home delivery	City of the shipping address
postcode	number	Yes for home delivery	Postal code (1000-9999)
country	string	Yes for home delivery	Country code (HU)
note	string	No	Additional notes(visible on the label)
orderID	string or number	Yes	Order ID
weight	number	Yes	Package weight in gramms
cod	number	Yes	Cash on delivery amount in HUF(use 0 if theres no COD on the shipment)
value	number	Yes	Package value in HUF
senderID	string	Yes	Sender’s ID

Possible error codes

Code	Description
invalid_delivery_point_type	The selected delivery point type does not exists
invalid_delivery_point_id	The delivery point id does not exists, doesn’t belong to the selected type or unavailable(closed, deleted, damaged)
wrong_weight_value	The courier won’t ship a shipment with this weight
wrong_cod_value	The courier can’t handle the COD value
missing_weight	Valid weight is required
label_not_generated	Unable to generate label due to an issue with the Courier’s API
sender_not_found	The sender ID does not belong to the user or doesn’t exists
courier_not_found	Wrong courier ID
courier_not_active	The selected courier is not activated in the user’s account

Example URI

POST https://api.kvikk.hu/v1/shipment/

Request home delivery

HideShow

Headers

Content-Type: application/json

Body

{
  "name": "John Doe",
  "phone": "06301234567",
  "email": "sample@test.com",
  "courier": "mpl",
  "address": "Sample Street 1.",
  "city": "City",
  "postcode": 2021,
  "country": "HU",
  "note": "",
  "orderID": "K-1234",
  "weight": 1450,
  "cod": 0,
  "value": 14500,
  "senderID": "6679566f3826e1e46f645789"
}

Request shipping to delivery point

HideShow

Headers

Content-Type: application/json

Body

{
  "name": "John Doe",
  "phone": "06301234567",
  "email": "sample@test.com",
  "courier": "packeta",
  "deliveryPointType": "zbox",
  "deliveryPointID": "25090",
  "note": "",
  "orderID": "K-1234",
  "weight": 1450,
  "cod": 0,
  "value": 14500,
  "senderID": "6679566f3826e1e46f645789"
}

Response 201

HideShow

Headers

Content-Type: application/json

Body

{
    "status": "success",
    "code": "shipment_added",
    "message": "Shipment successfully generated",
    "data": {
        "trackingNumber": "M123412341234", //The tracking number generated by Kvikk
        "label": "...", //PDF label in base64
        "labelDownloadLink": "https://assets.kvikk.hu/...pdf" //Available for 15 minutes
        "accounting": {
            "courierTrackingNumber": "4124124124124", //The tracking number generated by the courier
            "weight": 1450,
            "shipping": 1120, //Caluclated base shipping cost(net)
            "codFee": 0, //Caluclated fixed COD fee(net)
            "codPercentage": 0, //Percentage fee for COD
            "link": "https://app.kvikk.hu/..." //Link to app.kvikk.hu for managing the shipment
        }
    }
}

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "status": "fail",
  "code": "wrong_weight_value",
  "message": "Unable to create shipment with given weight."
}

Get shipment ¶

Get shipment
GET`/shipment/{trackingNumber}/`

Get all the details from a single shipment, including up-to-date tracking information.

The tracking events are grouped into these categories to provide a unified tracking experience across couriers:

Event ID	Description
booked	Shipment label generated, but not dispatched yet
sent	Shipment was picked up by the courier, or it was dropped off for dispatch
in_transit	The shipment is traveling betwwen locations
out_for_delivery	Shipment is out for delivery for home delivery
ready_for_pickup	Shipment was placed at the delivery point for pickup
delivered	Shipment was successfully delivered at home or customer collected from delivery point
failed	Unable to deliver, might try again later
returned	Returned to the sender

Example URI

GET https://api.kvikk.hu/v1/shipment/M123412341234/

URI Parameters

HideShow

trackingNumber: string (required) Example: M123412341234
Shipment’s tracking number

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    "status": "success",
    "code": "shipment_found",
    "message": "Shipment data successfully returned.",
    "data": {
        "tracking": {
            "shipped": true,
            "delivered": true,
            "returned": false,
            "updated": "2024-07-12T09:02:47.992Z",
            "events": [
                {
                    "event": "delivered",
                    "message": "Sikeresen kézbesítve háznál",
                    "location": "Sellye posta, Sellye",
                    "date": "2024-07-11T06:53:48.000Z",
                },
                {
                    "event": "out_for_delivery",
                    "message": "A küldemény a kézbesítőnél van",
                    "location": "Sellye posta, Sellye",
                    "date": "2024-07-11T06:53:48.000Z",
                }
            ]
        },
        "dispatchAddress": {
            "address": "Szabadság u 76.",
            "city": "Kisnána",
            "postcode": "3264",
            "name": "Noblehunt",
            "phone": "+36307383761",
            "email": "info@noblehunt.hu",
            "country": "HU",
        },
        "name": "Test Customer",
        "phone": "+36301234567",
        "email": "sample@email.com",
        "courier": "mpl",
        "orderID": "5027",
        "weight": 1000,
        "cod": 14360,
        "value": 14360,
        "note": "",
        "trackingNumber": "M206021574489",
        "courierTrackingNumber": "PBUUE50001038",
        "created": "2024-07-10T09:02:37.477Z",
        "shippingAddress": {
            "address": "Petőfi S. u. 56.",
            "city": "Budapest",
            "postcode": "1025",
            "country": "HU",
        },
        "courierTrackingLink": "https://www.posta.hu/nyomkovetes/nyitooldal?searchvalue=PBUUE50001037",
        "trackingLink": "https://tracking.kvikk.hu/#/M206021574488",
        "labelDownloadLink": "https://assets.kvikk.hu/download/?file=2024%2F07%2Fca72eba53b30220d.pdf&token=de936f4811ecfb7d59850a78171ae10c%3A5fcac7e356ebdc9bbb16b61072f21dd473a87389083b0605ff5e6ad5d3df0fc38791e1c90891e1a443ed5bb057761404",
        "appLink": "https://app.kvikk.hu/shipments/668e4e2d9fc3c2e7903104d7",
    }
}

Delete shipment ¶

Delete shipment
DELETE`/shipment/{trackingNumber}/`

Delete a specific shipment by its tracking number. You can only delete it, if it was not shipped yet. If it’s already on a delivery note, you won’t be able to delete it.

Example URI

DELETE https://api.kvikk.hu/v1/shipment/M123412341234/

URI Parameters

HideShow

trackingNumber: string (required) Example: M123412341234
Shipment’s tracking number

Response 200

HideShow

Body

{
  "status": "success",
  "code": "shipment_deleted",
  "message": "Shipment successfully deleted."
}

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "status": "fail",
  "code": "shipment_dispatched",
  "message": "Shipment already dispatched."
}

Get shipment label ¶

Get shipment label
GET`/shipment/{trackingNumber}/label`

Get the shipping label for a specific shipment.

Example URI

GET https://api.kvikk.hu/v1/shipment/M123412341234/label

URI Parameters

HideShow

trackingNumber: string (required) Example: M123412341234
Shipment’s tracking number

Response 200

HideShow

Headers

Content-Type: application/pdf
Content-Disposition: attachment; filename="M123412341234_label.pdf"

Body

[Binary PDF content of the shipping label]

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "status": "fail",
  "code": "shipment_not_found",
  "message": "Shipment not found."
}

Utils ¶

Utility endpoints for additional functionalities.

Delivery Points ¶

Delivery Points
GET`/delivery-points/`

Retrieve a list of delivery points based on courier and type. The ID parameter is the same as in the courier’s own database, so if you have your own list of delivery points with valid IDs, you can use that to generate shipments on Kvikk.

Example URI

GET https://api.kvikk.hu/v1/delivery-points/

URI Parameters

HideShow

courier: string (required) Example: mpl
Filter by courier name.
type: string (required) Example: mpl_postapont
Filter by type of delivery point. Allowed to be empty, in that case it will return all points from the courier.

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    "status": "success",
    "code": "delivery_points_returned",
    "message": "Delivery points data returned.",
    "data": [
        {
        "id": "690",
        "lat": "48.07785",
        "lon": "19.29279",
        "name": "Nemesvári Papír",
        "zip": "2660",
        "addr": "Teleki László utca 1",
        "city": "Balassagyarmat",
        "country": "HU",
        "type": "packeta_zpont",
        "courier": "packeta",
        "hours": {
            "1": "09:00–17:00",
            "2": "09:00–17:00",
            "3": "09:00–17:00",
            "4": "09:00–17:00",
            "5": "09:00–17:00",
            "6": "09:00–12:00",
            "7": ""
        },
        "imported": "2024-07-14T06:36:44.227Z",
        }
    ]
}

Account Information ¶

Account Information
GET`/account-details/`

Retrieve information about the user’s account: sender address, available couriers to use for creating shipments, actual price list for the user to be used to calculate estimated shipping costs before the shipment is actually created. You can get a list of available senders and you need to pass the _id parameter’s value when you create a shipment. You can only create a shipment if the courier is in the couriers array with active status. In the pricing parameter, you can find the shipping and COD fees grouped by couriers. Inside each courier, you can get the net cost and fee based on the min/max range. Range is gramms in case of shipping cost, and HUF in case of COD pricing.

Example URI

GET https://api.kvikk.hu/v1/account-details/

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
"status": "success",
"code": "couriers_retrieved",
"message": "Couriers successfully retrieved",
"data": {
    "couriers": [
        {
            "slug": "mpl",
            "name": "MPL",
            "status": "active",
            "note": "MPL-es csomagot feladhatsz bármelyik postán, vagy kérhetsz háznál történő felvételt.",
            "pickupLimit": 1,
            "deliveryPointTypes": [
                {
                    "slug": "mpl_posta",
                    "name": "Posta",
                    "db": "https://points-api.kvikk.hu/points?&search=mpl_posta"
                },
                {
                    "slug": "mpl_postapont",
                    "name": "Postapont",
                    "db": "https://points-api.kvikk.hu/points?&search=mpl_postapont"
                },
                {
                    "slug": "mpl_automata",
                    "name": "Automata",
                    "db": "https://points-api.kvikk.hu/points?&search=mpl_automata"
                }
            ]
        },
        {
            "slug": "packeta",
            "name": "Packeta",
            "status": "active",
            "note": "Packeta csomagokat Packeta Z-Pont átvevőhelyeken tudsz feladni.",
            "pickupLimit": 1,
            "deliveryPointTypes": [
                {
                    "slug": "packeta_zpont",
                    "name": "Z-Pont",
                    "db": "https://assets.kvikk.hu/getDeliveryPoints/packeta_zpont"
                },
                {
                    "slug": "packeta_zbox",
                    "name": "Z-Box",
                    "db": "https://assets.kvikk.hu/getDeliveryPoints/packeta_zbox"
                }
            ]
        },
        {
            "slug": "expressone",
            "name": "Express One",
            "status": "pending",
            "note": "Express One csomagfelvételt minimum 3 csomagtól tudsz kérni.",
            "pickupLimit": 3,
            "deliveryPointTypes": [
                {
                    "slug": "expressone_omv",
                    "name": "OMV",
                    "db": "https://assets.kvikk.hu/getDeliveryPoints/expressone_omv"
                },
                {
                    "slug": "expressone_alzabox",
                    "name": "AlzaBox",
                    "db": "https://assets.kvikk.hu/getDeliveryPoints/expressone_alzabox"
                }
            ]
        },
    ],
    "senders": [
        {
            "address": "Test u. 1.",
            "city": "Balatonalmádi",
            "postcode": "8220",
            "name": "Test User",
            "phone": "+36301234567",
            "email": "test@kvik.hu",
            "country": "HU",
            "_id": "668c5f8c2d6d7579f2233b4f"
        }
    ],
    "pricing": {
        "from": "2024-06-30T22:00:00.000Z",
        "to": "2024-07-31T21:59:59.999Z",
        "shipping": [
            {
            "courier": "mpl",
            "prices": [
                {
                "min": 0,
                "max": 1000,
                "cost": 1110
                },
                {
                "min": 1001,
                "max": 2000,
                "cost": 1140
                },
                {
                "min": 2001,
                "max": 3000,
                "cost": 1190
                },
                {
                "min": 3001,
                "max": 4000,
                "cost": 1230
                },
                {
                "min": 4001,
                "max": 5000,
                "cost": 1270
                },
                {
                "min": 5001,
                "max": 10000,
                "cost": 1340
                },
                {
                "min": 10001,
                "max": 15000,
                "cost": 1530
                },
                {
                "min": 15001,
                "max": 20000,
                "cost": 1690
                },
                {
                "min": 20001,
                "max": 25000,
                "cost": 1980
                },
                {
                "min": 25001,
                "max": 30000,
                "cost": 2260
                },
                {
                "min": 30001,
                "max": 35000,
                "cost": 3440
                },
                {
                "min": 35001,
                "max": 40000,
                "cost": 3650
                }
            ]
            },
        ],
        "cod": [
            {
            "courier": "mpl",
            "prices": [
                {
                "min": 0,
                "max": 20000,
                "fee": 200,
                "percentage": 0.5
                },
                {
                "min": 20001,
                "max": 50000,
                "fee": 260,
                "percentage": 0.5
                },
                {
                "min": 50001,
                "max": 100000,
                "fee": 410,
                "percentage": 0.5
                },
                {
                "min": 100001,
                "max": 200000,
                "fee": 560,
                "percentage": 0.5
                },
                {
                "min": 200001,
                "max": 500000,
                "fee": 870,
                "percentage": 0.5
                },
                {
                "min": 500001,
                "max": 1000000,
                "fee": 1420,
                "percentage": 0.5
                },
                {
                "min": 1000001,
                "max": 2000000,
                "fee": 2850,
                "percentage": 0.5
                }
            ]
            },
        ],
        "created": "2024-07-01T18:24:43.042Z",
        }
    }
}

Base URL ¶

Authentication ¶

Date Format ¶

API Conventions ¶

Errors ¶

Shipments ¶

Create shipment ¶

Create shipmentPOST/shipment/

Body parameters ¶

Possible error codes ¶

Example URI

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Get shipment ¶

Get shipmentGET/shipment/{trackingNumber}/

Example URI

Headers

Body

Delete shipment ¶

Delete shipmentDELETE/shipment/{trackingNumber}/

Example URI

Body

Headers

Body

Get shipment label ¶

Get shipment labelGET/shipment/{trackingNumber}/label

Example URI

Headers

Body

Headers

Body

Utils ¶

Delivery Points ¶

Delivery PointsGET/delivery-points/

Example URI

Headers

Body

Account Information ¶

Account InformationGET/account-details/

Example URI

Headers

Body

Base URL

Authentication

Date Format

API Conventions

Errors

Create shipment
POST`/shipment/`

Body parameters

Possible error codes

Get shipment
GET`/shipment/{trackingNumber}/`

Delete shipment
DELETE`/shipment/{trackingNumber}/`

Get shipment label
GET`/shipment/{trackingNumber}/label`

Delivery Points
GET`/delivery-points/`

Account Information
GET`/account-details/`