Alaikis Documents

Appearance

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:

bash
POST /api/tokens

Request Body:

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

Response:

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

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:

python
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:

javascript
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:

bash
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:

json
{
  "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:

bash
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:

bash
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:

bash
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:

bash
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:

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

Checking Processing Status ​

Check the status of an async job:

bash
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:

bash
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:

bash
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:

bash
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:

json
{
  "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:

bash
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:

bash
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:

bash
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:

bash
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:

bash
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:

bash
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:

bash
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:

bash
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:

bash
pip install alaikis-sdk
python
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:

bash
npm install @alaikis/sdk
javascript
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:

javascript
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:

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

Use the Java SDK:

java
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:

python
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:

python
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:

python
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:

python
# 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:

python
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.