API Documentation

Getting Started

The EZRFID API uses standard HTTP methods and returns JSON responses. All requests require authentication via API key.

1. Get your API key

Generate an API key from your organization settings dashboard.

2. Make a request

Include your API key in the X-API-KEY header with every request.

3. Process response

Handle JSON responses and check status codes for success or errors.

Authentication

All API requests must include your organization's API key in the request header.

Header Authentication

Include the X-API-KEY header with every request

X-API-KEY: your_organization_api_key_here

Keep your API key secure

Never expose your API key in client-side code or public repositories.

API Endpoints

Full Inventory Sync

POST

Replace all existing stock data with a complete inventory snapshot. Can create a new stock taking record or update the latest one.

POST /api/v1/sync/full

Request Headers

X-API-KEY

required

Your organization API key

Content-Type

required

Must be application/json

Request Body Parameters

mode string optional

Operation mode for stock taking.

"create": Always creates a new Stock Taking record.
"update" (default): Updates the latest existing Stock Taking record for the organization. If no existing record is found, a new one is created.

stocks array required

Array of stock items. Each item must include:

code required • string • Unique stock code
rfid required • string • RFID tag identifier
group optional • string • Product category/type (max 255 chars)
location optional • string • Storage location (max 255 chars)
image optional • string • Image URL
soldout optional • string • "YES" or "NO"

mappings object optional

Column mapping configuration. Override defaults if needed.

Default mappings:

• rfid_code_column: "rfid"
• stock_code_column: "code"
• group_column: "group"
• location_column: "location"
• sold_out_column: "soldout"
• image_column: "image"

showing_columns array optional

Array of column names to display in the UI. Defaults to all columns if not specified.

Response

200 OK Success

{
  "success": true,
  "message": "Full sync completed successfully. Created 150 stocks in stock taking code ST-2025-12-01.",
  "data": {
    "stock_count": 150,
    "group_count": 8,
    "original_count": 152,
    "filtered_count": 150
  }
}

401 Unauthorized Missing or invalid API key

{
  "success": false,
  "message": "Invalid API Key."
}

403 Forbidden Subscription limit exceeded

{
  "success": false,
  "message": "The number of stocks in this sync exceeds your plan limit. Please upgrade your subscription."
}

422 Unprocessable Entity Validation failed

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "stocks.0.code": ["The stocks.0.code field is required."],
    "stocks.0.rfid": ["The stocks.0.rfid field is required."]
  }
}

Code Examples

Sample implementations in popular languages

$payload = [
    'mode' => 'update', 
    'stocks' => [
        [
            'code' => 'PROD-001',
            'rfid' => 'E200001234567890',
            'group' => 'Electronics',
            'location' => 'Warehouse-A',
            'image' => 'https://example.com/image1.jpg',
            'soldout' => 'NO'
        ],
        [
            'code' => 'PROD-002',
            'rfid' => 'E200001234567891',
            'group' => 'Electronics',
            'location' => 'Warehouse-B',
            'soldout' => 'YES'
        ]
    ],
    'showing_columns' => ['code', 'rfid', 'group', 'location', 'soldout'],
    'mappings' => [
        'rfid_code_column' => 'rfid',
        'stock_code_column' => 'code',
        'group_column' => 'group',
        'location_column' => 'location',
        'sold_out_column' => 'soldout',
        'image_column' => 'image'
    ]
];

$response = Http::withHeaders([
    'Content-Type' => 'application/json',
    'X-API-KEY' => 'your_api_key_here'
])
->timeout(120)
->post('https://ezrfid-7h9k5z4u.on-forge.com/api/v1/sync/full', $payload);

if ($response->successful()) {

    $data = $response->json();

    echo "Sync successful! " . $data['message'];

} else {

    echo "Error: " . $response->body();

}

curl -X POST https://ezrfid-7h9k5z4u.on-forge.com/api/v1/sync/full \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -d '{
    "mode": "update",
    "stocks": [
      {
        "code": "PROD-001",
        "rfid": "E200001234567890",
        "group": "Electronics",
        "location": "Warehouse-A",
        "image": "https://example.com/image1.jpg",
        "soldout": "NO"
      },
      {
        "code": "PROD-002",
        "rfid": "E200001234567891",
        "group": "Electronics",
        "location": "Warehouse-B",
        "soldout": "YES"
      }
    ],
    "showing_columns": ["code", "rfid", "group", "location", "soldout"],
    "mappings": {
      "rfid_code_column": "rfid",
      "stock_code_column": "code",
      "group_column": "group",
      "location_column": "location",
      "sold_out_column": "soldout",
      "image_column": "image"
    }
  }'

import requests
import json

url = "https://ezrfid-7h9k5z4u.on-forge.com/api/v1/sync/full"

headers = {
    "Content-Type": "application/json",
    "X-API-KEY": "your_api_key_here"
}

payload = {
    "mode": "update",    
    "stocks": [
        {
            "code": "PROD-001",
            "rfid": "E200001234567890",
            "group": "Electronics",
            "location": "Warehouse-A",
            "image": "https://example.com/image1.jpg",
            "soldout": "NO"
        },
        {
            "code": "PROD-002",
            "rfid": "E200001234567891",
            "group": "Electronics",
            "location": "Warehouse-B",
            "soldout": "YES"
        }
    ],
    "showing_columns": ["code", "rfid", "group", "location", "soldout"],
    "mappings": {
        "rfid_code_column": "rfid",
        "stock_code_column": "code",
        "group_column": "group",
        "location_column": "location",
        "sold_out_column": "soldout",
        "image_column": "image"
    }
}

response = requests.post(url, headers=headers, data=json.dumps(payload), timeout=120)

if response.status_code == 200:
    data = response.json()
    print(f"Sync successful! {data['message']}")
else:
    print(f"Error: {response.text}")

const payload = {
  mode: 'update', 
  stocks: [
    {
      code: 'PROD-001',
      rfid: 'E200001234567890',
      group: 'Electronics',
      location: 'Warehouse-A',
      image: 'https://example.com/image1.jpg',
      soldout: 'NO'
    },
    {
      code: 'PROD-002',
      rfid: 'E200001234567891',
      group: 'Electronics',
      location: 'Warehouse-B',
      soldout: 'YES'
    }
  ],
  showing_columns: ['code', 'rfid', 'group', 'location', 'soldout'],
  mappings: {
    rfid_code_column: 'rfid',
    stock_code_column: 'code',
    group_column: 'group',
    location_column: 'location',
    sold_out_column: 'soldout',
    image_column: 'image'
  }
};

fetch('https://ezrfid-7h9k5z4u.on-forge.com/api/v1/sync/full', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'your_api_key_here'
  },
  body: JSON.stringify(payload)
})
.then(response => response.json())
.then(data => {
  if (data.success) {
    console.log(`Sync successful! ${data.message}`);
  } else {
    console.error('Error:', data.message);
  }
})
.catch(error => console.error('Request failed:', error));