Back to top

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

Changelog

  • 2024-11-29: Specified dimension parameters(weight, length, height) to the generate shipment request

  • 2024-08-01: First version of the documentation

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.

In some cases, package length, width and height should be submitted too:

  • If you want to dispatch an MPL package from an MPL Csomagautomata(the cabinet size will be set based on the package dimensions)

  • If the courieres requires the package dimensions to be specified, for example DHL(used to calculate volumetric weight)

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
length number No Package length in cm. Required in specific use-cases, see abow.
width number No Package width in cm. Required in specific use-cases, see abow.
height number No Package height in cm. Required in specific use-cases, see abow.
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",
        }
    }
}

Generated by aglio on 01 Dec 2024