User Guide

This guide provides comprehensive instructions for using the Alaikis BI API services. Learn how to authenticate, make API calls, and integrate our services into your applications.

Authentication Workflow

Step 1: Get API Key Creation

Create an API key for programmatic access:

POST /api/tokens

Request Body:

{
    "name": "Production Server Key",
    "description": "API key for production environment",
    "scopes": ["packing:read", "packing:write", "product-trace:read", "product-trace:write"]
}

Response:

{
    "id": 1,
    "token": "alaikis_sk_xxxxxxxxxxxxxxxxxx",
    "name": "Production Server Key",
    "created_at": "2024-01-15T10:30:00"
}

::: warning Store Securely The API key is only shown once. Store it securely and never expose it in client-side code. :::

Step 2: Using the API Key

Include the API key in all requests:

import requests

headers = {
    "Authorization": "Bearer alaikis_sk_xxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json"
}

response = requests.get("https://api.alaikis.com/bi/packing", headers=headers)

Step 3: JWT Authentication (Web Applications)

For browser-based applications, use JWT tokens:

const urlParams = new URLSearchParams(window.location.search);
const token = urlParams.get('token');

if (token) {
    localStorage.setItem('auth_token', token);
}

Packing API Usage

Basic Packing Calculation

Calculate optimal packing for your products:

curl -X POST "https://api.alaikis.com/bi/packing/calculate" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"sku_id": "SKU001", "quantity": 50, "length": 30, "width": 20, "height": 10, "weight": 0.5},
      {"sku_id": "SKU002", "quantity": 30, "length": 40, "width": 30, "height": 15, "weight": 1.2}
    ],
    "pallet_type": "standard"
  }'

Response:

{
  "pallets": [
    {
      "id": "PLT-001",
      "pallet_type": "standard",
      "items": [
        {"sku_id": "SKU001", "quantity": 50},
        {"sku_id": "SKU002", "quantity": 30}
      ],
      "total_weight": 61.0,
      "utilization": 0.85
    }
  ],
  "total_pallets": 1,
  "total_cost": 25.00,
  "layers_used": 3,
  "success": true
}

Understanding the Response

The response contains:

• pallets: Array of pallet objects with items placed on each pallet
• total_pallets: Total number of pallets used
• total_cost: Estimated shipping cost
• layers_used: Number of layers per pallet
• success: Whether the calculation was successful

Pre-assigned Pallets

You can also specify pre-assigned pallets:

curl -X POST "https://api.alaikis.com/bi/packing/calculate" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"sku_id": "SKU001", "quantity": 100, "length": 30, "width": 20, "height": 10}
    ],
    "preassigned_pallets": [
      {"pallet_id": "PLT-001", "remaining_capacity": 0.6}
    ]
  }'

Product Trace API Usage

Recording a Product

Record a product with trace information:

curl -X POST "https://api.alaikis.com/bi/trace/record" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "PRODUCT001",
    "identification_code": "IC-2024-001",
    "image_url": "https://example.com/image.jpg",
    "metadata": {
      "manufacturer": "Acme Corp",
      "batch": "BATCH-2024-001"
    }
  }'

Multi-Image Recording

Record a product with multiple images:

curl -X POST "https://api.alaikis.com/bi/trace/record" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "PRODUCT001",
    "identification_code": "IC-2024-002",
    "image_urls": [
      "https://example.com/image1.jpg",
      "https://example.com/image2.jpg",
      "https://example.com/image3.jpg"
    ]
  }'

Asynchronous Recording

For large batches, use async recording:

curl -X POST "https://api.alaikis.com/bi/trace/record-async" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"sku": "P001", "identification_code": "IC-001"},
      {"sku": "P002", "identification_code": "IC-002"}
    ]
  }'

Response:

{
  "job_id": "JOB-12345",
  "status": "processing",
  "estimated_time": "5 minutes"
}

Checking Processing Status

Check the status of an async job:

curl -X GET "https://api.alaikis.com/bi/trace/job/JOB-12345" \
  -H "Authorization: Bearer your_api_key"

Verifying a Product

Verify a product using barcode or image:

curl -X POST "https://api.alaikis.com/bi/trace/verify" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "identification_code": "IC-2024-001",
    "image_url": "https://example.com/verify.jpg"
  }'

Barcode Detection

Detect and decode barcodes from images:

curl -X POST "https://api.alaikis.com/bi/trace/barcode-detect" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/barcode.jpg"
  }'

Product Scan API with DINOv2 Optimization

Use the advanced DINOv2 model for accurate product identification:

curl -X POST "https://api.alaikis.com/bi/trace/scan" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/scan.jpg",
    "use_dinov2": true,
    "threshold": 0.85
  }'

Response:

{
  "success": true,
  "matches": [
    {
      "sku": "SKU-001",
      "identification_code": "IC-2024-001",
      "product_name": "Product A",
      "similarity_score": 0.95,
      "match_method": "dinov2",
      "dinov2_similarity": 0.97,
      "ocr_similarity": 0.88
    }
  ],
  "total_count": 1,
  "exit_reason": "match_found",
  "processing_time_ms": 150,
  "early_termination": true,
  "stages_completed": ["dinov2_matching"],
  "architecture_used": "dinov2_vit_b_14"
}

DINOv2 Early Termination

The DINOv2 model can perform early termination when a high-confidence match is found, reducing processing time:

• If DINOv2 similarity exceeds 0.95, the API returns immediately without OCR processing
• This can reduce response time by up to 50%

Response Example with DINOv2 Early Termination

When early termination occurs, the response includes:

• early_termination: Boolean indicating if early termination was used
• exit_reason: Reason for termination (match_found, no_match, max_iterations)
• stages_completed: Array of stages that were executed
• architecture_used: The DINOv2 architecture variant used

DINOv2 Performance Optimization Tips

1. Use early termination: Set threshold to 0.9+ for faster responses
2. Optimize images: Use images with clear product labels
3. Batch processing: Process multiple images in a single request
4. Cache results: Store verification results for repeat queries

Scan Status Monitoring

Monitor the scan job status:

curl -X GET "https://api.alaikis.com/bi/trace/scan-status/SCAN-123" \
  -H "Authorization: Bearer your_api_key"

DINOv2 Verify API

Verify products using the DINOv2 model:

curl -X POST "https://api.alaikis.com/bi/trace/dinov2-verify" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "SKU-001",
    "identification_code": "IC-2024-001",
    "image_url": "https://example.com/verify.jpg"
  }'

Address Parsing API Usage

Parse a Single Address

Parse a single address string:

curl -X POST "https://api.alaikis.com/bi/address/parse" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "raw_address": "1600 Pennsylvania Ave NW, Washington, DC 20500"
  }'

Batch Address Parsing

Parse multiple addresses in one request:

curl -X POST "https://api.alaikis.com/bi/address/batch" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": [
      "1600 Pennsylvania Ave NW, Washington, DC 20500",
      "350 Fifth Avenue, New York, NY 10118"
    ]
  }'

Format Address

Format an address according to country standards:

curl -X POST "https://api.alaikis.com/bi/address/format" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "US",
    "street": "1600 Pennsylvania Ave NW",
    "city": "Washington",
    "region": "DC",
    "postal_code": "20500"
  }'

Check Service Status

Check the status of address parsing service:

curl -X GET "https://api.alaikis.com/bi/address/status" \
  -H "Authorization: Bearer your_api_key"

Classification API Usage

Classify Shipping Status

Classify shipping status from tracking updates:

curl -X POST "https://api.alaikis.com/bi/classification/shipping" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Package delivered to recipient"
  }'

With Custom Examples

Use custom classification with examples:

curl -X POST "https://api.alaikis.com/bi/classification/shipping" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Out for delivery",
    "examples": [
      {"text": "Out for delivery", "label": "in_transit"},
      {"text": "Delivered", "label": "delivered"}
    ]
  }'

SDK Usage

Python SDK

Install and use the Python SDK:

pip install alaikis-sdk

from alaikis import AlaikisClient

client = AlaikisClient(api_key="your_api_key")

# Calculate packing
result = client.packing.calculate(
    items=[
        {"sku_id": "SKU001", "quantity": 50, "length": 30, "width": 20, "height": 10}
    ],
    pallet_type="standard"
)

print(result)

JavaScript SDK

Install and use the JavaScript SDK:

npm install @alaikis/sdk

import { AlaikisClient } from '@alaikis/sdk';

const client = new AlaikisClient({ apiKey: 'your_api_key' });

const result = await client.packing.calculate({
  items: [
    { skuId: 'SKU001', quantity: 50, length: 30, width: 20, height: 10 }
  ],
  palletType: 'standard'
});

console.log(result);

Verify a product:

const verifyResult = await client.trace.verify({
  sku: 'SKU001',
  identificationCode: 'IC-2024-001',
  imageUrl: 'https://example.com/image.jpg'
});

Java SDK

Add the dependency to your Maven project:

<dependency>
    <groupId>com.alaikis</groupId>
    <artifactId>sdk</artifactId>
    <version>1.0.0</version>
</dependency>

Use the Java SDK:

import com.alaikis.sdk.AlaikisClient;
import com.alaikis.sdk.model.PackingResult;

AlaikisClient client = new AlaikisClient("your_api_key");

PackingResult result = client.getPackingApi().calculate(
    Arrays.asList(
        new Item().setSkuId("SKU001").setQuantity(50)
            .setLength(30).setWidth(20).setHeight(10)
    ),
    "standard"
);

Best Practices

1. Error Handling

Implement proper error handling:

import requests
from requests.exceptions import HTTPError

try:
    response = requests.post(url, json=payload, headers=headers)
    response.raise_for_status()
    result = response.json()
except HTTPError as e:
    if response.status_code == 401:
        print("Authentication failed - check API key")
    elif response.status_code == 429:
        print("Rate limit exceeded - retry later")
    elif response.status_code == 400:
        error_detail = response.json().get("detail", {})
        print(f"Validation error: {error_detail}")
    else:
        print(f"HTTP error: {e}")
except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")

2. Retry Logic

Implement exponential backoff for transient errors:

import time
from requests.adapters import HTTPAdapter
from requests.packages.urllib3.util.retry import Retry

session = requests.Session()
retry_strategy = Retry(
    total=3,
    backoff_factor=1,
    status_forcelist=[429, 500, 502, 503, 504]
)
adapter = HTTPAdapter(max_retries=retry_strategy)
session.mount("https://", adapter)

response = session.get(url, headers=headers)

3. Request Timeouts

Always set appropriate timeouts:

response = requests.get(url, headers=headers, timeout=30)

4. Image Optimization

Optimize images before uploading:

• Use JPEG format for photos
• Use PNG for graphics with text
• Compress images to reduce file size
• Target 80% quality with reasonable dimensions

5. Batch Operations

Use batch endpoints when available:

# Instead of individual requests
for address in addresses:
    result = parse_single(address)

# Use batch API
results = parse_batch(addresses)

6. Caching Strategies

Implement caching for frequently accessed data:

import hashlib
import json
from functools import lru_cache

def get_cache_key(params):
    return hashlib.md5(json.dumps(params, sort_keys=True).encode()).hexdigest()

# Cache API responses
@lru_cache(maxsize=1000)
def cached_lookup(key):
    return api_lookup(key)

Troubleshooting

Common Issues

401 Unauthorized

• Check if your API key is valid
• Ensure the API key has the required scopes
• Verify the Authorization header format

429 Rate Limited

• Implement exponential backoff
• Check your usage quota
• Consider upgrading to a higher tier

400 Bad Request

• Validate request payload format
• Check required parameters
• Verify JSON syntax

Timeout Errors

• Increase timeout values
• Optimize image sizes
• Use async endpoints for large requests

Support and Performance

For additional support, contact support@alaikis.com.

For performance optimization tips, refer to our best practices guide.