Version: 1.0

API Documentation

Welcome to the Kvikk Shipping API! Our API is designed to simplify the way you integrate shipping services into your applications. With Kvikk, you can easily manage shipping processes, track packages, generate labels, and get real-time shipping rates – all in one place.

Whether you're running an e-commerce store, a logistics platform, or simply need efficient shipping solutions for your business, the Kvikk API empowers you to streamline and automate your shipping operations.

This documentation will guide you through the API’s features, offering easy-to-follow instructions, code examples, and explanations. Whether you're a developer integrating shipping functionality for the first time or an experienced developer, you'll find all the information you need to get started with the Kvikk Shipping API.

Let's get started, and revolutionize your shipping process with Kvikk!

Authentication

Before you can start making API calls, you need to authenticate with your API key. This key ensures that your requests are secure and authorized.

How to Obtain an API Key:

• Log in to Your Account
  • Go to the Kvikk website and log in with your account credentials.
• Click on Settings
  • After logging in, navigate to your account settings.
• Find the API Key Section
  • In the settings menu, locate and click on the API Key or API Access section.
• Click on "New Key"
  • Inside the API Key section, you’ll find an option to create a new key. Click on "New Key" or "Generate API Key".
• Copy the API Token
  • Once the key is generated, a unique API token will be displayed on the screen.
  • Copy this token and store it securely, as it’s your access key for the API.

How to Authenticate:

Include the X-API-KEY header in every request with your API key as the value:

Example:

X-API-KEY: eyJraWQiOiI0...

Your API key acts as your personal access token. If you don't include it, or if it’s invalid, you’ll receive an HTTP 401 Unauthorized error, so make sure you’ve got it right!

Date Format

All timestamps in the API follow the ISO 8601 format, ensuring clarity and uniformity in your application. Everything is provided in UTC to avoid time zone confusion, no matter where your users are located.

Example:

2024-08-01 10:18:42.697Z

This means the date is 2024-08-01 and the time is 10:18:42.697 in UTC.

API Conventions

Kvikk’s API is built on top of HTTP and follows RESTful principles. Below, we’ve outlined the key conventions you’ll need to keep in mind when interacting with the API.

1. Path Matching:

• The endpoint /something is functionally equivalent to /something/. Both URLs will lead to the same resource or perform the same operation, regardless of whether or not a trailing slash is included

2. Case Sensitivity:

• URL paths, query parameters, and JSON fields are case-sensitive.
• For example: /shipment and /Shipment are treated as different. So, always double-check the casing!

3. Standard HTTP Status Codes:

• 2xx: Everything is awesome – the request succeeded (e.g., 200 OK, 201 Created).
• 4xx: Something went wrong on your end – check your request (e.g., 400 Bad Request, 404 Not Found).
• 5xx: Oops, something went wrong on our end – try again later (e.g., 500 Internal Server Error).

4. Error Handling:

• If something goes wrong, the response will include an error message with details to help you diagnose and fix the issue.
• Always handle errors gracefully by checking both the HTTP status code and the error message.

5. Request Parameters:

• We don’t ignore unexpected query parameters or extra fields in the JSON body. So, be sure to only send what’s required to avoid errors.
• Missing or incorrect parameters? That’s a 400 Bad Request waiting to happen.

6. Response Format:

• Every response you get is in JSON format. This is true for both success and error responses.
• Successful responses will have a status of "success", while errors will provide a clear message on what went wrong.

Example of a Successful Response:

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

This standardized format ensures consistency and ease of use across all API interactions.

Errors

We use standard HTTP response codes to indicate the success or failure of your requests. Below is a quick guide to what each code means:

Code	Description	What to Do
200	OK: The request was processed successfully.	Everything is great! You can move on.
201	Created: The requested resource was created successfully.	The resource is now available.
204	No Content: The resource was deleted.	The request succeeded, but no data was returned.
400	Bad Request: There’s an issue with your request.	Check your parameters, make sure everything required is included.
401	Unauthorized: Invalid or missing API key.	Include a valid API key in the X-API-KEY header.
403	Forbidden: You don’t have permission to access this resource.	Double-check your API key’s permissions or check for rate limiting.
404	Not Found: The resource doesn’t exist.	Verify the URL or resource identifier.
409	Conflict: The resource already exists.	Resolve the conflict (e.g., try a different name) and retry.
500	Internal Server Error: Something went wrong on the server side.	Wait a moment and retry. If the issue persists, contact support.
502	Bad Gateway: The server received an invalid response.	Retry the request.
503	Service Unavailable: The service is temporarily unavailable.	Wait and try again later.
504	Gateway Timeout: The request took too long to process.	Retry after a brief pause.

Each error is designed to give you clear and actionable feedback, helping you get back on track quickly.

Authentication

API Key: X-API-KEY

Security Scheme Type:	apiKey
Header parameter name:	X-API-KEY

Contact

KVIKK: [email protected]