SKYBIZ API — Sales Module

Sales

The Sales module allows you to retrieve and create sales invoice records in your SKYBIZ account. Supports both read and create operations.

Endpoint: /apiv2/modules/sales.php

Required Permissions: Sales — Read, Sales — Create

Allowed DocTypes: CusInv (Invoice), CS (Cash Sale), CusCN (Credit Note), CusDN (Debit Note)

Read Sales

Retrieves sales invoices created within the given date range. Returns all fields — no field filtering or custom filters are supported for this module.

Base Request Structure

{
  "api_key": "your-api-key",
  "api_secret": "your-api-secret",
  "action": "read",
  "date_from": "YYYY-MM-DD",
  "date_to": "YYYY-MM-DD"
}

Request Parameters

Date Rules

• Format must be YYYY-MM-DD — e.g. "2026-04-01"
• Maximum range is 31 days
• date_from cannot be after date_to

Available Fields (Read Only)

The Sales module returns all fields. Field filtering is not supported for this module.

Example 1 — Get All Sales (All Fields)

This request returns all sales invoice fields for invoices created between April 1, 2026 and April 30, 2026.

Request

{
  "api_key": "your-api-key",
  "api_secret": "your-api-secret",
  "action": "read",
  "date_from": "2026-04-01",
  "date_to": "2026-04-30"
}

Sample Code for making an API READ request using php

<?php
header('Content-Type: application/json');

// ============================================================
// STEP 1: CONFIGURATION
// ============================================================

$API_KEY = "your-api-key";
$API_SECRET = "your-api-secret";
$ACTION = "read";

// Date range (required for all endpoints, max 31 days)
$DATE_FROM = "2026-04-01";
$DATE_TO = "2026-04-30";

// ============================================================
// STEP 2: ENDPOINT
// ============================================================

$BASE_URL = "https://domain-name/01/clientportal/apiv2/modules"; //(replace it with your skybiz domain name url)
$ENDPOINT = "sales.php";

// ============================================================
// STEP 3: REQUEST PARAMETERS
// ============================================================

$requestParams = [
    "date_from" => $DATE_FROM,
    "date_to" => $DATE_TO
];

// ============================================================
// STEP 4: BUILD PAYLOAD
// ============================================================

$payload = array_merge(
    [
        "api_key" => $API_KEY,
        "api_secret" => $API_SECRET,
        "action" => $ACTION
    ],
    $requestParams
);

// ============================================================
// STEP 5: SEND REQUEST
// ============================================================

$url = rtrim($BASE_URL, '/') . '/' . ltrim($ENDPOINT, '/');

$ch = curl_init($url);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query($payload),
    CURLOPT_TIMEOUT => 30,
]);

$response = curl_exec($ch);

// ============================================================
// STEP 6: HANDLE CURL ERROR
// ============================================================

if ($response === false) {
    echo json_encode([
        "status" => "error",
        "timestamp" => date("c"),
        "request_id" => uniqid("req_"),
        "message" => curl_error($ch)
    ], JSON_PRETTY_PRINT);
    curl_close($ch);
    exit;
}

$httpStatus = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

// ============================================================
// STEP 7: DECODE RESPONSE
// ============================================================

$result = json_decode($response, true);

if (!$result) {
    echo json_encode([
        "status" => "error",
        "timestamp" => date("c"),
        "request_id" => uniqid("req_"),
        "message" => "Invalid JSON from API",
        "raw_response" => $response
    ], JSON_PRETTY_PRINT);
    exit;
}

// ============================================================
// STEP 8: RETURN CLEAN JSON FORMAT
// ============================================================

echo json_encode([
    "status" => $result['status'] ?? "error",
    "timestamp" => date("c"),
    "request_id" => $result['request_id'] ?? uniqid("req_"),
    "data" => $result['data'] ?? null,
    "message" => $result['message'] ?? null
], JSON_PRETTY_PRINT);

Response (Success)

{
  "status": "response",
  "timestamp": "2026-04-30T04:07:04+00:00",
  "request_id": "req_69f2d56891e57",
  "data": {
    "requested_by": "your-api-key",
    "mode": "2",
    "date_range": {
      "from": "2026-04-01",
      "to": "2026-04-30",
      "days": 30
    },
    "total_returned": 2,
    "data": [
      {
        "Doc1No": "INV-001",
        "CusCode": "CUST001",
        "DocType": "CusInv",
        "HCNetAmt": 1500.00,
        "HCDtTax": 120.00,
        "D_ate": "2026-04-15",
        "DateTimeModified": "2026-04-15 10:30:00"
      },
      {
        "Doc1No": "INV-002",
        "CusCode": "CUST002",
        "DocType": "CusInv",
        "HCNetAmt": 2500.00,
        "HCDtTax": 200.00,
        "D_ate": "2026-04-20",
        "DateTimeModified": "2026-04-20 14:45:00"
      }
    ]
  }
}

Postman Steps — READ Request

1. Set method to POST

2. Enter URL: https://your-domain/01/clientportal/apiv2/modules/sales.php

3. Set header: Content-Type: application/json

4. Under Body, select raw and format JSON

5. Paste your request payload and click Send

Create Sales Invoice

Creates one or more sales invoice records. All documents are validated before any are saved. If any document fails, the entire batch is rejected.

Compulsory Fields — Header

Compulsory Fields — Items

Optional Fields — Header

Optional Fields — Items

BlankLine Values

Base Create Request Structure

{
  "api_key": "your-api-key",
  "api_secret": "your-api-secret",
  "action": "create",
  "sales_data": {
    "documents": [
      {
        "Doc1No": "INV-001",
        "CusCode": "CUST001",
        "DocType": "CusInv",
        "D_ate": "2026-05-20",
        "HCNetAmt": 550.00,
        "HCDtTax": 44.00,
        "CurCode": "RM",
        "CurRate1": 1,
        "items": [
          {
            "ItemCode": "ITEM001",
            "Description": "Product A",
            "Qty": 10,
            "FactorQty": 1,
            "UOM": "Piece",
            "HCUnitCost": 50.00,
            "HCLineAmt": 500.00,
            "BlankLine": "0",
            "HCTax": 40.00,
            "TaxRate1": 8,
            "LineNo": 1
          }
        ]
      }
    ]
  }
}

Sample Code for making an API CREATE request using php

<?php
header('Content-Type: application/json');

// ============================================================
// STEP 1: CONFIGURATION
// ============================================================

$API_KEY = "your-api-key";
$API_SECRET = "your-api-secret";
$ACTION = "create";

// ============================================================
// STEP 2: ENDPOINT
// ============================================================

$BASE_URL = "https://domain-name/01/clientportal/apiv2/modules"; //(replace it with your skybiz domain name url)
$ENDPOINT = "sales.php";

// ============================================================
// STEP 3: DATA KEY
// ============================================================

$DATA_KEY = "sales_data";

// ============================================================
// STEP 4: BUILD YOUR DOCUMENTS ARRAY
// ============================================================

$DOCUMENTS = [];

// --- Sales example ---
$DOCUMENTS[] = [
    "Doc1No" => "INV-001",
    "CusCode" => "CUST001",
    "DocType" => "CusInv",
    "D_ate" => "2026-05-20",
    "HCNetAmt" => 550.00,
    "HCDtTax" => 44.00,
    "CurCode" => "RM",
    "CurRate1" => 1,
    "items" => [
        [
            "ItemCode" => "ITEM001",
            "Description" => "Product A",
            "Qty" => 10,
            "FactorQty" => 1,
            "UOM" => "Piece",
            "HCUnitCost" => 50.00,
            "HCLineAmt" => 500.00,
            "BlankLine" => "0",
            "HCTax" => 40.00,
            "TaxRate1" => 8,
            "LineNo" => 1
        ]
    ]
];

// ============================================================
// STEP 5: CLIENT-SIDE COUNT CHECK (Please do not modify this)
// ============================================================

$totalDocuments = 0;

foreach ($DOCUMENTS as $document) {
    $totalDocuments++;

    if (empty($document['Doc1No'])) {
        echo json_encode([
            "status" => "REJECTED_BY_CLIENT",
            "timestamp" => date("c"),
            "request_id" => uniqid("req_"),
            "message" => "CLIENT-SIDE REJECTION: Document at position {$totalDocuments} has empty Doc1No",
            "action_required" => "Fix the document before sending to server"
        ], JSON_PRETTY_PRINT);
        exit;
    }
}

if ($totalDocuments > 500) {
    echo json_encode([
        "status" => "REJECTED_BY_CLIENT",
        "timestamp" => date("c"),
        "request_id" => uniqid("req_"),
        "message" => "CLIENT-SIDE REJECTION: You have {$totalDocuments} documents. Maximum is 500.",
        "your_document_count" => $totalDocuments,
        "max_allowed" => 500,
        "action_required" => "Reduce your documents to 500 or less BEFORE sending to server"
    ], JSON_PRETTY_PRINT);
    exit;
}

echo "=== CLIENT-SIDE VALIDATION ===\n";
echo "Looped through all {$totalDocuments} documents one by one\n";
echo "All documents passed client validation\n";
echo "Document count: {$totalDocuments} (max 500)\n";
echo "Sending to server...\n\n";

// ============================================================
// STEP 6: SEND REQUEST
// ============================================================

$url = rtrim($BASE_URL, '/') . '/' . ltrim($ENDPOINT, '/');

$payload = [
    "api_key" => $API_KEY,
    "api_secret" => $API_SECRET,
    "action" => $ACTION,
    $DATA_KEY => ["documents" => $DOCUMENTS]
];

$ch = curl_init($url);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_TIMEOUT => 120,
]);

$response = curl_exec($ch);

// ============================================================
// STEP 7: HANDLE CURL ERROR
// ============================================================

if ($response === false) {
    echo json_encode([
        "status" => "error",
        "timestamp" => date("c"),
        "request_id" => uniqid("req_"),
        "message" => curl_error($ch)
    ], JSON_PRETTY_PRINT);
    curl_close($ch);
    exit;
}

$httpStatus = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

// ============================================================
// STEP 8: DECODE RESPONSE
// ============================================================

$result = json_decode($response, true);

if (!$result) {
    echo json_encode([
        "status" => "error",
        "timestamp" => date("c"),
        "request_id" => uniqid("req_"),
        "message" => "Invalid JSON from API",
        "raw_response" => $response
    ], JSON_PRETTY_PRINT);
    exit;
}

// ============================================================
// STEP 9: RETURN CLEAN JSON FORMAT
// ============================================================

echo "=== SERVER RESPONSE ===\n";
echo json_encode([
    "status" => $result['status'] ?? "error",
    "timestamp" => date("c"),
    "request_id" => $result['request_id'] ?? uniqid("req_"),
    "data" => $result['data'] ?? null,
    "message" => $result['message'] ?? null
], JSON_PRETTY_PRINT);

Response (Success)

{
  "status": "response",
  "timestamp": "2026-05-20T10:30:00+08:00",
  "request_id": "req_69fc0070d83cf",
  "data": {
    "requested_by": "your-api-key",
    "mode": "2",
    "summary": {
      "total_documents": 1,
      "inserted": 1,
      "failed": 0
    },
    "successful_documents": ["INV-001"],
    "failed_documents": [],
    "fail_details": {
      "compulsory_fields_missing": [],
      "duplicate_documents": [],
      "invalid_customers": [],
      "invalid_items": [],
      "invalid_tax_codes": [],
      "invalid_sales_persons": [],
      "invalid_locations": [],
      "invalid_departments": [],
      "invalid_projects": [],
      "invalid_branches": [],
      "invalid_currencies": [],
      "invalid_uoms": [],
      "amount_mismatch": [],
      "validation_errors": []
    }
  }
}

Response (Error — Duplicate Document)

{
  "status": "response",
  "timestamp": "2026-05-20T10:30:00+08:00",
  "request_id": "req_69fc03e446a20",
  "data": {
    "requested_by": "your-api-key",
    "mode": "2",
    "summary": {
      "total_documents": 1,
      "inserted": 0,
      "failed": 1
    },
    "successful_documents": [],
    "failed_documents": ["INV-001"],
    "fail_details": {
      "duplicate_documents": ["INV-001"],
      "invalid_currencies": [],
      "invalid_uoms": [],
      "amount_mismatch": [],
      "validation_errors": {}
    }
  }
}

Error Responses

Missing Date Range (READ)

{
  "status": "error",
  "timestamp": "2026-04-07T10:46:15+08:00",
  "request_id": "req_6612f3b9c21a7",
  "message": "date_from and date_to are required"
}

Invalid Date Format

{
  "status": "error",
  "timestamp": "2026-04-07T10:46:15+08:00",
  "request_id": "req_6612f3b9c21a7",
  "message": "Invalid date format. Use YYYY-MM-DD format."
}

Date Range Exceeds 31 Days

{
  "status": "error",
  "timestamp": "2026-04-07T10:46:15+08:00",
  "request_id": "req_6612f3b9c21a7",
  "message": "Date range cannot exceed 31 days."
}

Invalid DocType (CREATE)

{
  "status": "error",
  "timestamp": "2026-04-07T10:46:15+08:00",
  "request_id": "req_6612f3b9c21a7",
  "message": "Invalid DocType 'XXX'. Allowed: CusInv, CS, CusCN, CusDN"
}

Missing Compulsory Fields (CREATE)

{
  "status": "response",
  "timestamp": "2026-05-20T10:30:00+08:00",
  "request_id": "req_123456",
  "data": {
    "summary": {
      "total_documents": 1,
      "inserted": 0,
      "failed": 1
    },
    "failed_documents": ["INV-001"],
    "fail_details": {
      "compulsory_fields_missing": [
        "Document 1 (Doc1No: INV-001): Missing header fields - CusCode, HCNetAmt, HCDtTax, DocType"
      ]
    }
  }
}

Invalid Customer Code (CREATE)

{
  "status": "response",
  "timestamp": "2026-05-20T10:30:00+08:00",
  "request_id": "req_123456",
  "data": {
    "summary": {
      "total_documents": 1,
      "inserted": 0,
      "failed": 1
    },
    "failed_documents": ["INV-001"],
    "fail_details": {
      "invalid_customers": [
        {
          "customer_code": "INVALID",
          "document_no": "INV-001",
          "error": "Customer Code 'INVALID' does not exist"
        }
      ]
    }
  }
}

Invalid Item Code (CREATE)

{
  "status": "response",
  "timestamp": "2026-05-20T10:30:00+08:00",
  "request_id": "req_123456",
  "data": {
    "summary": {
      "total_documents": 1,
      "inserted": 0,
      "failed": 1
    },
    "failed_documents": ["INV-001"],
    "fail_details": {
      "invalid_items": [
        {
          "item_code": "INVALID",
          "document_no": "INV-001",
          "line_no": 1,
          "blank_line_type": "0 (Stock Item)"
        }
      ]
    }
  }
}

Invalid UOM Code (CREATE)

{
  "status": "response",
  "timestamp": "2026-05-20T10:30:00+08:00",
  "request_id": "req_123456",
  "data": {
    "summary": {
      "total_documents": 1,
      "inserted": 0,
      "failed": 1
    },
    "failed_documents": ["INV-001"],
    "fail_details": {
      "invalid_uoms": [
        {
          "uom_code": "INVALID",
          "document_no": "INV-001",
          "line_no": 1,
          "error": "UOM code 'INVALID' does not exist"
        }
      ]
    }
  }
}

Invalid Currency Code (CREATE)

{
  "status": "response",
  "timestamp": "2026-05-20T10:30:00+08:00",
  "request_id": "req_123456",
  "data": {
    "summary": {
      "total_documents": 1,
      "inserted": 0,
      "failed": 1
    },
    "failed_documents": ["INV-001"],
    "fail_details": {
      "invalid_currencies": [
        "Document 1 (Doc1No: INV-001): Currency code 'INVALID' does not exist"
      ]
    }
  }
}

Amount Mismatch — Line Level (CREATE)

{
  "status": "response",
  "timestamp": "2026-05-20T10:30:00+08:00",
  "request_id": "req_123456",
  "data": {
    "summary": {
      "total_documents": 1,
      "inserted": 0,
      "failed": 1
    },
    "failed_documents": ["INV-001"],
    "fail_details": {
      "amount_mismatch": {
        "INV-001": [
          {
            "line_no": 1,
            "item_code": "ITEM001",
            "provided_hclineamt": "100.00",
            "expected_hclineamt": "500.00",
            "error": "HCLineAmt does not match Qty × HCUnitCost"
          }
        ]
      }
    }
  }
}

Amount Mismatch — Header Level (CREATE)

{
  "status": "response",
  "timestamp": "2026-05-20T10:30:00+08:00",
  "request_id": "req_123456",
  "data": {
    "summary": {
      "total_documents": 1,
      "inserted": 0,
      "failed": 1
    },
    "failed_documents": ["INV-001"],
    "fail_details": {
      "amount_mismatch": {
        "INV-001": [
          "Header HCNetAmt (100.00) does not match sum of HCLineAmt (500.00)"
        ]
      }
    }
  }
}

No Read Permission

{
  "status": "error",
  "timestamp": "2026-04-07T10:46:15+08:00",
  "request_id": "req_6612f3b9c21a7",
  "message": "Sales read permission denied"
}

No Create Permission

{
  "status": "error",
  "timestamp": "2026-05-20T10:30:00+08:00",
  "request_id": "req_123456",
  "message": "Sales create permission denied"
}

Common Errors — Sales Module