Jewellery REST API Integration Specification

This technical manual is organized sequentially into the following eleven architectural sections:

The Perfecto Jewellery Third-Party REST API is a dedicated, production-grade integration service built natively into the Perfecto ERP platform (perfecto-api). It enables Point-of-Sale (POS) systems, custom billing software, enterprise warehouse platforms, and third-party ERP vendors to synchronize jewellery showroom inventory with Perfecto ERP in real time via structured HTTP REST requests.

Core Architectural Guarantees

• Direct System-to-System REST API: Synchronizes stock directly via HTTP POST requests without Excel spreadsheets, CSV parsing, or manual human imports.
• Non-Destructive UPSERT Engine: Uploading new jewellery items or modifying item attributes does NOT delete, wipe, or deactivate unmentioned active showroom stock. Stock remains live until explicitly updated or soft-deactivated.
• Flexible Showroom Counter Scoping: Showroom merchandise in Perfecto ERP can be tracked at the showroom level or allocated to specific display counters (mst_counter_stock). Counter_Id is optional: With Counter_Id → counter-wise stock; Without Counter_Id → outlet-wise stock like before.
• Built-in Idempotency Protection: Every batch upload supports a client-generated Reference_Id. Submitting identical Reference_Id values returns the cached response, preventing accidental duplicate inventory on network retries.
• Strict Multi-Tenant Company & Outlet Isolation: API credentials in rest_perfecto_service_credentials authenticate at the Company level. A single company token operates across all showrooms belonging to that company. Cross-company access is strictly blocked.
• Standard JSON Payload Architecture: All payloads and responses strictly utilize pure application/json. Multipart form-data or encrypted wrapper bodies are unnecessary for third-party operations.

All third-party integration requests must target the verified production gateway. Localhost and developer LAN endpoints must NOT be hardcoded into third-party software.

Authentication & Security Architecture

RestPerfectoService enforces an isolated, enterprise-grade authentication pipeline:

• Isolated Credential Repository: API credentials (Username, Password_Hash, Company_Id, Is_Active) are provisioned by Store Administrators and stored in rest_perfecto_service_credentials at Company level.
• Cryptographic Password Protection: Passwords are protected using 10,000 rounds of PBKDF2 with HMAC-SHA512 and cryptographic per-user salt.
• Stateless Access Tokens: Calling POST /Login returns a cryptographically signed HMAC-SHA256 JSON Web Token (JWT) with a 24-hour TTL. The token is Company-scoped and valid across all authorized company showrooms.
• Mandatory Bearer Authorization: All protected endpoints require the HTTP Authorization header: Authorization: Bearer <ACCESS_TOKEN>.
• Real-Time Revocation Enforcement: On every protected API request, middleware checks the database to confirm Is_Active = 1. If an administrator deactivates the credential, active tokens are revoked immediately with HTTP 401.

Authenticates third-party service credentials and issues a 1-hour JWT Bearer Access Token.

Request Parameters

Example: POST /Login Request Payload

POST /api/v1/RestPerfectoService/Login
Content-Type: application/json

{
  "Username": "surat_jewellers_pos",
  "Password": "XXXXXXXXXXXXXXXXXX"
}

Success Response (HTTP 200 OK)

{
  "status": "1",
  "message": "Login successful.",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjcmVkZW50aWFsSWQiOjEsImNvbXBhbnlJZCI6MSwidXNlcm5hbWUiOiJzdXJhdF9qZXdlbGxlcnNfcG9zIiwidG9rZW5UeXBlIjoiUmVzdFBlcmZlY3RvU2VydmljZSIsImp0aSI6IjgxZjQyZGEzLTExOGItNDRhOC1iMTYxLTU5MDZhMmFlMzM1OCIsImlhdCI6MTc3NDYwMDAwMCwiZXhwIjoxNzc0Njg2NDAwfQ.s...",
    "expires_in": 86400,
    "token_type": "Bearer",
    "company": {
      "Company_Id": 1,
      "Company_Name": "Surat Jewellers Enterprise"
    }
  }
}

Response Fields Description

Error Responses (HTTP 200 / 401)

// Scenario 1: Invalid Credentials
{
  "status": "0",
  "message": "Invalid username or password.",
  "token": "",
  "data": {}
}

// Scenario 2: Inactive Service Account (Is_Active = 0)
{
  "status": "0",
  "message": "RestPerfectoService access is inactive.",
  "token": "",
  "data": {}
}

// Scenario 3: Missing Fields
{
  "status": "0",
  "message": "Username and Password are required.",
  "token": "",
  "data": {}
}

Active outlets of the authenticated company can be retrieved for selecting the target Outlet_Id. External POS, billing, and ERP synchronization systems must query this endpoint to obtain the authorized Outlet_Id values belonging to their enterprise before executing stock uploads or operations.

Request Parameters

Example Request Payloads

POST /api/v1/RestPerfectoService/GetOutlets
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

{}

POST /api/v1/RestPerfectoService/GetOutlets
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

{
  "Outlet_Id": 1
}

Success Response (HTTP 200 OK)

{
  "status": "1",
  "message": "Outlet list fetched successfully",
  "data": [
    {
      "Outlet_Id": 1,
      "Outlet_Name": "Surat Main Showroom",
      "Company_Id": 1,
      "Stock_Type": "JEWELLERY",
      "Email": "surat@pristinejewels.com",
      "Phone": "+91 261 2450001",
      "Mobile": "+91 98250 12345",
      "Address": "Ring Road, Surat",
      "City": "Surat",
      "Pin_Code": "395002",
      "Is_Active": 1
    },
    {
      "Outlet_Id": 2,
      "Outlet_Name": "Ahmedabad Flagship Showroom",
      "Company_Id": 1,
      "Stock_Type": "JEWELLERY",
      "Email": "ahmedabad@pristinejewels.com",
      "Phone": "+91 79 2650002",
      "Mobile": "+91 98250 54321",
      "Address": "CG Road, Navrangpura",
      "City": "Ahmedabad",
      "Pin_Code": "380009",
      "Is_Active": 1
    }
  ]
}

Error Responses (HTTP 200 / 401 / 403)

// Scenario 1: Missing or Invalid Token (HTTP 401)
{
  "status": "0",
  "message": "Access denied. Token missing or invalid."
}

// Scenario 2: Anti-Tampering - Attempting to pass/override Company_Id in Request Body (HTTP 200)
{
  "status": "0",
  "message": "Company_Id and Credential_Id cannot be overridden in request."
}

// Scenario 3: Cross-Company Outlet Access (Selected Outlet does not belong to Company)
{
  "status": "0",
  "message": "Outlet does not belong to your company."
}

In Perfecto ERP, a Counter represents a distinct physical display showcase, sales counter, or jewellery tray inside a showroom (e.g., 'Gold Bangles Showcase', 'Bridal Diamond Counter 01').

Creates a new showroom display counter record in mst_counter_master for a specific company outlet.

Request Parameters (POST /api/admin/v1/AddCounter)

Example: POST /api/admin/v1/AddCounter Request Payload

POST /api/v1/RestPerfectoService/AddCounter
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

{
  "Outlet_Id": 1,
  "Counter_Name": "Gold-Counter-01",
  "Counter_Code": "GC-01"
}

Success Response (HTTP 200 OK)

{
  "status": "1",
  "message": "Counter added successfully.",
  "data": {
    "Counter_Id": 2,
    "Counter_Name": "Gold-Counter-01",
    "Counter_Code": "GC-01",
    "Outlet_Id": 1,
    "Company_Id": 1
  }
}

Company & Outlet Validation Rules

• Tenant Boundary Enforcement: The backend resolves the authenticated operator's Company_Id and Outlet_Id from the session token. Non-superadmin users cannot create counters for other outlets.
• Name Uniqueness Check: The backend executes: SELECT Counter_Id FROM mst_counter_master WHERE Outlet_Id = ? AND Company_Id = ? AND LOWER(Counter_Name) = LOWER(?) LIMIT 1. Attempting to add an existing name in the same outlet is rejected with HTTP 200 / status: 0 ('A counter with this name already exists in this outlet.').
• Counter_Id Generation Behavior: Upon successful insertion, the MariaDB auto-increment primary key (Counter_Id) is generated, Is_Active is set to 1, and the integer is returned in data.Counter_Id.

Error Responses (POST /api/admin/v1/AddCounter)

Enables systems to discover and list showroom display counters for an outlet.

Request Parameters (POST /api/admin/v1/OutletCountersList)

Example: POST /api/admin/v1/OutletCountersList Request Payload

POST /api/v1/RestPerfectoService/GetCounters
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

{
  "Outlet_Id": 1
}

Success Response (POST /api/admin/v1/OutletCountersList)

{
  "status": "1",
  "message": "Counters retrieved successfully.",
  "data": {
    "counters": [
      {
        "Counter_Id": 2,
        "Outlet_Id": 1,
        "Counter_Name": "Gold-Counter-01",
        "Counter_Code": "GC-01",
        "Is_Active": 1
      },
      {
        "Counter_Id": 3,
        "Outlet_Id": 1,
        "Counter_Name": "Diamond-Showcase-01",
        "Counter_Code": "DC-01",
        "Is_Active": 1
      }
    ],
    "total_records": 2
  }
}

Third-Party Live Counter Discovery (POST /Reports/StockCount)

Third-party POS and ERP clients calling the RestPerfectoService gateway can discover all active display counters and their live jewellery counts without admin credentials by calling POST /Reports/StockCount with their third-party Bearer token:

POST /api/v1/RestPerfectoService/Reports/StockCount
Authorization: Bearer <THIRD_PARTY_BEARER_TOKEN>
Content-Type: application/json

{
  "Stock_Type": "JEWELLERY"
}

// Response returns all active counters for the authenticated showroom:
{
  "status": "1",
  "message": "Live stock count fetched successfully.",
  "data": {
    "Stock_Type": "JEWELLERY",
    "Total_Live_Stock": 1420,
    "Counters": [
      {
        "Counter_Id": 2,
        "Counter_Name": "Gold-Counter-01",
        "Stock_Count": 680
      },
      {
        "Counter_Id": 3,
        "Counter_Name": "Diamond-Showcase-01",
        "Stock_Count": 740
      }
    ]
  }
}

Active / Inactive Counter Behavior & Filtering

• Active Counter Filtering: The query strictly enforces WHERE Is_Active = 1. Deactivated counters are automatically suppressed from showroom POS workflows.
• Tenant Outlet Filtering: The query automatically limits results to the authenticated operator's Company_Id and Outlet_Id. Cross-tenant records are completely invisible.
• Counter_Id Operational Usage: The integer Counter_Id extracted from data.List[].Counter_Id (or data.Counters[].Counter_Id) is the exact identifier required for all stock upload and operation APIs.

In Perfecto ERP, Counter_Id is the authoritative operational anchor linking jewellery SKU stock to showroom topology:

Batch-Level vs. Item-Level Counter Specification

• Batch-Level Specification (Recommended): Include 'Counter_Id': 2 at the top level of the JSON body. All items inside the 'Items' array are automatically assigned to this counter.
• Item-Level Override: Include 'Counter_Id': 3 inside individual item objects in the 'Items' array. Enables a single multi-counter synchronization payload.

Whenever stock is uploaded or modified via RestPerfectoService, the backend executes the resolveAndValidateCounter() engine inside transaction boundaries. The server strictly enforces the following verified validation rules:

The primary production endpoint for synchronizing showroom jewellery inventory. Implements non-destructive UPSERT (Inserts new stock; updates existing stock attributes; preserves unmentioned active showroom items).

Batch-Level Request Parameters

Jewellery Item Fields (inside Items array)

Example: POST /UploadStock Request Payload

POST /api/v1/RestPerfectoService/UploadStock
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

{
  "Outlet_Id": 1,
  "Reference_Id": "POS-SURAT-2026-001",
  "Counter_Id": 2,
  "Stock_Type": "JEWELLERY",
  "Mode": "ADD",
  "Items": [
    {
      "Tag_No": "JWL-RNG-001",
      "Item_Name": "18K Gold Solitaire Ring",
      "Category_Name": "Rings",
      "Gross_Wt": 4.520,
      "Net_Wt": 4.220,
      "Stone_Wt": 0.300,
      "Pcs": 1,
      "Making_Charge": 3500.00,
      "Stone_Amount": 125000.00
    }
  ]
}

Success Response (HTTP 200 OK)

{
  "status": "1",
  "message": "Stock items processed successfully.",
  "data": {
    "upload_reference_id": "POS-SURAT-2026-001",
    "outlet_id": 1,
    "counter_id": 2,
    "total_records_received": 1,
    "inserted_count": 1,
    "updated_count": 0,
    "failed_count": 0,
    "summary": {
      "total_gross_weight": 4.520,
      "total_net_weight": 4.220,
      "total_pieces": 1
    }
  }
}

High-precision granular stock lifecycle engine. Enforces strict schema contracts, explicit operational modes, and granular counter mapping.

Supported Operational Modes

Example: POST /StockOperation (UPDATE Mode) Request Payload

POST /api/v1/RestPerfectoService/StockOperation
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

{
  "Outlet_Id": 1,
  "Operation_Mode": "UPDATE",
  "Counter_Id": 2,
  "Items": [
    {
      "Tag_No": "JWL-RNG-001",
      "Gross_Wt": 4.510,
      "Net_Wt": 4.210,
      "Remarks": "Weight re-adjustment"
    }
  ]
}

Success Response (HTTP 200 OK)

{
  "status": "1",
  "message": "Stock operation executed successfully.",
  "data": {
    "operation_mode": "UPDATE",
    "outlet_id": 1,
    "counter_id": 2,
    "processed_count": 1,
    "failed_count": 0,
    "details": [
      {
        "tag_no": "JWL-RNG-001",
        "status": "SUCCESS",
        "message": "Stock item updated successfully."
      }
    ]
  }
}

Performs safe, transaction-bound soft-deactivation (Is_Active = 0) of all jewellery stock assigned to a specified showroom counter. Does NOT physically delete or purge database records.

Request Parameters (POST /ResetStock)

Example: POST /ResetStock Request Payload

POST /api/v1/RestPerfectoService/ResetStock
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

{
  "Outlet_Id": 1,
  "Counter_Id": 2
}

Success Response (HTTP 200 OK)

{
  "status": "1",
  "message": "Stock reset successfully.",
  "data": {
    "outlet_id": 1,
    "counter_id": 2,
    "archived_stock_count": 1420,
    "cleared_counter_allocations": 1420,
    "execution_timestamp": "2026-09-26 11:30:00"
  }
}

Retrieves historical batch upload logs, processing timestamps, and synchronization metrics for the authenticated showroom.

Request Parameters

Example: POST /Reports/SessionSummary Request Payload

POST /api/v1/RestPerfectoService/Reports/SessionSummary
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

{
  "Outlet_Id": 1,
  "Limit": 10,
  "Page": 1
}

Success Response (HTTP 200 OK)

{
  "status": "1",
  "message": "Session summary report fetched successfully.",
  "token": "",
  "data": {
    "Total_Sessions": 12,
    "Sessions": [
      {
        "Upload_History_Id": 145,
        "Upload_Code": "UPLOAD-20260924-114830-1430",
        "Reference_Id": "POS-SURAT-2026-001",
        "Stock_Type": "JEWELLERY",
        "Operation_Mode": "ADD",
        "Total_Items": 2,
        "Inserted_Items": 2,
        "Updated_Items": 0,
        "Failed_Items": 0,
        "Status": "COMPLETED",
        "Entry_Date": "2026-09-24 11:48:30"
      }
    ]
  }
}

Returns real-time active showroom inventory balances broken down by individual display counter.

Request Parameters

Example: POST /Reports/StockCount Request Payload

POST /api/v1/RestPerfectoService/Reports/StockCount
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

{
  "Outlet_Id": 1,
  "Stock_Type": "JEWELLERY"
}

Success Response (HTTP 200 OK)

{
  "status": "1",
  "message": "Live stock count fetched successfully.",
  "token": "",
  "data": {
    "Stock_Type": "JEWELLERY",
    "Total_Live_Stock": 1420,
    "Counters": [
      {
        "Counter_Id": 2,
        "Counter_Name": "Gold-Counter-01",
        "Stock_Count": 680
      },
      {
        "Counter_Id": 3,
        "Counter_Name": "Diamond-Showcase-01",
        "Stock_Count": 740
      }
    ]
  }
}

Third-party Point-of-Sale (POS) and ERP systems must implement the following standardized 7-step operational lifecycle when communicating with Perfecto ERP:

Architectural Sequence: 7-Step Integration Lifecycle

POS / ERP SYSTEM                                     PERFECTO ERP GATEWAY
│                                                                   │
[1] ├── POST /Login ─────────────────────────────────────────────> │ Issue 24-Hour Company Bearer Token
    │ <── HTTP 200 { token, expires_in: 86400 } ───────────────────┤
│                                                                   │
[2] ├── POST /GetOutlets {} ─────────────────────────────────────> │ Return Active Showrooms List
    │ <── HTTP 200 { outlets: [ { Outlet_Id: 1, ... } ] } ────────┤
│                                                                   │
[3] ├── (Optional) POST /GetCounters { Outlet_Id: 1 } ───────────> │ Return Display Counters
    │ <── HTTP 200 { counters: [ { Counter_Id: 2, ... } ] } ──────┤ (Or Omit for Outlet-wise)
│                                                                   │
[4] ├── POST /UploadStock { Outlet_Id: 1, [Counter_Id], Items } ─> │ Non-Destructive UPSERT
    │ <── HTTP 200 { total_items, inserted_count, summary } ───────┤ (mst_jewellery_stock_master)
│                                                                   │
[5] ├── POST /StockOperation { Outlet_Id: 1, Mode, Items } ──────> │ Granular Operations
    │ <── HTTP 200 { processed_count, details } ───────────────────┤ (SET, ADD, UPDATE, REMOVE)
│                                                                   │
[6] ├── POST /ResetStock { Outlet_Id: 1, [Counter_Id] } ─────────> │ Soft-Reset Inventory
    │ <── HTTP 200 { archived_stock_count } ───────────────────────┤ (Mode: DELETE_ALL)
│                                                                   │
[7] ├── POST /Reports/StockCount { Outlet_Id: 1 } ───────────────> │ Audit Verification
    │ <── HTTP 200 { Total_Live_Stock, Counters } ─────────────────┤ & rest_perfecto_service_audit_logs

RestPerfectoService uses standardized HTTP status codes in conjunction with explicit application status ("1" for success, "0" for rejected) and exact error messages.

All documented APIs and operational constraints have undergone comprehensive automated verification against the Perfecto backend engine. Test cases for Counter Add and Counter List have been verified and documented separately below: