API REST de LogisticaHQ

Descripción general

LogisticaHQ ofrece una API REST completa que permite integrarse sin fricción con sistemas externos: ERP, plataformas de comercio electrónico y aplicaciones propias. Esta guía cubre la autenticación, los endpoints y los patrones de integración más habituales.

Documentación completa: para consultar la documentación completa de LogisticaHQ —guías de usuario, configuración y recursos adicionales— visite https://docs.p4.software

Índice

• Autenticación de la API
• Estructura y patrones de la API
• Recursos principales
• Ejemplos de integración
• Configuración de Webhooks
• Manejo de errores
• Mejores Prácticas

Autenticación de la API

Cómo obtener su clave de API

SEGURIDAD: nunca exponga su clave de API en código del lado del cliente ni en repositorios públicos. Guarde las credenciales de forma segura mediante variables de entorno o sistemas de gestión de claves.

1. Vaya a Configuración > Sistema > Usuarios
2. Haga clic en el usuario 'system' de la lista
3. Haga clic en el icono desplegable para mostrar la clave de API de su inquilino
4. Copie y guarde la clave de API de forma segura

Encabezados de autenticación

Todas las solicitudes a la API requieren los siguientes encabezados:

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

Estructura y patrones de la API

Formato de la URL base

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

• URL base: siempre https://api.LogisticaHQ.com (igual para todos los inquilinos)
• : el tipo de recurso (Product, Client, Vendor, PickTicket, PurchaseOrder, etc.)
• : la operación (CreateOrUpdate, DeleteBatch, Execute, etc.)

Endpoints estándar

Cada recurso normalmente admite estas acciones:

Ejemplos de 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

Nota: la identificación del inquilino se realiza mediante la clave de API en el encabezado Authorization, no a través de la URL.

Recursos principales

1. Productos

Crear/actualizar producto

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"
    }
  ]
}

Respuesta

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

2. Órdenes de compra

Crear orden de compra

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. Órdenes de venta (órdenes de salida)

Crear orden de venta

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. Inventario Operaciones

Consultar Inventario actual (reporte FourWall)

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

Respuesta

{
  "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
}

Inventario - Ajuste

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

Crear/actualizar Cliente

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

Crear/actualizar proveedor

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"
}

Ejemplos de integración

Solicitud HTTP básica (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"
  }'

Ejemplo en Python

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")

Ejemplo en JavaScript/Node.js

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
});

Ejemplo en C#

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

Configuración de Webhooks

LogisticaHQ puede enviar notificaciones en tiempo real a sus endpoints cuando ocurren determinados eventos.

Eventos de webhook disponibles

• Eventos de orden: creada, asignada, surtida, empacada, enviada
• Inventario - Eventos: existencias bajas, existencias recibidas, Inventario cíclico completado
• Eventos de orden de compra: recibida, completada
• 3PL - Eventos: factura generada, pago recibido

Ejemplo de carga útil de webhook

{
  "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=..."
}

Validación de seguridad del webhook

Valide siempre las firmas de los webhooks para garantizar su autenticidad:

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
    )

Manejo de errores

Códigos de estado HTTP

Formato de respuesta de error

{
  "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"
}

Estrategia de reintentos

Implemente una espera exponencial para los errores transitorios:

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)

Mejores Prácticas

1. Límite de solicitudes

• Límite predeterminado: 100 solicitudes por minuto
• Implemente colas de solicitudes para operaciones Operaciones
• Use endpoints por lotes cuando estén disponibles

2. Paginación

Para conjuntos de datos grandes, use los parámetros de paginación:

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

3. Filtrado

Use parámetros de consulta para filtrar los resultados:

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

4. Idempotencia

Incluya claves de idempotencia en las operaciones Operaciones:

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

5. Validación de datos

Valide siempre los datos antes de enviarlos:

• Que los campos obligatorios estén presentes
• Que los tipos de datos sean correctos
• Que los valores estén dentro de los rangos aceptables
• Que los SKU e identificadores existan en el sistema

6. Registro

Mantenga registros completos:

• Todas las solicitudes y respuestas de la API
• Detalles de errores y trazas de pila
• Métricas de desempeño
• Recepciones de webhooks

Pruebas

Entorno de pruebas

Pruebe su integración utilizando el entorno de pruebas:

• URL base: https://api.LogisticaHQ.com (igual que Producción)
• Use las claves de API de prueba proporcionadas por separado para acceder al entorno de pruebas
• Los datos se restablecen a diario

Datos de prueba

Use estos SKU de prueba en el entorno de pruebas:

• TEST-001 a TEST-100: producto estándarProductos
• LOT-001: producto rastreado por lote
• SERIAL-001: producto rastreado por número de serie
• EXPIRY-001: producto rastreado por vencimiento

Soporte

Recursos de documentación

• Documentación completa: https://docs.p4.software
• Swagger/OpenAPI: https://api.LogisticaHQ.com/swagger/index.html
• Soporte - Portal: comuníquese con su socio de LogisticaHQ

Cómo obtener ayuda

Al solicitar Soporte, proporcione:

1. El identificador de su inquilino
2. El endpoint de la API que se está llamando
3. La solicitud completa (sin la clave de API)
4. La respuesta recibida
5. La marca de tiempo de la solicitud
6. Cualquier mensaje de error

Apéndice: escenarios de integración comunes

Integración con comercio electrónico

Sincronice las órdenes de su tienda en línea:

1. Reciba el webhook de la orden desde la plataforma de comercio electrónico
2. Crear/actualizar Cliente en LogisticaHQ
3. Cree la orden de salida con los detalles del pedido
4. Supervise el estado de la orden mediante webhooks
5. Actualice el número de rastreo en la plataforma de comercio electrónico al despachar

Integración con ERP

Mantenga la sincronización de datos:

1. Sincronización del maestro de productos (cada hora o diaria)
2. Creación de órdenes en tiempo real
3. Inventario - Actualizaciones de niveles
4. Sincronización de órdenes de compra
5. Exportación de datos financieros para facturación

3PL Operaciones

Gestione operaciones multicliente Operaciones:

1. Catálogos de producto específicos por cliente
2. Seguimiento segregado de Inventario
3. Generación automática de facturación
4. Acceso al portal de clientes mediante la API
5. Reportes personalizados por cliente

Nota: esta documentación cubre la API estándar de LogisticaHQ. Según su nivel de suscripción y los módulos habilitados puede haber endpoints y funciones adicionales. Para la documentación completa, visite https://docs.p4.software