API examples

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

<?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
)
*/

<?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
)
*/

<?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
)
*/

<?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
)
*/

<?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
)
*/

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

<?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] =>
        )

...

)
*/

<?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
)
*/

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

)
*/

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

)
*/

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

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

)
*/

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

<?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
)
 */

<?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
)
*/

<?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
)
*/

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