Skip to content

API Usage Purchase

Jump to bottom
simitben edited this page Apr 10, 2026 · 3 revisions

Purpose

This page explains how third-party systems should call Purchase APIs in SimBiz 6 API V3.

Base URL

  • https://<host>/api/v3

Authentication

All purchase endpoints are protected.

Required headers:

  • Authorization: Bearer <token>
  • x-uid: <uid>

How to get token:

Date-Time Format

  • date_from and date_to: YYYY-MM-DD
  • updated_from and updated_to: YYYY-MM-DD HH:MM:SS

Endpoint Summary

Purchase Invoices

No. Endpoint Method Purpose
1 /api/v3/purchase-invoices GET List purchase invoices
2 /api/v3/purchase-invoices/{id} GET Get purchase invoice by id
3 /api/v3/purchase-invoices POST Create purchase invoice

Payment Vouchers

No. Endpoint Method Purpose
1 /api/v3/payment-vouchers GET List payment vouchers
2 /api/v3/payment-vouchers/{id} GET Get payment voucher by id
3 /api/v3/payment-vouchers POST Create payment voucher
4 /api/v3/payment-vouchers/{documentNo}/void POST Void payment voucher

Document Lookup

No. Endpoint Method Purpose
1 /api/v3/purchase-documents/{type}/{documentNo} GET Lookup purchase document by type+no

1) List Purchase Invoices

Request

GET /api/v3/purchase-invoices

Query Parameters

Parameter Type Required Notes
page int No default 1
per_page int No default 50, max 200
all string No
paginate string No
document_no string No exact document no
document_refno string No exact reference no
document_status string No accepted: D (Draft), CO (Completed), V (Voided)
bpartner_id string No
bpartner_no string No
date_from date No
date_to date No
updated_from datetime No
updated_to datetime No
organization_id/org_id or organization_code/org_code string No org filter

Response Fields

Field Type Notes
data object/array Endpoint payload. See success response example for exact fields.
meta object Standard metadata including timing fields.
  • document_id, document_no, document_date, document_status, document_status_label
  • bpartner_id, bpartner_no, bpartner_name
  • organization_id, organization_code, organization_name
  • currency_code, currency_rate, total_amount, total_tax_amount, total_nett_amount, updated
  • lines[] with line-level location_id/location_code/location_name and tax_id/tax_code/tax_rate

Example cURL

curl -G "https://<host>/api/v3/purchase-invoices" \
  -H "Authorization: Bearer <token>" \
  -H "x-uid: support" \
  --data-urlencode "organization_code=BHH" \
  --data-urlencode "all=1"

Success Response Example

{
  "status": "OK",
  "data": [
    {
      "document_id": "1-1-9001",
      "document_no": "PI000123",
      "document_date": "2026-04-09",
      "document_status": "CO",
      "bpartner_id": "1-1-1",
      "bpartner_no": "BP0001",
      "bpartner_name": "ABC Supplier",
      "organization_id": "1",
      "organization_code": "BHH",
      "organization_name": "BHH",
      "currency_code": "MYR",
      "total_nett_amount": "100.00",
      "updated": "2026-04-09 11:30:00"
    }
  ],
  "meta": {
    "pagination": null,
    "execute_time_ms": 17,
    "request_time": "2026-04-10 14:10:00",
    "response_time": "2026-04-10 14:10:00"
  }
}

2) Get Purchase Invoice by ID

Request

GET /api/v3/purchase-invoices/{id}

Query Parameters

None.

Response Fields

Field Type Notes
data object/array Endpoint payload. See success response example for exact fields.
meta object Standard metadata including timing fields.
  • Header fields from list + updated
  • lines[] detail entries

Example cURL

curl -X GET "https://<host>/api/v3/purchase-invoices/1-1-9001" \
  -H "Authorization: Bearer <token>" \
  -H "x-uid: support"

Success Response Example

{
  "status": "OK",
  "data": {
    "document_id": "1-1-9001",
    "document_no": "PI000123",
    "document_date": "2026-04-09",
    "document_status": "CO",
    "bpartner_id": "1-1-1",
    "bpartner_no": "BP0001",
    "bpartner_name": "ABC Supplier",
    "updated": "2026-04-09 11:30:00",
    "lines": []
  },
  "meta": {
    "execute_time_ms": 10,
    "request_time": "2026-04-10 14:10:00",
    "response_time": "2026-04-10 14:10:00"
  }
}

3) Create Purchase Invoice

Request

POST /api/v3/purchase-invoices

Body is required (JSON).

Body Parameters:

Field Required Accepted Value / Format Notes
headerarr Yes object document header
headerarr.organization_id No valid org id/code
headerarr.organization_code No valid org id/code
headerarr.document_date No YYYY-MM-DD optional
headerarr.document_status No valid status code (D, CO, etc.) optional
headerarr.bpartner_id No valid id/no
headerarr.bpartner_no No valid id/no
headerarr.currency_code No valid currency code optional
linearr Yes array minimum 1 row recommended
linearr[].item_id No valid id/code
linearr[].item_code No valid id/code
linearr[].quantity No decimal string > 0 quantity
linearr[].uom_code No valid UOM code optional
linearr[].unitprice No decimal string >= 0 unit price
linearr[].amount_netttotal No decimal string >= 0 line nett total

Query Parameters

None.

Response Fields

Field Type Notes
data object/array Endpoint payload. See success response example for exact fields.
meta object Standard metadata including timing fields.
  • document_id, document_no, msg, updated

Example cURL

curl -X POST "https://<host>/api/v3/purchase-invoices" \
  -H "Authorization: Bearer <token>" \
  -H "x-uid: support" \
  -H "Content-Type: application/json" \
  -d '{"headerarr":{"organization_code":"BHH","document_date":"2026-04-09","bpartner_no":"BP0001"},"linearr":[{"item_code":"ITEM001","quantity":"1"}]}'

Success Response Example

{
  "status": "OK",
  "data": {
    "document_id": "1-1-9001",
    "document_no": "PI000123",
    "msg": "Document saved successfully",
    "updated": ""
  },
  "meta": {
    "execute_time_ms": 20,
    "request_time": "2026-04-10 14:10:00",
    "response_time": "2026-04-10 14:10:00"
  }
}

4) List Payment Vouchers

Request

GET /api/v3/payment-vouchers

Query Parameters

Same as GET /api/v3/purchase-invoices.

Response Fields

Field Type Notes
data object/array Endpoint payload. See success response example for exact fields.
meta object Standard metadata including timing fields.
  • Same as purchase invoice list fields.
  • Includes lines[] with line-level location_id/location_code/location_name and tax_id/tax_code/tax_rate.

Example cURL

curl -G "https://<host>/api/v3/payment-vouchers" \
  -H "Authorization: Bearer <token>" \
  -H "x-uid: support" \
  --data-urlencode "organization_code=BHH"

Success Response Example

{
  "status": "OK",
  "data": [{ "document_id": "1-1-9002", "document_no": "PV000123", "updated": "2026-04-09 12:00:00" }],
  "meta": { "pagination": null, "execute_time_ms": 16, "request_time": "2026-04-10 14:10:00", "response_time": "2026-04-10 14:10:00" }
}

5) Get Payment Voucher by ID

Request

GET /api/v3/payment-vouchers/{id}

Query Parameters

None.

Response Fields

Field Type Notes
data object/array Endpoint payload. See success response example for exact fields.
meta object Standard metadata including timing fields.
  • Header fields from list + updated
  • lines[] detail entries

Example cURL

curl -X GET "https://<host>/api/v3/payment-vouchers/1-1-9002" \
  -H "Authorization: Bearer <token>" \
  -H "x-uid: support"

Success Response Example

{
  "status": "OK",
  "data": {
    "document_id": "1-1-9002",
    "document_no": "PV000123",
    "document_date": "2026-04-09",
    "document_status": "CO",
    "bpartner_id": "1-1-1",
    "bpartner_no": "BP0001",
    "bpartner_name": "ABC Supplier",
    "updated": "2026-04-09 12:00:00",
    "lines": []
  },
  "meta": {
    "execute_time_ms": 10,
    "request_time": "2026-04-10 14:10:00",
    "response_time": "2026-04-10 14:10:00"
  }
}

6) Create Payment Voucher

Request

POST /api/v3/payment-vouchers

Body is required (JSON).

Body Parameters:

Field Required Accepted Value / Format Notes
headerarr Yes object same accepted values as Purchase Invoice create
linearr Yes array same accepted values as Purchase Invoice create

Query Parameters

None.

Response Fields

Field Type Notes
data object/array Endpoint payload. See success response example for exact fields.
meta object Standard metadata including timing fields.
  • document_id, document_no, msg, updated

Example cURL

curl -X POST "https://<host>/api/v3/payment-vouchers" \
  -H "Authorization: Bearer <token>" \
  -H "x-uid: support" \
  -H "Content-Type: application/json" \
  -d '{"headerarr":{"organization_code":"BHH","document_date":"2026-04-09","bpartner_no":"BP0001"},"linearr":[{"item_code":"ITEM001","quantity":"1"}]}'

Success Response Example

{
  "status": "OK",
  "data": {
    "document_id": "1-1-9002",
    "document_no": "PV000123",
    "msg": "Document saved successfully",
    "updated": ""
  },
  "meta": {
    "execute_time_ms": 20,
    "request_time": "2026-04-10 14:10:00",
    "response_time": "2026-04-10 14:10:00"
  }
}

7) Void Payment Voucher

Request

POST /api/v3/payment-vouchers/{documentNo}/void

Body is supported (JSON).

Body Parameters:

Field Required Accepted Value / Format Notes
organization_id No valid org id/code
organization_code No valid org id/code
document_reason No string void reason/audit note

Query Parameters

None.

Response Fields

Field Type Notes
data object/array Endpoint payload. See success response example for exact fields.
meta object Standard metadata including timing fields.
  • document_id, document_no, msg, updated

Example cURL

curl -X POST "https://<host>/api/v3/payment-vouchers/PV000123/void" \
  -H "Authorization: Bearer <token>" \
  -H "x-uid: support" \
  -H "Content-Type: application/json" \
  -d '{"organization_code":"BHH","document_reason":"Void by finance review"}'

Success Response Example

{
  "status": "OK",
  "data": {
    "document_id": "1-1-9002",
    "document_no": "PV000123",
    "msg": "Document voided successfully",
    "updated": ""
  },
  "meta": {
    "execute_time_ms": 17,
    "request_time": "2026-04-10 14:10:00",
    "response_time": "2026-04-10 14:10:00"
  }
}

8) Purchase Document Lookup by Type + No

Request

GET /api/v3/purchase-documents/{type}/{documentNo}

Query Parameters

None.

Response Fields

Field Type Notes
data object/array Endpoint payload. See success response example for exact fields.
meta object Standard metadata including timing fields.
  • document_id, document_no, document_type, document_date, document_status
  • bpartner_id, bpartner_no, bpartner_name, updated

Example cURL

curl -X GET "https://<host>/api/v3/purchase-documents/PI/PI000123" \
  -H "Authorization: Bearer <token>" \
  -H "x-uid: support"

Success Response Example

{
  "status": "OK",
  "data": {
    "document_id": "1-1-9001",
    "document_no": "PI000123",
    "document_type": "PI",
    "document_date": "2026-04-09",
    "document_status": "CO",
    "bpartner_id": "1-1-1",
    "bpartner_no": "BP0001",
    "bpartner_name": "ABC Supplier",
    "updated": "2026-04-09 11:30:00"
  },
  "meta": {
    "execute_time_ms": 9,
    "request_time": "2026-04-10 14:10:00",
    "response_time": "2026-04-10 14:10:00"
  }
}

Clone this wiki locally