The external sales API lets an external point-of-sale or ordering system create invoices (sales) for a customer in PracBill, optionally with a payment attached, and add payments to an existing invoice.
All endpoints are relative to https://billing.pracbill.com.au/api/:tokenid/.... The examples below post to a single endpoint; the request body is an array of sale objects.
POST /:tokenid/externalsales/addPosting this data will create an invoice with the listed products and assign it to the given customer ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
tokenid |
string | Yes | Your API access token. |
cid |
integer | Yes | Customer ID. |
date |
date | Sale date (Y-m-d, or Y-m-d h:i:s). | |
amount |
string | Sale total (PHP example only). | |
products |
array | Products to invoice. | |
products[].pid |
integer | Product ID. | |
products[].price |
string | Unit price. | |
products[].quantity |
integer | Quantity. | |
payments |
object | No | Payment to apply, keyed by payment type (see "Create sale with payment"). |
iid |
integer | No | Existing invoice ID (see "Add payment to invoice"). |
add_payment |
boolean | No | Set to true when adding a payment to an existing invoice. |
Request (PHP)
$payload = array(
array(
'amount' => '1.08',
'cid' => 7034729,
'date' => '2017-08-01',
'products' => array(
array(
'pid' => 12524779,
'price' => '1.08',
'quantity' => 1,
),
),
),
);
Request (jQuery)
var products = {
pid: 12524779,
price: '1.08',
quantity: 1,
}
var postData = {
cid: 7034729,
date: '2017-08-01',
products: products,
}
$.ajax({
url: 'https://portal.xenis.com.au/api/b27e5cb3-ed10-47fb-8737-903f1d8fe2c6/externalsales/add',
data: JSON.stringify(postData),
type: 'POST',
contentType: 'application/json',
success: function( response )
{
console.log(response);
}
});
Response (PHP)
Array
(
[results] => Array
(
[0] => Array
(
[success] => 1
[cid] => 7034729
[iid] => 309727
)
)
[processed] => 1
)
Response (jQuery)
{"results":[{"success":true,"cid":7034729,"iid":309769}],"processed":true}
POST /:tokenid/externalsales/addTo create an invoice with a payment assigned to it, add the payment information into the post array.
The payment type is set as the array key. In this case the payment type is cash.
Request (PHP)
$payload = array(
array(
'amount' => '1.08',
'cid' => 7034729,
'date' => date('Y-m-d h:i:s'),
'products' => array(
array(
'pid' => 12524779,
'price' => '1.08',
'quantity' => 1,
),
),
'payments' => array(
'cash' => array(
'description' => 'This is a test payment',
'amount' => '1.08',
),
),
),
);
Request (jQuery)
var products = [{
pid: 12524779,
price: '1.08',
quantity: 1,
},
{
pid: 12524779,
price: '20',
quantity: 1,
}]
var payments = {
securepay: {
description: 'This is a test payment',
amount: '1.08',
}
}
var postData = {
cid: 7034729,
date: '2017-08-01',
products: products,
payments: payments,
}
$.ajax({
url: 'https://portal.xenis.com.au/api/b27e5cb3-ed10-47fb-8737-903f1d8fe2c6/externalsales/add',
data: JSON.stringify(postData),
type: 'POST',
contentType: 'application/json',
success: function( response )
{
console.log(response);
}
});
Response (PHP)
Array
(
[results] => Array
(
[0] => Array
(
[success] => 1
[cid] => 7034729
[iid] => 309727
[paymentResult] => Array
(
[payment_id] => 310240
[success] => 1
[surcharge] => 0
[message] => Payment Successful
[amount] => 1.08
[balance] =>
)
)
)
[processed] => 1
)
Response (jQuery)
{"results":[{"success":true,"cid":7034729,"iid":309770,"paymentResult":{"payment_id":310286,"success":true,"surcharge":0,"message":"Payment Successful","amount":21.08,"balance":null}}],"processed":true}
POST /:tokenid/externalsales/addAdd a payment to an existing invoice. The iid is a required field.
Important: The
add_paymentvalue must be set to true. Without this the sale's product list will be cleared.
Request (PHP)
$payload = array(
array(
'cid' => 7034729,
'date' => '2017-08-01',
'iid' => 309727,
'add_payment' => true,
'payments' => array(
'cash' => array(
'description' => 'This is a an example payment',
'amount' => '1.08',
),
),
),
);
Request (jQuery)
var payments = {
securepay: {
description: 'This is a test payment',
amount: '20',
}
}
var postData = {
iid: 309773,
cid: 7034729,
date: '2017-08-01',
add_payment: true,
payments: payments,
}
$.ajax({
url: 'https://portal.xenis.com.au/api/b27e5cb3-ed10-47fb-8737-903f1d8fe2c6/externalsales/add',
data: JSON.stringify(postData),
type: 'POST',
contentType: 'application/json',
success: function( response )
{
console.log(response);
}
});
Response (PHP)
Array
(
[results] => Array
(
[0] => Array
(
[success] => 1
[cid] => 7034729
[iid] => 309727
[paymentResult] => Array
(
[payment_id] => 310240
[success] => 1
[surcharge] => 0
[message] => Payment Successful
[amount] => 1.08
[balance] =>
)
)
)
[processed] => 1
)
Response (jQuery)
{"results":[{"success":true,"cid":7034729,"iid":309773,"paymentResult":{"payment_id":310298,"success":true,"surcharge":0,"message":"Transaction successful","amount":"20","balance":null}}],"processed":true}
Here you will find information about how the order data objects work and some examples of some. A key item to understand is that the order data and order workflows are not only dynamic, but can also be altered through the platform, which means that the information provided here may not reflect your exact data, but will guide you on how to find what your order looks like.
Related: Getting started with the API, API overview, Customers API, Invoices API, Credit management API, Price books, pricing and products API.