LogisticaHQ REST API

Overview

logisticaHQ provides a comprehensive REST API that enables seamless integration with external systems including ERPs, e-commerce platforms, and custom applications. This guide covers authentication, API endpoints, and common integration patterns.

Full Documentation: For complete logisticaHQ documentation including user guides, configuration, and additional resources, visit https://docs.p4.software

Table of Contents

• API Authentication
• API Structure & Patterns
• Core Resources
• Integration Examples
• Webhook Configuration
• Error Handling
• Best Practices

API Authentication

Obtaining Your API Key

SECURITY: Never expose your API key in client-side code or public repositories. Store credentials securely using environment variables or secure key management systems.

1. Navigate to Setup > System > Users
2. Click on the 'system' user from the list
3. Click the dropdown icon to reveal your tenant's API key
4. Copy and securely store the API key

Authentication Headers

All API requests require the following headers:

Authorization: Bearer {your-api-key}
Content-Type: application/json
Accept: application/json

API Structure & Patterns

Base URL Format

https://api.LogisticaHQ.com/{Resource}Api/{Action}

• Base URL: Always https://api.LogisticaHQ.com (same for all tenants)
• : The resource type (Product, Client, Vendor, PickTicket, PurchaseOrder, etc.)
• : The operation (CreateOrUpdate, DeleteBatch, Execute, etc.)

Standard Endpoints

Each resource typically supports these actions:

Example Endpoints

https://api.LogisticaHQ.com/ProductApi/CreateOrUpdate
https://api.LogisticaHQ.com/PickTicketApi/CreateOrUpdate
https://api.LogisticaHQ.com/PurchaseOrderApi/DeleteBatch
https://api.LogisticaHQ.com/FourWallReport/Execute

Note: The tenant identification is handled through the API key in the Authorization header, not through the URL.

Core Resources

1. Products

Create/Update Product

POST https://api.LogisticaHQ.com/ProductApi/CreateOrUpdate

{
  "sku": "WIDGET-001",
  "description": "Blue Widget - Large",
  "barcode": "123456789012",
  "client_id": "CLIENT01",
  "weight": 1.5,
  "length": 10,
  "width": 8,
  "height": 5,
  "unit_of_measure": "EACH",
  "lot_tracking": false,
  "serial_tracking": false,
  "expiry_tracking": false,
  "active": true,
  "pack_sizes": [
    {
      "pack_size": 12,
      "barcode": "123456789013",
      "description": "Case of 12"
    }
  ]
}

Response

{
  "success": true,
  "product_id": "12345",
  "message": "Product created successfully"
}

2. Purchase Orders

Create Purchase Order

POST https://api.LogisticaHQ.com/PurchaseOrderApi/CreateOrUpdate

{
  "po_number": "PO-2024-001",
  "vendor_id": "VENDOR01",
  "warehouse_code": "WH01",
  "expected_date": "2024-12-31",
  "reference": "Vendor Ref #12345",
  "lines": [
    {
      "line_number": 1,
      "sku": "WIDGET-001",
      "quantity": 100,
      "unit_cost": 5.50
    },
    {
      "line_number": 2,
      "sku": "WIDGET-002",
      "quantity": 50,
      "unit_cost": 7.25
    }
  ]
}

3. Sales Orders (Pick Tickets)

Create Sales Order

POST https://api.LogisticaHQ.com/PickTicketApi/CreateOrUpdate

{
  "order_number": "SO-2024-001",
  "customer_id": "CUST01",
  "warehouse_code": "WH01",
  "order_date": "2024-01-15",
  "required_date": "2024-01-20",
  "ship_to": {
    "name": "John Doe",
    "company": "ABC Company",
    "address1": "123 Main Street",
    "address2": "Suite 100",
    "city": "Anytown",
    "state": "CA",
    "postal_code": "12345",
    "country": "US",
    "phone": "555-123-4567"
  },
  "carrier": "FEDEX",
  "service_level": "GROUND",
  "lines": [
    {
      "line_number": 1,
      "sku": "WIDGET-001",
      "quantity": 5
    },
    {
      "line_number": 2,
      "sku": "WIDGET-002",
      "quantity": 10
    }
  ]
}

4. Inventory Operations

Get Current Inventory (FourWall Report)

GET https://api.LogisticaHQ.com/FourWallReport/Execute?warehouse_code=WH01

Response

{
  "success": true,
  "data": [
    {
      "sku": "WIDGET-001",
      "description": "Blue Widget - Large",
      "warehouse_code": "WH01",
      "bin_location": "A-01-01",
      "quantity_on_hand": 150,
      "quantity_allocated": 25,
      "quantity_available": 125,
      "lot_number": "LOT123",
      "expiry_date": "2025-12-31",
      "last_updated": "2024-01-15T10:30:00Z"
    }
  ],
  "total_records": 1
}

Inventory Adjustment

POST https://api.LogisticaHQ.com/InventoryApi/Adjust

{
  "warehouse_code": "WH01",
  "adjustments": [
    {
      "sku": "WIDGET-001",
      "bin_location": "A-01-01",
      "quantity": 10,
      "reason_code": "CYCLE_COUNT",
      "notes": "Physical count adjustment"
    }
  ]
}

5. Customers

Create/Update Customer

POST https://api.LogisticaHQ.com/CustomerApi/CreateOrUpdate

{
  "customer_number": "CUST01",
  "company_name": "ABC Company",
  "contact_person": "John Doe",
  "Email": "john@abccompany.com",
  "phone": "555-123-4567",
  "addresses": [
    {
      "type": "Shipping",
      "address1": "123 Main Street",
      "city": "Anytown",
      "state": "CA",
      "postal_code": "12345",
      "country": "US",
      "is_default": true
    }
  ]
}

6. Vendors

Create/Update Vendor

POST https://api.LogisticaHQ.com/VendorApi/CreateOrUpdate

{
  "vendor_number": "VENDOR01",
  "company_name": "XYZ Suppliers",
  "contact_person": "Jane Smith",
  "Email": "jane@xyzsuppliers.com",
  "phone": "555-987-6543"
}

Integration Examples

Basic HTTP Request (cURL)

curl -X POST https://api.LogisticaHQ.com/ProductApi/CreateOrUpdate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "TEST-001",
    "description": "Test Product"
  }'

Python Example

import requests
import json

class LogisticaHQClient:
    def __init__(self, api_key):
        self.base_url = "https://api.LogisticaHQ.com"
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }
    
    def create_product(self, product_data):
        url = f"{self.base_url}/ProductApi/CreateOrUpdate"
        response = requests.post(url, 
                                headers=self.headers, 
                                json=product_data)
        return response.json()
    
    def get_inventory(self, warehouse_code):
        url = f"{self.base_url}/FourWallReport/Execute"
        params = {"warehouse_code": warehouse_code}
        response = requests.get(url, 
                              headers=self.headers, 
                              params=params)
        return response.json()

# Usage
client = LogisticaHQClient("your-api-key")
Inventory = client.get_inventory("WH01")

JavaScript/Node.js Example

const axios = require('axios');

class LogisticaHQClient {
    constructor(apiKey) {
        this.baseURL = 'https://api.LogisticaHQ.com';
        this.headers = {
            'Authorization': `Bearer ${apiKey}`,
            'Content-Type': 'application/json'
        };
    }
    
    async createOrder(orderData) {
        try {
            const response = await axios.post(
                `${this.baseURL}/PickTicketApi/CreateOrUpdate`,
                orderData,
                { headers: this.headers }
            );
            return response.data;
        } catch (error) {
            console.error('Error creating order:', error.response.data);
            throw error;
        }
    }
}

// Usage
const client = new LogisticaHQClient('your-api-key');
const order = await client.createOrder({
    order_number: 'SO-2024-001',
    customer_id: 'CUST01',
    // ... other order data
});

C# Example

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

public class LogisticaHQClient
{
    private readonly HttpClient _httpClient;
    private readonly string _baseUrl = "https://api.LogisticaHQ.com";
    
    public LogisticaHQClient(string apiKey)
    {
        _httpClient = new HttpClient();
        _httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}");
        _httpClient.DefaultRequestHeaders.Add("Accept", "application/json");
    }
    
    public async Task

Webhook Configuration

logisticaHQ can send real-time notifications to your endpoints when specific events occur.

Available Webhook Events

• Order Events: Created, Allocated, Picked, Packed, Shipped
• Inventory Events: Low Stock, Stock Received, Cycle Count Complete
• Purchase Order Events: Received, Completed
• 3PL Events: Invoice Generated, Payment Received

Webhook Payload Example

{
  "event_type": "ORDER_SHIPPED",
  "timestamp": "2024-01-15T14:30:00Z",
  "tenant": "your-tenant-identifier",
  "data": {
    "order_number": "SO-2024-001",
    "tracking_number": "1234567890",
    "carrier": "FEDEX",
    "ship_date": "2024-01-15",
    "lines": [
      {
        "sku": "WIDGET-001",
        "quantity_shipped": 5
      }
    ]
  },
  "signature": "sha256=..."
}

Webhook Security Validation

Always validate webhook signatures to ensure authenticity:

import hmac
import hashlib

def validate_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(
        f"sha256={expected}",
        signature
    )

Error Handling

HTTP Status Codes

Error Response Format

{
  "success": false,
  "error": {
    "code": "INVALID_SKU",
    "message": "Product with SKU 'WIDGET-999' not found",
    "details": {
      "field": "sku",
      "value": "WIDGET-999"
    }
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Retry Strategy

Implement exponential backoff for transient errors:

import time
import random

def retry_request(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            
            # Exponential backoff with jitter
            wait_time = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(wait_time)

Best Practices

1. Rate Limiting

• Default limit: 100 requests per minute
• Implement request queuing for bulk Operations
• Use batch endpoints when available

2. Pagination

For large data sets, use pagination parameters:

GET https://api.LogisticaHQ.com/ProductApi/List?page=1&page_size=100

3. Filtering

Use query parameters to filter results:

GET https://api.LogisticaHQ.com/InventoryApi/List?warehouse_code=WH01&sku=WIDGET*

4. Idempotency

Include idempotency keys for critical Operations:

{
  "idempotency_key": "unique-key-12345",
  "order_number": "SO-2024-001",
  // ... rest of order data
}

5. Data Validation

Always validate data before sending:

• Required fields are present
• Data types are correct
• Values are within acceptable ranges
• SKUs and IDs exist in the system

6. Logging

Maintain comprehensive logs:

• All API requests and responses
• Error details and stack traces
• Performance metrics
• Webhook receipts

Testing

Sandbox Environment

Test your integration using the sandbox:

• Base URL: https://api.LogisticaHQ.com (same as Production)
• Use test API keys provided separately for sandbox access
• Data is reset daily

Test Data

Use these test SKUs in sandbox:

• TEST-001 through TEST-100: Standard Products
• LOT-001: Lot-tracked product
• SERIAL-001: Serial-tracked product
• EXPIRY-001: Expiry-tracked product

Support

Documentation Resources

• Complete Documentation: https://docs.p4.software
• Swagger/OpenAPI: https://api.LogisticaHQ.com/swagger/index.html
• Support Portal: Contact your logisticaHQ partner

Getting Help

When requesting Support, provide:

1. Your tenant identifier
2. API endpoint being called
3. Complete request (minus API key)
4. Response received
5. Timestamp of the request
6. Any error messages

Appendix: Common Integration Scenarios

E-Commerce Integration

Sync orders from your online store:

1. Receive order webhook from e-commerce platform
2. Create/update Customer in logisticaHQ
3. Create pick ticket with order details
4. Monitor order status via webhooks
5. Update tracking in e-commerce platform when shipped

ERP Integration

Maintain data synchronization:

1. Product master sync (hourly/daily)
2. Real-time order creation
3. Inventory level updates
4. Purchase order synchronization
5. Financial data export for invoicing

3PL Operations

Manage multi-client Operations:

1. Client-specific product catalogs
2. Segregated Inventory tracking
3. Automated billing generation
4. Client portal access via API
5. Custom reporting per client

Note: This documentation covers the standard logisticaHQ API. Additional endpoints and features may be available based on your subscription level and enabled modules. For complete documentation, visit https://docs.p4.software