Create Shipment
POST/shipment
Create a New Shipment (/shipment)
This endpoint allows you to create a new shipment. Upon successful creation, you will receive two tracking numbers in the response:
- Kvikk-generated tracking number: This tracking number is created by Kvikk and can be used for later shipment management.
- Courier-generated tracking number: This tracking number is generated by the courier and can be used to track the shipment within the courier's system.
You can use this same endpoint to create both home delivery and delivery point shipments. Additionally, the response will include a PDF shipping label in base64 format, which you can store for later use.
The generated tracking numbers follow this format:
M{12 digits}. The first letter of the tracking number indicates the courier:
- M = MPL
- P = Packeta
- E = Express One
- F = FámaFutár
Package Dimensions (Optional)
In certain cases, the following package dimensions may be required:
-
MPL Csomagautomata Shipments: If you are dispatching a package via MPL's Csomagautomata (automated parcel lockers), the dimensions of the package should be provided. The cabinet size will be determined based on the package dimensions.
-
Courier Requirements: Some couriers (e.g., DHL) may require package dimensions to be submitted in order to calculate volumetric weight.
Ensure that you provide the correct dimensions when required to avoid errors during shipment creation.
Possible Error Codes
| Error Code | Description | Details |
|---|---|---|
| invalid_delivery_point_type | The selected delivery point type does not exist. | This error occurs when the specified deliveryPointType is not valid or does not exist in the system. Each courier has a set of predefined delivery point types (e.g., automated lockers, pickup points). If the type provided doesn’t match the available options, this error is triggered. |
| invalid_delivery_point_id | The delivery point ID does not exist, doesn’t belong to the selected type, or is unavailable (closed, deleted, damaged). | This error occurs if the provided deliveryPointID is invalid or unreachable. It could be because the delivery point doesn’t exist, or the point is closed, deleted, or damaged. The deliveryPointID should match a valid location for the given deliveryPointType. |
| wrong_weight_value | The courier won’t ship a shipment with this weight. | This error is returned if the weight of the package exceeds the limits defined by the selected courier. Each courier has specific weight restrictions, and this error helps ensure that packages are within acceptable shipping weight. |
| wrong_cod_value | The courier can’t handle the COD (Cash on Delivery) value. | This error occurs when the cod (Cash on Delivery) value exceeds the maximum limit set by the selected courier. Some couriers do not accept large amounts for COD, and this error ensures that the provided amount aligns with the courier's capabilities. |
| missing_weight | Valid weight is required. | This error is triggered when the weight of the package is missing from the request. A valid weight is essential for the shipment calculation, and this error ensures that the weight parameter is provided and is valid. |
| label_not_generated | Unable to generate the label due to an issue with the Courier’s API. | This error occurs when the shipment label cannot be generated due to issues on the courier's end, such as an API failure or unexpected issues with their system. It implies that the process of generating the shipment label has failed. |
| sender_not_found | The sender ID does not belong to the user or doesn’t exist. | This error is returned when the senderID provided does not match any valid sender registered under the user's account. The senderID must correspond to a legitimate user or entity. |
| courier_not_found | Wrong courier ID. | This error happens when the courier ID provided in the request is incorrect or does not match any available courier in the system. The courier ID should be one of the supported courier values such as mpl, expressone, packeta, or famafutar. |
| courier_not_active | The selected courier is not activated in the user’s account. | This error occurs when the selected courier is not activated in the user’s account, meaning the user has not enabled the courier for use in their API integration. This could be due to the courier not being set up properly in the user's system or inactive status for the particular courier. |
Request
Responses
- 201
- 400
Created
Bad Request