How to setup API in a local instance

To test and develop with Karrio APIs in your local environment, you’ll need to set up the Karrio server, create API credentials, and configure your development workflow. This guide will walk you through the complete process.

Setting Up Your Local Karrio Instance

Quick Start with Docker

If you don’t have Karrio running locally yet, here’s the fastest way to get started:

Create your project folder
1mkdir karrio-api-dev
2cd karrio-api-dev
3
4# Download the latest version of karrio
5curl https://raw.githubusercontent.com/karrioapi/karrio/HEAD/docker/docker-compose.yml -o docker-compose.yml
6curl https://raw.githubusercontent.com/karrioapi/karrio/HEAD/docker/.env -o .env

Start the Karrio services:

1docker compose up -d

Wait for all services to be ready. You can check the status with:

1docker compose ps

1- KARRIO_PUBLIC_URL=http://localhost:5002
2+ KARRIO_PUBLIC_URL=http://[YOUR-VM-IP-ADDRESS]:5002

Once running, you should have:

• API Server: http://localhost:5002
• Dashboard: http://localhost:3002
• API Documentation: http://localhost:5002/openapi

Testing Your API Setup

1. Test API Connectivity

First, verify that your API is accessible:

1curl -X GET http://localhost:5002

You should receive a response indicating the API is healthy.

2. Set Up Environment Variables

To make your API testing experience smoother, let’s set up some environment variables that we’ll reuse throughout this guide:

Set base configuration
1export KARRIO_API_URL="http://localhost:5002"
2export KARRIO_TEST_MODE="true"
3
4# Verify the setup
5echo "API URL: $KARRIO_API_URL"
6echo "Test Mode: $KARRIO_TEST_MODE"

3. Login and Get Access Token

Start by authenticating with the default admin credentials to get an access token:

1curl -X POST $KARRIO_API_URL/api/token \
2  -H "Content-Type: application/json" \
3  -d '{
4    "email": "admin@example.com",
5    "password": "demo"
6  }'

Expected Response:

1{
2  "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
3  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."
4}

Save the access token as an environment variable:

Replace with your actual token from the response above
1export KARRIO_ACCESS_TOKEN="eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."
2
3# Verify it's set
4echo "Access Token: ${KARRIO_ACCESS_TOKEN:0:20}..."

1export KARRIO_ACCESS_TOKEN=$(curl -s -X POST $KARRIO_API_URL/api/token \
2  -H "Content-Type: application/json" \
3  -d '{"email": "admin@example.com", "password": "demo"}' | \
4  jq -r '.access')

4. Retrieve API Keys (Test Mode)

Get your API keys using the GraphQL endpoint:

1curl -X POST $KARRIO_API_URL/graphql \
2  -H "Authorization: Bearer $KARRIO_ACCESS_TOKEN" \
3  -H "Content-Type: application/json" \
4  -H "x-test-mode: $KARRIO_TEST_MODE" \
5  -d '{
6    "query": "query { token { key test_mode created permissions } }"
7  }'

Save your API key as an environment variable:

Replace with your actual API key from the response above
1export KARRIO_API_KEY="your_api_key_here"
2
3# Verify it's set
4echo "API Key: ${KARRIO_API_KEY:0:20}..."

1export KARRIO_API_KEY=$(curl -s -X POST $KARRIO_API_URL/graphql \
2  -H "Authorization: Bearer $KARRIO_ACCESS_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{"query": "query { token { key } }"}' | \
5  jq -r '.data.token.key')

5. Test Authentication with API Key

Test your API key authentication using GraphQL:

1curl -X POST $KARRIO_API_URL/graphql \
2  -H "Authorization: Token $KARRIO_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "query": "query { user { email full_name is_staff date_joined } }"
6  }'

A successful response will return your user information:

1{
2  "data": {
3    "user": {
4      "email": "admin@example.com",
5      "full_name": "Admin User",
6      "is_staff": true,
7      "date_joined": "2024-01-01T00:00:00Z"
8    }
9  }
10}

6. Create a Generic Carrier Connection

Set up a test carrier connection for development purposes:

1curl -X POST $KARRIO_API_URL/v1/connections \
2  -H "Authorization: Token $KARRIO_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "carrier_name": "generic",
6    "carrier_id": "aeroship:us:test",
7    "credentials": {
8      "custom_carrier_name": "aeroship",
9      "display_name": "Aeroship"
10    },
11    "metadata": {
12      "description": "Generic test carrier for development"
13    }
14  }'

Expected Response:

1{
2  "id": "conn_xxxxx",
3  "carrier_name": "generic",
4  "carrier_id": "generic_test_connection",
5  "test_mode": true,
6  ...
7}

Save the connection ID as an environment variable:

Replace with your actual connection ID from the response above
1export KARRIO_CARRIER_ID="aeroship:us:test"
2
3# Verify it's set
4echo "Carrier ID: $KARRIO_CARRIER_ID"

1export KARRIO_CARRIER_ID=$(curl -s -X GET $KARRIO_API_URL/v1/connections \
2  -H "Authorization: Token $KARRIO_API_KEY" \
3  -H "Content-Type: application/json" | \
4  jq -r '.results[0].carrier_id')

7. Create Your First Shipment

Create a test shipment to generate your first label:

1curl -X POST $KARRIO_API_URL/v1/shipments \
2  -H "Authorization: Token $KARRIO_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "shipper": {
6      "postal_code": "10001",
7      "city": "New York",
8      "country_code": "US",
9      "state_code": "NY",
10      "address_line1": "123 Shipper Street",
11      "person_name": "Sender Name",
12      "company_name": "Sender Company",
13      "phone_number": "1234567890",
14      "email": "sender@example.com"
15    },
16    "recipient": {
17      "postal_code": "90210",
18      "city": "Beverly Hills",
19      "country_code": "US",
20      "state_code": "CA",
21      "address_line1": "456 Recipient Ave",
22      "person_name": "Recipient Name",
23      "company_name": "Recipient Company",
24      "phone_number": "0987654321",
25      "email": "recipient@example.com"
26    },
27    "parcels": [{
28      "weight": 1.0,
29      "width": 10,
30      "height": 10,
31      "length": 10,
32      "weight_unit": "LB",
33      "dimension_unit": "IN"
34    }],
35    "service": "standard_service",
36    "label_type": "PDF",
37    "reference": "TEST_SHIPMENT_001",
38    "metadata": {
39      "test_shipment": true
40    }
41  }'

Expected Response:

1{
2  "id": "ship_xxxxx",
3  "status": "purchased",
4  "carrier_name": "generic",
5  "service": "standard_service",
6  "tracking_number": "TEST123456789",
7  "label_url": "/v1/shipments/ship_xxxxx/label",
8  ...
9}

Save the shipment details:

Replace with your actual values from the response above
1export KARRIO_SHIPMENT_ID="ship_xxxxx"
2export KARRIO_TRACKING_NUMBER="TEST123456789"
3
4echo "Shipment ID: $KARRIO_SHIPMENT_ID"
5echo "Tracking Number: $KARRIO_TRACKING_NUMBER"

Download the label:

1open $KARRIO_API_URL/v1/shipments/$KARRIO_SHIPMENT_ID/label.pdf

8. Verify Your Setup

After running the setup script, you should have:

• ✅ A working JWT token for authentication
• ✅ API keys for programmatic access
• ✅ A generic carrier connection for testing
• ✅ A test shipment with tracking number
• ✅ A shipping label (PDF) ready for download
• ✅ All environment variables saved for reuse

You can now start building your shipping integration using the Karrio API!

Next Steps

Once you have your local API development environment set up:

1. Explore the API Reference: Visit http://localhost:5002/openapi for interactive API documentation
2. Test with Real Carriers: Configure production carrier credentials for real-world testing
3. Deploy Your Application: Move from local development to staging and production environments

For more advanced topics, check out:

• Plugin Development - Extending Karrio functionality
• Carrier Integration - Adding new shipping carriers
• API Reference - Complete API documentation