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 shipmentPOST/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 |
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
home delivery
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"
}
shipping to delivery point
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"
}
201
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
}
}
}
400
Headers
Content-Type: application/json
Body
{
"status": "fail",
"code": "wrong_weight_value",
"message": "Unable to create shipment with given weight."
}
Get shipment ¶
Get shipmentGET/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
- trackingNumber
string
(required) Example: M123412341234Shipment’s tracking number
200
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 shipmentDELETE/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
- trackingNumber
string
(required) Example: M123412341234Shipment’s tracking number
200
Body
{
"status": "success",
"code": "shipment_deleted",
"message": "Shipment successfully deleted."
}
400
Headers
Content-Type: application/json
Body
{
"status": "fail",
"code": "shipment_dispatched",
"message": "Shipment already dispatched."
}
Get shipment label ¶
Get shipment labelGET/shipment/{trackingNumber}/label
Get the shipping label for a specific shipment.
Example URI
- trackingNumber
string
(required) Example: M123412341234Shipment’s tracking number
200
Headers
Content-Type: application/pdf
Content-Disposition: attachment; filename="M123412341234_label.pdf"
Body
[Binary PDF content of the shipping label]
400
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 PointsGET/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
- courier
string
(required) Example: mplFilter by courier name.
- type
string
(required) Example: mpl_postapontFilter by type of delivery point. Allowed to be empty, in that case it will return all points from the courier.
200
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 InformationGET/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
200
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",
}
}
}