Log in
 

API examples

PHP using SoapClient

Browse the repo on GitHub

Initialisation

<?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')),
));

CreateEntity

<?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

CreateInvoice

<?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_format29.99 1.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

CreatePayment

<?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

CreatePaymentPayPal

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

CreateProject

<?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

EntityOutstandingBalance

<?php
require_once __DIR__ '/includes.php';
$entityOutstandingBalance $client->getEntityOutstandingBalance16'sales' );
print_r$entityOutstandingBalance );

/*
Clearbooks_Soap_1_0_EntityOutstandingBalance Object
(
    [outstanding] => 6578.67
    [overdue] => 6548.68
)
*/

View on GitHub

GetExchangeRate

<?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

ListAccountCodes

<?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

ListBankAccounts

<?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

ListEntities

<?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

ListInvoices

<?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

ListInvoicesAdvanced

<?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 0true$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 ) <= mktime00) ) {
            
$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->invoiceNumber6'0'STR_PAD_LEFT );
        
$gross number_format$invoice->gross);
        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->invoiceNumber6'0'STR_PAD_LEFT );
        
$balance number_format$invoice->balance);
        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->invoiceNumber6'0'STR_PAD_LEFT );
        
$balance number_format$invoice->balance);
        echo 
"Invoice {$number} has an outstanding balance of £{$balance}\n";
    } );
}

/*
Invoice INV000200 has an outstanding balance of £66.89
 */

View on GitHub

ListOutstandingBalances

<?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

UpdateEntity

<?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

VoidInvoice

<?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_format29.99 1.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

VoidPayment

<?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

WriteOff

<?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

includes

<?php
spl_autoload_register
( function( $class ) {
    if ( 
strpos$class'Clearbooks_' ) !== ) {
        return 
false;
    }
    require_once 
__DIR__ '/../src/' str_replace'_''/'$class ) . '.php';
    return 
true;
} );
$client = new \Clearbooks_Soap_1_0'demo' );

View on GitHub

ICB accreditation

Clear Books, accredited by The Institute of Certified Bookkeepers and registered with the Financial Conduct Authority (reg. no. 843585), delivers valued, comprehensive online accounting software for small businesses in the UK.