For standard guidance to setup the SKYBIZ API, you can refer: SKYBIZ API Setup – Standard

Introduction to SKYBIZ API Setup 

Getting Started

Prerequisites

Before initiating any API interaction, the following conditions must be satisfied:

1. API Integration Mode. API Integration must be set to an active mode by your SKYBIZ administrator via the portal. If API Integration is set to Disabled (Mode 0), all incoming requests — including credential registration — will be automatically rejected. Ensure an active mode is configured prior to proceeding. See Integration Modes for a full description of each mode.

2. Callback URL Availability. A valid and accessible Callback URL is required. The Callback URL must be publicly accessible, fully operational at the time of credential registration, and capable of receiving POST requests. The credential issuance process is dependent on the successful delivery of data to this endpoint.

Integration Mode

The SKYBIZ API operates in one of three modes, controlled by the SKYBIZ administrator. The mode governs security requirements and origin restrictions for all API requests made under that store’s credentials.

The active mode is returned in every successful data response as the mode field, so your integration can verify the mode under which a request was processed.

If a request violates the mode’s rules — for example, a plain HTTP request under Production mode — the API returns 403 Forbidden. Contact your SKYBIZ administrator to change the integration mode.

Credential Registration Workflow

The credential registration process consists of the following steps:

Step 1 : Submit a registration request

Initiate the process by sending a POST request to the registration endpoint with the following parameters:

• • • callback_url — URL publicly accessible HTTPS endpoint
    • store_code — Unique identifier for your store
    • store_main — Primary store indicator

Upon receiving the request, SKYBIZ validates whether API Integration is enabled for the specified store before proceeding.

Step 2 : Credential Generation

If validation is successful, SKYBIZ generates the following credentials:

• • • API Key
      • 25-character alphanumeric string
      • Uniquely identifies your store
    • API Secret
      • 64-character randomly generated string
      • Provided in plain text only at this stage
    • API Renewal Date
      • An expiry date assigned to the credential at the point of registration. See the API Key Renewal Date section below.

Step 3 : Callback Invocation

SKYBIZ sends a POST request to your provided Callback URL with the generated credentials.

Request Payload (JSON body):

{
"api_key": "your-generated-api-key",
"api_secret": "your-generated-api-secret"
}

Request headers:

Content-Type: application/json
X-Timestamp: <unix-timestamp>
X-Signature: <HMAC-SHA256 hash>

Step 4 : Signature Verification

Signature verification is mandatory to ensure request authenticity.

The X-Signature is generated using an HMAC-SHA256 hash computed as follows:

signature = HMAC_SHA256(
key = API Secret,
message = timestamp + "." + raw_json_payload
)

On your Callback endpoint:

1. Reconstruct the signature using the same algorithm and inputs
2. Compare it with the value provided in the X-Signature header

• If the values match → the request is verified and trusted
• If the values do not match → the request must be rejected

Step 5 : Secure Credential Storage. 

Upon successful signature verification, immediately store the following credentials securely:

• API Key
• API Secret

Important:
This is the only instance where the API Secret is available in plain text. SKYBIZ does not retain or provide access to the Secret after this step.

Failure to securely store the Secret will require you to:

• Deactivate the current credential set
• Repeat the registration process

Step 6 : Registration Completion 

SKYBIZ responds with a 200 OK status upon completion, including a callback_status field indicating whether the Callback delivery was successful.

At this point, the credentials are fully activated and ready for use.

⚠ What if my Callback URL fails?

If your Callback URL is unreachable or returns an error, the credentials are still written to the SKYBIZ system but registration does not roll back. The callback_status in the response will reflect the failure. In this case, deactivate the credential set from the portal and re-register with a working Callback URL. Do not attempt to use credentials that were not successfully delivered to your endpoint.

Authentication

Authentication Method

The SKYBIZ API uses a credentials-in-body authentication model. Every request must include the following two fields in the JSON request body:

• api_key — The unique identifier assigned to your store during credential registration
• api_secret — The 64-character secret generated at registration and stored exclusively on your end

Both values must be present in every request. Omitting either field will result in an immediate 400 Bad Request response before any further processing occurs.

How Authentication is Verified Server-Side

Upon receiving a request, the SKYBIZ API performs the following verification sequence:

1. The API Key is used to locate the corresponding record in the system
2. If no matching record is found, a 401 Unauthorized response is returned immediately
3. The renewal date on the credential is checked. If APIRenewalDate is not set, or if today’s date is past the renewal date, a 401 Unauthorized response is returned immediately.
4. If a matching record is found, the provided API Secret is verified against the stored bcrypt hash using password_verify()
5. If the hash comparison fails, a 401 Unauthorized response is returned

Important: Both a missing key and an incorrect secret return the same generic message — "Invalid API credentials" — intentionally. The API does not indicate which of the two values failed, as doing so would provide information useful to an attacker.

The plain-text API Secret is never stored, never logged, and never returned in any API response under any circumstance.

Failed Authentication

API Key Renewal Date

Every API key issued by SKYBIZ carries a renewal date — a fixed expiry date set at the time of credential registration. Once the renewal date has passed, the key is no longer valid and all requests made using it will be rejected immediately, regardless of whether the key and secret are otherwise correct.

The following conditions trigger a 401 response related to the renewal date:

The renewal date is visible in the API Credentials section of the SKYBIZ Portal. Monitor this date proactively — there is a warning when a key is expired. When a key expires, the only resolution is to delete the expired credential set from the portal and register a new one. The existing key cannot be extended or reactivated.

Credential Lifecycle

Deactivating Credentials To revoke access, submit a deactivation request to delete section. This nullifies the API Key, Secret and Callback URL for that credential set. Any subsequent request using the deactivated key will return 401 Unauthorized. Deactivation does not delete the underlying record — the store entry is retained, allowing a fresh credential set to be registered for the same store if needed.

Viewing Module Permissions Module read and create permissions can be viewed at any time via the SKYBIZ portal (Modules button on the credentials table).

Re-registering Credentials If credentials are lost, compromised, or deactivated, re-register by submitting a new registration request. SKYBIZ will detect the existing empty record for the store and update it in place rather than creating a duplicate entry. A new API Key and Secret will be generated and delivered to your Callback URL following the same registration flow described in the Getting Started section.

Security Recommendations

The following practices are strongly advised for all integrations using the SKYBIZ API:

Never expose credentials in client-side code. The API Key and API Secret must only ever exist in server-side code, environment variables, or a dedicated secrets manager. Embedding credentials in frontend JavaScript, mobile application binaries, or any publicly accessible file constitutes a critical security vulnerability.

Use environment variables or a secrets manager. Do not hardcode credentials in your source code or configuration files. Store them as environment variables or use a secrets management solution. This ensures credentials are never inadvertently committed to version control or exposed in build artefacts.

HTTPS is mandatory. The SKYBIZ API rejects all requests that are not made over HTTPS. There are no exceptions and no fallback to HTTP. Ensure your integration enforces HTTPS at the transport layer, not merely as a convention.

Rotate credentials immediately upon suspected compromise. If you have reason to believe your API Key or Secret has been exposed — through a code repository leak, a logged request, an unauthorised access attempt, or any other means — deactivate the credential set immediately via the portal and re-register. Do not delay rotation while investigating the cause.

Scope permissions to the minimum required. Configure module permissions to only what your integration actively needs. A credential set used exclusively for item lookups, for example, should not carry read permissions on the Sales module. Least-privilege access limits the impact of any credential exposure.

Request Format

Standard Request Structure

All SKYBIZ API endpoints accept HTTP POST requests with a Content-Type of application/json. The request body must be a valid JSON object. Requests submitted with any other HTTP method will be rejected with a 405 Method Not Allowed response.+

A standard request takes the following structure:

{
"api_key": "your-api-key",
"api_secret": "your-api-secret",
"action": "read",
"fields": ["CusCode", "CusName", "Email"],
"filters": { "Town": "Kuala Lumpur" },
}

Fields Required on Every Request

Read Request

A read request retrieves records from the specified module filtered by a date range.

Additional required fields for read:

Omitting any of the above will result in a 400 Bad Request response before the request reaches any business logic.

Date rules: format must be YYYY-MM-DD, maximum range is 31 days, and date_from cannot be after date_to.

Optional fields for read:

Controlling Returned Fields

The fields parameter allows you to request only the specific columns your integration requires, rather than receiving the full record for every row. Pass an array of field name strings corresponding to the fields defined for that module.

If fields is omitted or left empty, all available fields for the module will be returned.

"fields": ["CusCode", "CusName", "Email", "Tel"]

Only field names that are recognised and permitted for the requested module will be returned. Any unrecognised field names in the array are silently ignored. If the resulting valid field list is empty after filtering, the API returns a 400 Bad Request response with the message "No valid fields requested". Refer to the individual module reference sections for the complete list of permitted fields per module.

Filtering Results

The filters parameter accepts a JSON object where each key is a field name and each value is the exact value to match against. Filters are applied as exact equality conditions and are combined using AND logic — all specified conditions must be satisfied for a record to be included in the response.

"filters": {
"Town": "Kuala Lumpur"
}

Only fields that belong to the permitted field list of the requested module can be used as filter keys. Filter keys referencing fields outside the permitted list are silently ignored. Filters do not support partial matching, range conditions, or OR logic in the current version.

Create Request

A create request submits new documents into SKYBIZ. Currently supported on the Sales and Purchase modules only. The date_from, date_to, fields, and filters parameters are not used in create requests and should be omitted.

Data Key Reference:

Document limit: A maximum of 500 documents may be submitted per request. If the payload exceeds this, the entire request is rejected before any processing occurs. Split payloads exceeding 500 documents into separate requests.

Create request structure:

{
"api_key": "your-api-key",
"api_secret": "your-api-secret",
"action": "create",
"sales_data": {
"documents": [
{
"Doc1No": "INV-0001",
"CusCode": "C-000001",
"DocType": "CusInv",
"HCNetAmt": 100.00,
"HCDtTax": 9.00,
"items": [
{
"ItemCode": "ITEM001",
"Description": "Product A",
"Qty": 2,
"FactorQty": 1,
"UOM": "PCS",
"HCUnitCost": 50.00,
"HCLineAmt": 100.00,
"BlankLine": "0",
"HCTax": 9.00,
"TaxRate1": 9
}
]
}
]
}
}

For Purchase, replace sales_data with purchase_data.

DocType reference:

BlankLine reference:

Compulsory header fields (both modules):

Compulsory item fields (both modules):

Amount validation rules:

The API enforces the following checks on every submitted document. A mismatch causes the affected document to fail — other valid documents in the same batch are still inserted.

Optional fields:

Reference validation:

The following fields are validated against existing records in SKYBIZ. If the provided value does not exist, the affected document fails and is excluded from the insert — other valid documents in the same batch are unaffected.

Response Format

Overview

Every response returned by the SKYBIZ API — regardless of the endpoint called, the operation performed, or whether the request succeeded or failed — follows a consistent JSON envelope structure.

Response Envelope

Read Success Response

{
"status": "success",
"timestamp": "2026-04-07T10:45:32+08:00",
"request_id": "req_6612f3a7b84c2",
"data": {
"requested_by": "a1b2c3d4e5f6a1b2c3d4e5f67",
"mode": 1,
"date_range": {
"from": "2026-04-01",
"to": "2026-04-07",
"days": 7
},
"total_returned": 2,
"data": [
{
"CusCode": "C001",
"CusName": "Ahmad Trading Sdn Bhd",
"Email": "ahmad@example.com"
}
]
}
}

Data fields in a read success response:

Create Success Response

A successful create request returns a batch summary regardless of whether individual documents passed or failed. The overall status is "success" as long as the request itself was processed — always check summary.failed to determine whether any documents were rejected.

{
"status": "success",
"timestamp": "2026-05-07T10:00:00+08:00",
"request_id": "req_abc123",
"data": {
"requested_by": "your-api-key",
"mode": "2",
"batch_id": "API20260507100000",
"summary": {
"total_documents": 3,
"inserted": 2,
"failed": 1
},
"successful_documents": ["INV-0001", "INV-0002"],
"failed_documents": ["INV-0003"],
"fail_details": {
"compulsory_fields_missing": [],
"duplicate_documents": [],
"invalid_customers": [],
"invalid_suppliers": [],
"invalid_items": [],
"invalid_tax_codes": [],
"invalid_sales_persons": [],
"invalid_locations": [],
"invalid_departments": [],
"invalid_projects": [],
"invalid_branches": [],
"amount_mismatch": {},
"validation_errors": {}
}
}
}

Data fields in a create success response:

fail_details breakdown:

Error Response

{
"status": "error",
"timestamp": "2026-04-07T10:46:15+00:00",
"request_id": "req_6612f3b9c21a7",
"message": "Invalid API credentials"
}

On error responses, the data field is absent entirely. Always check the status field before attempting to access data to avoid null reference errors.

Parsing Recommendation

Structure your response handling in the following order:

1. Check the HTTP status code — a 2xx code does not always guarantee a "success" status in the body
2. Parse the JSON body and read the status field
3. If status is "error", read message and handle accordingly — log the request_id for traceability
4. If status is "success", access the data field to retrieve your payload
5. For create responses, always check data.summary.failed — a "success" status does not mean all documents were inserted

Parsing Recommendation

Structure your response handling in the following order to ensure robust and predictable behaviour across all response types:

1. Check the HTTP status code first — a 2xx code does not always guarantee a "success" status in the body
2. Parse the JSON body and read the status field
3. If status is "error", read message and handle accordingly — log the request_id for traceability
4. If status is "success", access the data field to retrieve your payload
5. For paginated responses, check whether the returned data array length equals your requested limit — if it is less, you have reached the last page

HTTP Status Codes

Overview

The SKYBIZ API uses standard HTTP status codes to communicate the outcome of every request at the transport level. Evaluate the HTTP status code as the first layer of response handling, before parsing the response body.

Status Code Reference

200 — OK

The request was received, authenticated, and processed successfully. The response body will contain a "success" status and, where applicable, a data object.

{
"status": "success",
"timestamp": "2026-04-07T10:45:32+00:00",
"request_id": "req_6612f3a7b84c2",
"data": { ... }
}

A 200 response does not guarantee that records were returned — a valid request against a filtered dataset with no matching records will still return 200 with an empty data array. Evaluate the contents of data separately from the status code.

400 — Bad Request

Bad Request The request was rejected due to missing, invalid, or malformed input. This is a client-side error — the same malformed request will always produce the same 400 response. Do not retry a 400 without first correcting the specific condition identified in the message field.

Common triggers for read:

Common triggers for create:

Do not retry a 400 response without first correcting the request. The same request will produce the same rejection.

401 — Unauthorised

The request could not be authenticated. This occurs when the API Key does not exist in the system, or when the API Secret does not match the stored credential for that key.

{
"status": "error",
"timestamp": "2026-04-07T10:46:15+00:00",
"request_id": "req_6612f3b9c21a7",
"message": "Invalid API credentials"
}

Note that the response message is intentionally identical for both a missing key and an incorrect secret. The API does not indicate which value failed. If you are consistently receiving 401 responses with credentials you believe to be correct, verify that:

• The API Key and Secret are being read from the correct source in your environment
• No leading or trailing whitespace is present in the credential values
• The credential set has not been deactivated from the portal

If the issue persists, deactivate the credential set and re-register to obtain a new key pair.

403 — Forbidden

The request was understood but refused. Unlike 401, a 403 response does not relate to credential validity — your credentials may be perfectly valid, but access is being denied for one of the following reasons:

A 403 related to HTTPS or origin indicates a configuration issue with how your integration is making requests. A 403 related to integration status or module permissions should be directed to your SKYBIZ administrator for resolution.

404 — Not Found

The store identified by the provided store_code and store_main combination does not exist in the system. This typically indicates that either the store identifiers are incorrect, or the store record has not yet been provisioned.

{
"status": "error",
"timestamp": "2026-04-07T10:48:22+00:00",
"request_id": "req_6612f3d1e44b9",
"message": "Store not found"
}

Verify that the store_code and store_main values in your request exactly match those associated with your registered credentials. These values are case-sensitive.

405 — Method Not Allowed

The request was made using an HTTP method other than POST. The SKYBIZ API exclusively accepts POST requests on all endpoints. Submitting a GET, PUT, PATCH, or DELETE request will result in this response.

{
"status": "error",
"timestamp": "2026-04-07T10:49:05+00:00",
"request_id": "req_6612f3e2f55c3",
"message": "Only POST method allowed"
}

Review your HTTP client configuration and ensure the method is explicitly set to POST with a Content-Type of application/json.

500 — Internal Server Error

An unexpected error occurred on the server during the processing of your request. This is not a client-side error and does not indicate a problem with your request structure or credentials.

{
"status": "error",
"timestamp": "2026-04-07T10:51:44+00:00",
"request_id": "req_6612f404h77e5",
"message": "Internal server error"
}

When encountering a 500 response, note the following:

• The error has been automatically logged on the server side with full diagnostic detail
• The request_id in the response is the key reference for investigating the issue
• Retrying the same request may succeed if the error was transient in nature
• If the error persists across multiple retries, contact SKYBIZ support and include the request_id, the endpoint called, and the approximate time of the request

Do not include your API Secret in any support correspondence.

Quick Reference

The two toggles are independent of one another. A credential may be granted read access to a module without create access, or both simultaneously, or neither. A credential with neither permission for a module is treated as having no access to that module at all.

Available Modules

The following modules are currently available in the SKYBIZ API:

Create permissions are active for the Sales and Purchase modules. Customer, Supplier, and Item are read-only in the current version — the create toggle exists in the portal but has no functional effect for these modules at this stage.

Default Permissions at Registration

When a new credential set is registered, no module permissions are configured by default. The module configuration is left empty and must be set up manually via the SKYBIZ portal before the credential can access any data endpoint.

Viewing Permissions

Module permissions are managed through the SKYBIZ portal. No API call is required to view the permission configuration of a credential set.

To access permissions:

1. Navigate to the API Credentials section in the SKYBIZ portal
2. Locate the credential set you wish to view in the credentials table
3. Click the Modules button on the corresponding row
4. The API Module Permissions modal will display the current read and create toggle state for each module that allowed for your store

Behavior When a Permission is Missing

If a request is made to a module for which the credential does not hold the required permission, the API returns a 403 Forbidden response. The specific message in the response body will identify the module and the permission type that was denied.

For example, a request to the Sales module from a credential where the Sales read permission has been disabled will return:

{
"status": "error",
"timestamp": "2026-04-07T11:15:30+00:00",
"request_id": "req_6612f5a2b93c1",
"message": "Sales read permission denied"
}

If you receive a 403 related to module permissions, the resolution is to have your SKYBIZ administrator update the permission configuration for the affected credential set via the portal, as described above. This does not require re-registration or the generation of new credentials.

Module Field Reference

The tables below list every permitted field for each module and a description of the data each field contains.

Customer

Use these field name strings in the fields array when calling the customer module. Omit the fields parameter to return all fields. The date range filters records by DateTimeModified.

Collection

The Collection module returns a fixed set of fields for read requests. The fields and filters parameters have no effect on Collection responses. The date range filters records by the receipt date (D_ate).

Header fields:

Sales Order

The Sales Order module returns a fixed set of fields for read requests. The fields and filters parameters have no effect on Sales Order responses. The date range filters records by the order date (D_ate).

Header fields:

Detail fields:

Code Samples

Overview

The following code samples are provided as working reference implementations to help you get started quickly. Each sample demonstrates a complete, functional request to the SKYBIZ API — authentication, date range, field selection, and response handling.

Before Using These Samples

Ensure the following before running any of the samples below:

• Your credentials have been registered and your Callback URL has successfully received and stored your API Key and Secret, and module permissions have been configured via the SKYBIZ portal
• You are substituting all placeholder values — marked clearly in each sample — with your actual credentials and parameters
• Your environment has network access to the SKYBIZ API endpoint over HTTPS
• You are running these samples server-side only. Never execute API calls containing your credentials from a browser or client-facing environment

PHP — Customer Read Request

The following sample demonstrates a complete read request to the Customer module, returning two specific fields for all matching records.

1. Configuration

Define your API credentials and request action.

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

⚠️ In production, store credentials securely (e.g., environment variables).

2. Date Range

Specify the date from and date to range.

$DATE_FROM = "YYYY-MM-DD";
$DATE_TO = "YYYY-MM-DD";

3. API Endpoint Setup

Specify the base URL and target module.

$BASE_URL = "https://domain-name/01/clientportal/apiv2/modules";
$ENDPOINT = "modules.php";

Available endpoints: customer.php, supplier.php, item.php, sales.php

4. Request Parameters

Define query parameters for date range, specific fields and filters.

$requestParams = [
"date_from" => $DATE_FROM, 
"date_to" => $DATE_FROM, 
"fields" => [] // Leave empty for all fields, or specify like: "["CusCode", "CusName"]
"filters" => [], // Optional filters, e.g.: ["Town" => "Kuala Lumpur"]
];

5. Build Request Payload

Merge required authentication fields with request parameters.

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

6. Send API Request

Initialize and configure the cURL 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);

7. Handle cURL Errors

Check for transport-level errors.

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;
}

8. Process API Response

Retrieve HTTP status and decode response.

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

$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;
}

9. Return Clean JSON Format

Return result in 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);

PHP — Sales Create Request

The following sample demonstrates a complete create request to the Sales module.

1. Configuration

Define your API credentials and request action.

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

⚠️ In production, store credentials securely (e.g., environment variables).

2. Endpoint

Specify the endpoint.

$BASE_URL = "https://domain-name/01/clientportal/apiv2/modules";
$ENDPOINT = "modules.php"; // e.g. sales.php or purchase.php

3. Data Key

Set the data key that matches the module endpoint above.

• sales.php → "sales_data" (DocTypes: CusInv, CS, CusCN, CusDN)
• purchase.php → "purchase_data" (DocTypes: SupInv, SupCN, SupDN)

$DATA_KEY = "sales_data"; // replace to match your endpoint above

4. Build Documents Array

Maximum 500 documents per request. If you have more, split into multiple requests.

$DOCUMENTS = [];

$DOCUMENTS[] = [
"Doc1No" => "INV-0001", // (required) Your document number
"CusCode" => "C-000001", // (required) Customer code (Sales) / Supplier code (Purchase)
"DocType" => "CusInv", // (required) See DocType reference
"HCNetAmt" => 100.00, // (required) Must equal sum of all item HCLineAmt
"HCDtTax" => 9.00, // (required) Must equal sum of all item HCTax
"CurCode" => "MYR", // (optional) Default: MYR
"CurRate1" => 1, // (optional) Default: 1
"items" => [
[
"ItemCode" => "ITEM001", // (required) Must exist in SKYBIZ
"Description" => "Product A", // (required)
"Qty" => 2, // (required) Must be > 0
"FactorQty" => 1, // (required) Must be > 0
"UOM" => "PCS", // (required)
"HCUnitCost" => 50.00, // (required) Must equal HCLineAmt / Qty
"HCLineAmt" => 100.00, // (required) Must equal Qty × HCUnitCost
"BlankLine" => "0", // (required) "0"=Stock, "4"=Other Charge, "6"=GL
"HCTax" => 9.00, // (optional) Must equal HCLineAmt × TaxRate1%
"TaxRate1" => 9, // (optional)
"DetailTaxCode" => "GST9", // (optional) Must exist in SKYBIZ if provided
]
]
];

5. Client-Side Validation

Merge required authentication fields with request parameters.

$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;
}

6. Send API Request

Initialize and configure the cURL 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);

7. Handle cURL Errors

Check for transport-level errors.

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);

8. Process API Response

Retrieve HTTP status and 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;
}

9. Return Clean JSON Format

Return result in 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);

Adapting These Samples

The samples above are written in PHP to align with common server-side integration environments. The underlying logic — constructing a JSON POST body, including credentials and parameters, reading the response envelope, and checking the status field — is transferable directly to any language or HTTP client. The following table maps the key operations to their equivalents in other common environments:

⚠️ Regardless of the language used, the three non-negotiable implementation requirements remain constant — credentials must never be hardcoded in source code, SSL verification must never be disabled in production, and signature verification on your Callback URL must always be performed before trusting or storing any delivered payload.

Audit Logs

Overview

The SKYBIZ API maintains a comprehensive audit log of every authenticated API request processed by the system. This log serves as the authoritative record of all API activity across your store — capturing what was accessed, by which credential, and when. The audit log is available both through the SKYBIZ portal for immediate visibility and programmatically via a dedicated endpoint for integration into your own monitoring or compliance workflows.

What is Logged

Every request that successfully passes authentication generates an audit log entry. The following information is recorded for each entry:

Requests that fail at the authentication stage — such as those with an invalid API Key or incorrect Secret — do not generate an audit log entry, as they do not reach the logging layer. Only requests that pass full authentication and reach the module execution stage are recorded.

Viewing Logs via the Portal

The SKYBIZ portal provides immediate access to audit log entries through the Active API Sessions panel on the API Credentials page.

To access the audit log:

1. Navigate to the API Credentials section in the SKYBIZ portal
2. Scroll down to the Active API Sessions panel below the credentials table
3. The panel displays a paginated table of recent API requests, showing the Requested By, Created timestamp, Doc Type, and Request Action for each entry
4. Use the Prev and Next pagination controls at the bottom of the panel to navigate through the log history

The Active API Sessions badge in the panel header reflects the total number of log entries associated with your store, updating each time the panel is loaded.

Recommendations

Use the audit log to verify integration behaviour during development. During initial integration development and testing, the audit log is a reliable way to confirm that your requests are reaching the API, being authenticated correctly, and accessing the intended modules and fields. Cross-reference your expected request pattern against the log entries to identify any discrepancies early.

Treat RequestedBy as your activity attribution field. Since the RequestedBy field records the API Key for every entry, organisations running multiple credential sets against the same store can attribute activity to specific integrations directly from the log — without needing to maintain a separate activity record on their own systems.

Security & Compliance

Overview

The SKYBIZ API is built with security as a foundational requirement, not an afterthought. Every layer of the system — from credential issuance to request handling to error responses — is designed to minimise exposure of sensitive data and limit the blast radius of any potential credential misuse. This section documents the specific security properties of the API so that your organisation can accurately assess the system against your own security and compliance requirements.

Store-Scoped Credentials

Every API Key issued by the SKYBIZ system is bound to a specific store at the point of registration. A credential set can only access data belonging to the store it was registered against — it is not possible for one credential to retrieve data from a different store, regardless of how the request is constructed.

This means that even in a scenario where a credential is compromised, the scope of accessible data is strictly limited to the single store associated with that credential. There is no elevation path from a store-level credential to broader system access.

API Secret Handling

The API Secret is generated as a 64-character random string at the point of credential registration and is transmitted once — to your Callback URL — at that moment. The following properties govern how the Secret is handled within the SKYBIZ system:

• The plain-text Secret is never written to the database
• The plain-text Secret is never written to any log file
• The plain-text Secret is never returned in any API response, including the registration response itself
• What is stored is a bcrypt hash of the Secret, used exclusively for verification purposes on each incoming request

The practical implication of this design is that the SKYBIZ system has no ability to retrieve or disclose your Secret after the initial registration callback. If your Secret is lost, the only resolution is to deactivate the credential set and re-register to generate a new one. This is by design.

Error Response Sanitisation

All error responses returned by the SKYBIZ API are sanitised before being sent to the client. Internal system errors — including database error messages, query details, server file paths, stack traces, and any other diagnostic information — are never included in the API response body under any circumstance.

When a server-side error occurs, the response returned to you will contain only a generic "Internal server error" message alongside a request_id. The full diagnostic detail is written exclusively to the server-side error log, accessible only to SKYBIZ system administrators. This ensures that your requests — including any that may be intercepted in transit — cannot be used to gain intelligence about the underlying system architecture.

Per-Store Integration Control

API Integration can be enabled or disabled on a per-store basis by your SKYBIZ administrator at any time. When integration is disabled for a store, all incoming API requests associated with that store — including credential registration attempts and data retrieval calls — are rejected immediately with a 403 Forbidden response, regardless of credential validity.

This control provides a single, administrator-managed kill switch for all API activity on a store. In the event of a suspected security incident, a compliance requirement, or a planned maintenance period, disabling integration at the store level immediately halts all external API access without requiring individual credential deactivation.

Credential Deactivation and Record Retention

API Integration can be enabled or disabled on a per-store basis by your SKYBIZ administrator at any time. When integration is disabled for a store, all incoming API requests associated with that store — including credential registration attempts and data retrieval calls — are rejected immediately with a 403 Forbidden response, regardless of credential validity.

This control provides a single, administrator-managed kill switch for all API activity on a store. In the event of a suspected security incident, a compliance requirement, or a planned maintenance period, disabling integration at the store level immediately halts all external API access without requiring individual credential deactivation.

Credential Deactivation and Record Retention

When a credential set is deactivated — either through the portal or via the deactivation endpoint — the following fields are set to null on the associated record:

• API Key
• API Secret (hashed value)
• Callback URL
• Module configuration

The underlying store record itself is retained in the system. It is not deleted. This is intentional for two reasons. First, it preserves audit continuity — historical audit log entries that reference the deactivated credential remain intact and traceable. Second, it allows a new credential set to be registered for the same store by updating the existing record in place, rather than creating a duplicate entry.

Any API request submitted using a deactivated API Key will receive a 401 Unauthorised response. The deactivated key cannot be reactivated — re-registration generates a new key pair entirely.

HTTPS Enforcement

HTTPS is enforced at the application level on all SKYBIZ API endpoints. Any request arriving over plain HTTP is rejected with a 403 Forbidden response. There is no automatic redirect from HTTP to HTTPS — the connection is refused and the request is not processed.

This enforcement applies universally and without exception. Ensure that your HTTP client is configured to use HTTPS explicitly, and that your integration does not fall back to HTTP under any error or timeout condition.

Error Reference

Overview

The following table documents every error message returned by the SKYBIZ API, the HTTP status code accompanying each, the conditions that trigger it, and the recommended action your integration should take in response. Use this reference as the first point of call when diagnosing unexpected API behaviour.

Complete Error Message Reference

Notes on Error Handling

400 errors are deterministic. The same malformed request will always produce the same 400 response. Do not retry a 400 without first correcting the specific condition identified in the message field.

The date format YYYY-MM-DD is strictly enforced. The API no longer accepts YYYY/MM/DD, DD-MM-YYYY, or ISO 8601 date strings. Always use hyphens and the YYYY-MM-DD order.

date_from and date_to are required on all modules. Unlike previous versions where date range was only required for Sales, every module now requires both date fields in every request.

401 and 403 are distinct failure modes. A 401 means your credentials could not be verified. A 403 means your credentials are valid but access is being denied for a mode, policy, or permission reason. The resolution path for each is different — 401 points to credential issues, 403 points to configuration issues that require administrator involvement.

500 errors are logged server-side automatically. You do not need to report every 500 response. However, if a 500 recurs consistently on the same request across multiple attempts, it warrants a support contact with the request_id included.

The message field is your primary diagnostic tool. In all cases, the message field in the response body will contain the specific error string listed in this reference. Build your error handling logic around this field to enable precise, actionable responses to each failure condition rather than handling all non-200 responses generically.

For create requests, a "success" status does not mean all documents were inserted. Always inspect data.summary.failed and data.fail_details in every create response, even when the top-level status is "success".

Per-Store Integration Control

API Integration can be enabled or disabled on a per-store basis by your SKYBIZ administrator at any time. When integration is disabled for a store, all incoming API requests associated with that store — including credential registration attempts, read requests, and create requests — are rejected immediately with a 403 Forbidden response, regardless of credential validity.

This control provides a single, administrator-managed kill switch for all API activity on a store. In the event of a suspected security incident, a compliance requirement, or a planned maintenance period, disabling integration at the store level immediately halts all external API access without requiring individual credential deactivation.

Credential Deactivation and Record Retention

When a credential set is deactivated — either through the portal or via the deactivation endpoint — the following fields are set to null on the associated record:

• API Key
• API Secret (hashed value)
• Callback URL
• Module configuration

The underlying store record itself is retained in the system. It is not deleted. This is intentional for two reasons. First, it preserves audit continuity — historical audit log entries that reference the deactivated credential remain intact and traceable. Second, it allows a new credential set to be registered for the same store by updating the existing record in place, rather than creating a duplicate entry.

Any API request submitted using a deactivated API Key will receive a 401 Unauthorized response. The deactivated key cannot be reactivated — re-registration generates a new key pair entirely.