Browse the repo on GitHub
<?php
$clearbooksUrl = 'https://secure.clearbooks.co.uk/';
$client = new SoapClient($clearbooksUrl.'api/accounting/wsdl/');
$client->__setSoapHeaders(array(
new SoapHeader($clearbooksUrl . 'api/accounting/soap/',
'authenticate', array('apiKey' => 'yourApiKey')),
));
<?php
spl_autoload_register( function( $class ) {
if ( strpos( $class, 'Clearbooks_' ) !== 0 ) {
return false;
}
require_once __DIR__ . '/../src/' . str_replace( '_', '/', $class ) . '.php';
return true;
} );
$client = new \Clearbooks_Soap_1_0( 'demo' );
View on GitHub
<?php
require_once __DIR__ . '/includes.php';
// create the entity
$entity = new \Clearbooks_Soap_1_0_Entity();
$entity->address1 = '107 Hammersmith Road';
$entity->address2 = 'West Kensington';
$entity->building = 'Master\'s House';
$entity->company_name = 'Clear Books';
$entity->email = 'no-reply@clearbooks.co.uk';
$entity->postcode = 'W14 0QH';
$entity->town = 'London';
$entity->website = 'http://www.clearbooks.co.uk';
// indicate that the entity is a supplier - an entity must be a customer, supplier or both
$entity->supplier = new \Clearbooks_Soap_1_0_EntityExtra();
$entityId = $client->createEntity( $entity );
print_r( $entityId );
/*
32
*/
View on GitHub
<?php
require_once __DIR__ . '/includes.php';
// create the invoice
$invoice = new \Clearbooks_Soap_1_0_Invoice();
$invoice->creditTerms = 30;
$invoice->dateCreated = date( 'Y-m-d' );
$invoice->dateDue = date( 'Y-m-d', strtotime( '+28 days' ) );
$invoice->description = 'API Test Invoice';
$invoice->entityId = 16;
$invoice->status = 'approved';
$invoice->type = 'sales';
// $invoice->multicurrency = 2; // Optionally create my invoice in Euros
// $invoice->fxrate = 2.00; // Optionally force the exchange rate for the invoice.
// add an item to the invoice
$item = new \Clearbooks_Soap_1_0_Item();
$item->description = 'Line Item #1';
$item->quantity = 1;
$item->type = 1001001;
$item->unitPrice = number_format( 29.99 / 1.2, 2 );
$item->vatRate = '0.2';
$invoice->items[] = $item;
$invoiceReturn = $client->createInvoice( $invoice );
print_r( $invoiceReturn );
/*
Clearbooks_Soap_1_0_InvoiceReturn Object
(
[due] => 29.99
[invoice_id] => 211
[invoice_prefix] => INV
[invoice_number] => 201
)
*/
View on GitHub
<?php
require_once __DIR__ . '/includes.php';
$invoice = new \Clearbooks_Soap_1_0_PaymentInvoice();
$invoice->id = 212;
$invoice->amount = 15.5;
$allocatedToInvoices = [ $invoice ];
// create the payment
$payment = new \Clearbooks_Soap_1_0_Payment();
$payment->amount = 29.99;
$payment->accountingDate = date( 'Y-m-d' );
$payment->bankAccount = 7502001;
$payment->description = 'Invoice Payment';
$payment->entityId = 22;
$payment->invoices = $allocatedToInvoices;
$payment->paymentMethod = 1;
$payment->type = 'sales';
$paymentReturn = $client->createPayment( $payment );
print_r( $paymentReturn );
/*
Clearbooks_Soap_1_0_PaymentReturn Object
(
[payment_id] => 618
)
*/
View on GitHub
<?php
require_once __DIR__ . '/includes.php';
// the paypal bank account
$paypalBankAccount = 7502004;
// the paypal entity id
$paypalEntityId = 12;
// the amount received by paypal
$received = 1150;
// the sales invoice id to apply the payment to
$salesInvoiceId = 189;
// fetch the original invoice
$invoiceQuery = new \Clearbooks_Soap_1_0_InvoiceQuery();
$invoiceQuery->id[] = $salesInvoiceId;
$invoiceQuery->ledger = 'sales';
$invoiceQuery->status = 'approved';
$invoices = $client->listInvoices( $invoiceQuery );
if ( !$invoices ) {
throw new \Exception( 'Invoice not found' );
}
$invoice = $invoices[0];
// calculate the invoice total
$total = 0;
array_walk( $invoice->items, function( $item ) use ( &$total ) {
/** @var $item \Clearbooks_Soap_1_0_item */
$total += $item->unitPrice + $item->vat;
} );
// the paypal fee is the amount received minus the invoice total (1150 - 1200 = -50)
$fee = $received - $total;
// create an invoice for the paypal fee
$invoice = new \Clearbooks_Soap_1_0_Invoice();
$invoice->creditTerms = 0;
$invoice->dateCreated = date( 'Y-m-d' );
$invoice->dateDue = date( 'Y-m-d' );
$invoice->description = 'PayPal Fee';
$invoice->entityId = $paypalEntityId;
$invoice->status = 'approved';
$invoice->type = 'sales';
// add the fee item to the invoice (should be a negative amount)
$item = new \Clearbooks_Soap_1_0_Item();
$item->description = 'PayPal Fee';
$item->quantity = 1;
$item->type = 6001002;
$item->unitPrice = number_format( $fee / 1.2, 2 );
$item->vatRate = '0.2';
$invoice->items[] = $item;
// create the invoice in the api and retrieve the invoice id
$invoiceReturn = $client->createInvoice( $invoice );
$feeInvoiceId = $invoiceReturn->invoice_id;
// create the payment
$payment = new \Clearbooks_Soap_1_0_Payment();
$payment->amount = $received;
$payment->accountingDate = date( 'Y-m-d' );
$payment->bankAccount = $paypalBankAccount;
$payment->description = 'PayPal Payment';
$payment->entityId = $invoice->entityId;
$payment->invoices[] = array( 'id' => $feeInvoiceId );
$payment->invoices[] = array( 'id' => $salesInvoiceId );
$payment->paymentMethod = 21;
$payment->type = 'sales';
$paymentReturn = $client->createPayment( $payment );
print_r( $paymentReturn );
/*
Clearbooks_Soap_1_0_PaymentReturn Object
(
[payment_id] => 620
)
*/
View on GitHub
<?php
require_once __DIR__ . '/includes.php';
// create the project
$project = new \Clearbooks_Soap_1_0_Project();
$project->description = 'Costs related to Search Engine Optimization';
$project->projectName = 'SEO';
$project->status = 'open';
$projectReturn = $client->createProject( $project );
print_r( $projectReturn );
/*
Clearbooks_Soap_1_0_ProjectReturn Object
(
[project_id] => 6
)
*/
View on GitHub
<?php
require_once __DIR__ . '/includes.php';
$entityOutstandingBalance = $client->getEntityOutstandingBalance( 16, 'sales' );
print_r( $entityOutstandingBalance );
/*
Clearbooks_Soap_1_0_EntityOutstandingBalance Object
(
[outstanding] => 6578.67
[overdue] => 6548.68
)
*/
View on GitHub
<?php
require_once __DIR__ . '/includes.php';
// construct the request
$request = new \Clearbooks_Soap_1_0_ExchangeRateRequest();
$request->baseCurrency = 'GBP'; // default
$request->targetCurrency = 'USD';
$request->date = '2012-10-05';
$rate = $client->getExchangeRate( $request );
print_r( $rate );
/*
1.6184948525068
*/
View on GitHub
<?php
require_once __DIR__ . '/includes.php';
// execute the command
$accountCodes = $client->listAccountCodes();
print_r( $accountCodes );
/*
Array
(
[0] => Clearbooks_Soap_1_0_AccountCode Object
(
[id] => 1001001
[account_name] => Revenue
[group_name] => Revenue
[default_vat_rate] =>
[show_sales] => 1
[show_purchases] =>
)
...
)
*/
View on GitHub
<?php
require_once __DIR__ . '/includes.php';
$bankAccounts = $client->listBankAccounts();
print_r( $bankAccounts );
/*
Clearbooks_Soap_1_0_ListBankAccountsReturn Object
(
[bankAccounts] => Array
(
[0] => Clearbooks_Soap_1_0_BankAccountListItem Object
(
[account_type] => 0
[balance] => 38253.83
[bank_name] => HSBC
[currency] => 1
[gl_account_code] => 7502004
[id] => 2
[last_date] => 23 Jul 2010
[total_mc] =>
)
[1] => Clearbooks_Soap_1_0_BankAccountListItem Object
(
[account_type] => 0
[balance] => 18768.89
[bank_name] => Barclays
[currency] => 1
[gl_account_code] => 7502001
[id] => 1
[last_date] => 24 Mar 2011
[total_mc] =>
)
)
[total] => 57022.72
)
*/
View on GitHub
<?php
require_once __DIR__ . '/includes.php';
// construct a query to filter returned invoices
$entityQuery = new \Clearbooks_Soap_1_0_EntityQuery();
$entityQuery->id[] = 8;
$entityQuery->type = 'supplier';
// execute the command
$entities = $client->listEntities( $entityQuery );
print_r( $entities );
/*
Array
(
[0] => Clearbooks_Soap_1_0_Entity Object
(
[supplier] => Clearbooks_Soap_1_0_EntityExtra Object
(
[default_account_code] => 0
[default_vat_rate] => 0.2
[default_credit_terms] => 0
)
[customer] => Clearbooks_Soap_1_0_EntityExtra Object
(
[default_account_code] => 0
[default_vat_rate] => 0.00:Out
[default_credit_terms] => 30
)
[bankAccount] => Clearbooks_Soap_1_0_BankAccount Object
(
[bankName] =>
[name] =>
[sortcode] =>
[accountNumber] =>
)
[id] => 8
[company_name] => Fubra Limited
[contact_name] =>
[address1] => Church Hill
[town] => Aldershot
[county] => Hampshire
[country] => GB
[postcode] => GU12 4RQ
[email] =>
[phone1] =>
[building] => Manor Coach House
[address2] =>
[phone2] =>
[fax] =>
[website] =>
[date_modified] => 2010-09-16 16:34:42
[external_id] => 0
[vat_number] =>
[company_number] =>
[statement_url] => https://secure.clearbooks.co.uk/s/2:333e2ce22db288036ec67ca6056c5a7b
)
)
*/
View on GitHub
<?php
require_once __DIR__ . '/includes.php';
// construct a query to filter returned invoices
$invoiceQuery = new \Clearbooks_Soap_1_0_InvoiceQuery();
$invoiceQuery->id[] = 209;
$invoiceQuery->ledger = 'sales';
// execute the command
$invoices = $client->listInvoices( $invoiceQuery );
print_r( $invoices );
/*
Array
(
[0] => Clearbooks_Soap_1_0_Invoice Object
(
[items] => Array
(
[0] => Clearbooks_Soap_1_0_Item Object
(
[description] => Line Item #1
[unitPrice] => 24.99
[vat] => 5
[quantity] => 1
[type] => 1001001
[vatRate] => 0.2
)
)
[description] => API Test Invoice
[entityId] => 16
[invoice_id] => 209
[invoice_prefix] => INV
[invoiceNumber] => 204
[reference] =>
[dateCreated] => 2012-10-19 00:00:00
[dateDue] => 2012-11-16 00:00:00
[dateAccrual] => 2012-10-19 00:00:00
[creditTerms] => 30
[bankPaymentId] => 0
[project] => 0
[external_id] =>
[status] => approved
[statementPage] => https://secure.clearbooks.co.uk/accounting/sales/invoice_html/?source=statement&type=invoice&c=2&auth=-lHLOCMD8mOPS5qyEjiw2g
[themeId] => 0
[type] => S
[vatTreatment] =>
[multicurrency] => 0
[gross] => 29.99
[net] => 24.99
[vat] => 5
[paid] => 0
[balance] => 29.99
[foreignCurrencyBalance] => 0
)
)
*/
View on GitHub
<?php
require_once __DIR__ . '/includes.php';
// construct a query to filter returned invoices
$invoiceQuery = new \Clearbooks_Soap_1_0_InvoiceQuery();
// find invoices that were created or had a payment applied within the last week
$invoiceQuery->modifiedSince = date( 'Y-m-d', strtotime( '-1 week' ) );
// look in the sales ledger
$invoiceQuery->ledger = 'sales';
// exclude voided invoices
$invoiceQuery->status = 'valid';
$invoices = array();
for ( $i = 0; true; $i += 100 ) {
$invoiceQuery->offset = $i;
// get the next batch of invoices
$batch = $client->listInvoices( $invoiceQuery );
// filter invoices by status
array_walk( $batch, function( $invoice ) use ( &$invoices ) {
/** @var $invoice Clearbooks_Soap_1_0_Invoice */
$status = $invoice->status;
if ( $status == 'approved' && strtotime( $invoice->dateDue ) <= mktime( 0, 0, 0 ) ) {
$status = 'unpaid';
}
$invoices[$status][] = $invoice;
} );
// exit the loop if there are no more invoices to retrieve
if ( count( $batch ) < 100 ) {
break;
}
}
// If you only wanted to retrieve paid invoices,
// $invoiceQuery->status = 'paid';
if ( isset( $invoices['paid'] ) ) {
array_walk( $invoices['paid'], function( $invoice ) {
/** @var $invoice Clearbooks_Soap_1_0_Invoice */
$number = ( $invoice->invoice_prefix ?: 'INV' ) . str_pad( $invoice->invoiceNumber, 6, '0', STR_PAD_LEFT );
$gross = number_format( $invoice->gross, 2 );
echo "Invoice {$number} has been paid £{$gross}\n";
} );
}
/*
Invoice INV000196 has been paid £5,875.00
Invoice INV000197 has been paid £5,875.00
Invoice INV000198 has been paid £11,750.00
*/
if ( isset( $invoices['approved'] ) ) {
array_walk( $invoices['approved'], function( $invoice ) {
/** @var $invoice Clearbooks_Soap_1_0_Invoice */
$number = ( $invoice->invoice_prefix ?: 'INV' ) . str_pad( $invoice->invoiceNumber, 6, '0', STR_PAD_LEFT );
$balance = number_format( $invoice->balance, 2 );
echo "Invoice {$number} has a balance of £{$balance}\n";
} );
}
/*
Invoice INV000199 has a balance of £3,842.25
*/
if ( isset( $invoices['unpaid'] ) ) {
array_walk( $invoices['unpaid'], function( $invoice ) {
/** @var $invoice Clearbooks_Soap_1_0_Invoice */
$number = ( $invoice->invoice_prefix ?: 'INV' ) . str_pad( $invoice->invoiceNumber, 6, '0', STR_PAD_LEFT );
$balance = number_format( $invoice->balance, 2 );
echo "Invoice {$number} has an outstanding balance of £{$balance}\n";
} );
}
/*
Invoice INV000200 has an outstanding balance of £66.89
*/
View on GitHub
<?php
require_once __DIR__ . '/includes.php';
$outstandingBalances = $client->listOutstandingBalances( 'sales' );
print_r( $outstandingBalances );
/*
Array
(
[0] => Clearbooks_Soap_1_0_ListOutstandingBalancesReturn Object
(
[entity] => 16
[balance] => 6608.66
)
[1] => Clearbooks_Soap_1_0_ListOutstandingBalancesReturn Object
(
[entity] => 17
[balance] => 3842.25
)
[2] => Clearbooks_Soap_1_0_ListOutstandingBalancesReturn Object
(
[entity] => 20
[balance] => 2469.91
)
[3] => Clearbooks_Soap_1_0_ListOutstandingBalancesReturn Object
(
[entity] => 18
[balance] => 1982.6
)
[4] => Clearbooks_Soap_1_0_ListOutstandingBalancesReturn Object
(
[entity] => 19
[balance] => 1200
)
[5] => Clearbooks_Soap_1_0_ListOutstandingBalancesReturn Object
(
[entity] => 26
[balance] => 360
)
)
*/
View on GitHub
<?php
require_once __DIR__ . '/includes.php';
$entity = new \Clearbooks_Soap_1_0_Entity();
$entity->company_name = "ClearBooks Api Example";
$entity->supplier = new \Clearbooks_Soap_1_0_EntityExtra();
$entityId = $client->createEntity( $entity );
$entityQuery = new \Clearbooks_Soap_1_0_EntityQuery();
$entityQuery->id = [ $entityId ];
list( $storedEntity ) = $client->listEntities( $entityQuery );
$storedEntity->town = "London";
$storedEntity->bankAccount->bankName = "Bank";
( $storedEntity->bankAccount = null);
$storedEntity->supplier = null;
$client->updateEntity( $storedEntity->id, $storedEntity );
list( $updatedEntity ) = $client->listEntities( $entityQuery );
View on GitHub
<?php
require_once __DIR__ . '/includes.php';
$invoice = new \Clearbooks_Soap_1_0_Invoice();
$invoice->creditTerms = 30;
$invoice->dateCreated = date( 'Y-m-d' );
$invoice->dateDue = date( 'Y-m-d', strtotime( '+28 days' ) );
$invoice->description = 'API Test Invoice';
$invoice->entityId = 33;
$invoice->status = 'approved';
$invoice->type = 'sales';
$invoice->vatTreatment = "DSEU";
// add an item to the invoice
$item = new \Clearbooks_Soap_1_0_Item();
$item->description = 'Line Item #1';
$item->quantity = 3.5;
$item->type = 1001001;
$item->unitPrice = number_format( 29.99 / 1.2, 2 );
$item->vatRate = '0.2';
$invoice->items[] = $item;
$invoiceReturn = $client->createInvoice( $invoice );
print_r( $invoiceReturn );
/*
Clearbooks_Soap_1_0_InvoiceReturn Object
(
[due] => 104.96
[invoice_id] => 45
[invoice_prefix] => INV
[invoice_number] => 29
)
*/
$voidRequest = new Clearbooks_Soap_1_0_InvoiceRef();
$voidRequest->id = $invoiceReturn->invoice_id;
$voidRequest->type = 'sales';
$voidResult = $client->voidInvoice( $voidRequest );
print_r( $voidResult );
/*
Clearbooks_Soap_1_0_ResponseStatus Object
(
[success] => 1
[msg] => Voiding this invoice was successful
)
*/
View on GitHub
<?php
require_once __DIR__ . '/includes.php';
// create the payment
$payment = new \Clearbooks_Soap_1_0_RemovePayment();
$payment->id = 620;
$payment->type = "sales";
$paymentReturn = $client->voidPayment( $payment );
print_r( $paymentReturn );
/*
Clearbooks_Soap_1_0_ResponseStatus Object
(
[success] => 1
[msg] => Voiding this payment was successful
)
*/
View on GitHub
<?php
require_once __DIR__ . '/includes.php';
// create the credit query
$creditQuery = new \Clearbooks_Soap_1_0_CreditQuery();
$creditQuery->accountCode = 7501001;
$creditQuery->dateCreated = date( 'Y-m-d' );
$creditQuery->description = 'Invoice Write Off';
$creditQuery->id = 213;
$creditQuery->ledger = 'sales';
$creditResponseStatus = $client->writeOff( $creditQuery );
print_r( $creditResponseStatus );
/*
Clearbooks_Soap_1_0_CreditResponseStatus Object
(
[id] => 213
[msg] => Credit applied against invoice
)
*/
View on GitHub
Clear Books is proudly registered with the Financial Conduct Authority as an Account Information Services Provider (register no. 843585).