P4 Software / P4 Warehouse

API REST de P4Warehouse

P4Warehouse REST API

Descripción General

P4 Warehouse proporciona una API REST completa que permite una integración perfecta con sistemas externos, incluidos ERPs, plataformas de comercio electrónico y aplicaciones personalizadas. Esta guía cubre la autenticación, los endpoints de la API y los patrones de integración más comunes.

Documentación Completa: Para la documentación completa de P4 Warehouse, incluidas guías de usuario, configuración y recursos adicionales, visite https://docs.p4.software

Tabla de Contenidos

  • Autenticación de 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 API

Obtención de su Clave de API

SEGURIDAD: Nunca exponga su clave de API en código del lado del cliente o en repositorios públicos. Almacene las credenciales de forma segura utilizando variables de entorno o sistemas de gestión de claves seguras.

  1. Navegue a Setup > System > Users
  2. Haga clic en el usuario 'system' de la lista
  3. Haga clic en el ícono desplegable para revelar la clave de API de su inquilino
  4. Copie y almacene de forma segura la clave de API

Encabezados de Autenticación

Todas las solicitudes de 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 URL Base

https://api.p4warehouse.com/{Resource}Api/{Action}
  • URL Base: Siempre https://api.p4warehouse.com (la misma 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 generalmente admite estas acciones:

Acción Método HTTP Descripción
CreateOrUpdate POST Crear nuevo o actualizar registro existente
DeleteBatch POST Eliminar múltiples registros
Get GET Recuperar un registro único
List GET Recuperar múltiples registros con paginación
Execute POST Ejecutar Operaciones específicas

Endpoints de Ejemplo

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

Nota: La identificación del inquilino se gestiona a través de la clave de API en el encabezado de Autorización, no a través de la URL.

Recursos Principales

1. Productos

Crear/Actualizar Producto

POST https://api.p4warehouse.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.p4warehouse.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 (Pick Tickets)

Crear Orden de Venta

POST https://api.p4warehouse.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

Obtener Inventario Actual (Reporte FourWall)

GET https://api.p4warehouse.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
}

Ajuste de Inventario

POST https://api.p4warehouse.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.p4warehouse.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.p4warehouse.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.p4warehouse.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 P4WarehouseClient:
    def __init__(self, api_key):
        self.base_url = "https://api.p4warehouse.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 = P4WarehouseClient("your-api-key")
Inventory = client.get_inventory("WH01")

Ejemplo en JavaScript/Node.js

const axios = require('axios');

class P4WarehouseClient {
    constructor(apiKey) {
        this.baseURL = 'https://api.p4warehouse.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 P4WarehouseClient('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 P4WarehouseClient
{
    private readonly HttpClient _httpClient;
    private readonly string _baseUrl = "https://api.p4warehouse.com";
    
    public P4WarehouseClient(string apiKey)
    {
        _httpClient = new HttpClient();
        _httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}");
        _httpClient.DefaultRequestHeaders.Add("Accept", "application/json");
    }
    
    public async Task<T> PostAsync<T>(string endpoint, object data)
    {
        var json = JsonConvert.SerializeObject(data);
        var content = new StringContent(json, Encoding.UTF8, "application/json");
        
        var response = await _httpClient.PostAsync($"{_baseUrl}/{endpoint}", content);
        response.EnsureSuccessStatusCode();
        
        var responseJson = await response.Content.ReadAsStringAsync();
        return JsonConvert.DeserializeObject<T>(responseJson);
    }
}

Configuración de Webhooks

P4 Warehouse puede enviar notificaciones en tiempo real a sus endpoints cuando ocurren eventos específicos.

Eventos de Webhook Disponibles

  • Eventos de Orden: Creada, Asignada, Recolectada, Empacada, Enviada
  • Eventos de Inventario: Stock Bajo, Stock Recibido, Conteo Cíclico Completado
  • Eventos de Orden de Compra: Recibida, Completada
  • Eventos de 3PL: Factura Generada, Pago Recibido

Ejemplo de Payload 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 de Webhooks

Siempre valide 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

Código de Estado Significado Acción Requerida
200 Éxito Ninguna
400 Solicitud Incorrecta Verifique el formato de la solicitud y los campos requeridos
401 No Autorizado Verifique la clave de API
403 Prohibido Verifique los permisos para el recurso
404 No Encontrado Verifique la URL del endpoint y el ID del recurso
429 Límite de Solicitudes Alcanzado Implemente reintentos con retroceso exponencial
500 Error del Servidor Contacte al Soporte si persiste

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 retroceso exponencial para 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 masivas
  • Utilice endpoints por lotes cuando estén disponibles

2. Paginación

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

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

3. Filtrado

Utilice parámetros de consulta para filtrar resultados:

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

4. Idempotencia

Incluya claves de idempotencia para Operaciones críticas:

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

5. Validación de Datos

Siempre valide los datos antes de enviarlos:

  • Los campos requeridos están presentes
  • Los tipos de datos son correctos
  • Los valores están dentro de los rangos aceptables
  • Los SKUs e IDs existen en el sistema

6. Registro de Eventos

Mantenga registros completos:

  • Todas las solicitudes y respuestas de la API
  • Detalles de errores y trazas de pila
  • Métricas de rendimiento
  • Recepción de webhooks

Pruebas

Entorno de Pruebas (Sandbox)

Pruebe su integración utilizando el sandbox:

  • URL Base: https://api.p4warehouse.com (la misma que Producción)
  • Utilice claves de API de prueba proporcionadas por separado para el acceso al sandbox
  • Los datos se restablecen diariamente

Datos de Prueba

Utilice estos SKUs de prueba en el sandbox:

  • TEST-001 hasta TEST-100: Productos estándar
  • LOT-001: Producto con seguimiento por lote

Was this page helpful?

Previous Registro de cambios