# P4Warehouse REST API

## Overview

P4 Warehouse 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.

{% hint style="info" %}
**Full Documentation**: For complete P4 Warehouse documentation including user guides, configuration, and additional resources, visit `https://docs.p4.software`
{% endhint %}

## Table of Contents

* [API Authentication](#api-authentication)
* [API Structure & Patterns](#api-structure--patterns)
* [Core Resources](#core-resources)
* [Integration Examples](#integration-examples)
* [Webhook Configuration](#webhook-configuration)
* [Error Handling](#error-handling)
* [Best Practices](#best-practices)

***

## API Authentication

### Obtaining Your API Key

{% hint style="danger" %}
**SECURITY**: Never expose your API key in client-side code or public repositories. Store credentials securely using environment variables or secure key management systems.
{% endhint %}

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:

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

***

## API Structure & Patterns

### Base URL Format

```
https://api.p4warehouse.com/{Resource}Api/{Action}
```

* **Base URL**: Always `https://api.p4warehouse.com` (same for all tenants)
* **{Resource}**: The resource type (Product, Client, Vendor, PickTicket, PurchaseOrder, etc.)
* **{Action}**: The operation (CreateOrUpdate, DeleteBatch, Execute, etc.)

### Standard Endpoints

Each resource typically supports these actions:

| Action         | HTTP Method | Description                               |
| -------------- | ----------- | ----------------------------------------- |
| CreateOrUpdate | POST        | Create new or update existing record      |
| DeleteBatch    | POST        | Delete multiple records                   |
| Get            | GET         | Retrieve single record                    |
| List           | GET         | Retrieve multiple records with pagination |
| Execute        | POST        | Execute specific operations               |

### Example Endpoints

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

{% hint style="info" %}
**Note**: The tenant identification is handled through the API key in the Authorization header, not through the URL.
{% endhint %}

***

## Core Resources

### 1. Products

#### Create/Update Product

```http
POST https://api.p4warehouse.com/ProductApi/CreateOrUpdate
```

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

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

### 2. Purchase Orders

#### Create Purchase Order

```http
POST https://api.p4warehouse.com/PurchaseOrderApi/CreateOrUpdate
```

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

```http
POST https://api.p4warehouse.com/PickTicketApi/CreateOrUpdate
```

```json
{
  "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)

```http
GET https://api.p4warehouse.com/FourWallReport/Execute?warehouse_code=WH01
```

#### Response

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

```http
POST https://api.p4warehouse.com/InventoryApi/Adjust
```

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

```http
POST https://api.p4warehouse.com/CustomerApi/CreateOrUpdate
```

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

```http
POST https://api.p4warehouse.com/VendorApi/CreateOrUpdate
```

```json
{
  "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)

```bash
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"
  }'
```

### Python Example

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

### JavaScript/Node.js Example

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

### C# Example

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

***

## Webhook Configuration

P4 Warehouse 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

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

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

| Status Code | Meaning      | Action Required                          |
| ----------- | ------------ | ---------------------------------------- |
| 200         | Success      | None                                     |
| 400         | Bad Request  | Check request format and required fields |
| 401         | Unauthorized | Verify API key                           |
| 403         | Forbidden    | Check permissions for resource           |
| 404         | Not Found    | Verify endpoint URL and resource ID      |
| 429         | Rate Limited | Implement retry with backoff             |
| 500         | Server Error | Contact support if persistent            |

### Error Response Format

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

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

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

### 3. Filtering

Use query parameters to filter results:

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

### 4. Idempotency

Include idempotency keys for critical operations:

```json
{
  "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.p4warehouse.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.p4warehouse.com/swagger/index.html`
* **Support Portal**: Contact your P4 Warehouse 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 P4 Warehouse
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

***

{% hint style="info" %}
**Note**: This documentation covers the standard P4 Warehouse API. Additional endpoints and features may be available based on your subscription level and enabled modules. For complete documentation, visit `https://docs.p4.software`
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.p4.software/p4warehouse-english/rest-api/p4warehouse-rest-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.