API Finance

Finance

Sample PHP code to call Finance methods

You have to create an XML to call a proper method. After creating the request XML you can use such kind of code.

$opts = array(
    'http' => array(
        'method'  => 'POST',
        'header'  => array(
            'Connection: close',
            'Content-Type: text/xml; charset=utf-8',
            'Content-Length: '.strlen($xml)
        ),
        'content' => $xml
    )
);

$context = stream_context_create($opts);
$response = file_get_contents("https://co3app.com/api/finance", false, $context);
echo $response;

Every method will return with an XML response.

Methods for the Finance plugin

getInvoices

Get invoices from a period of time.

Sample request XML:

        <?xml version="1.0" encoding="utf-8"?>
        <command>
            <getInvoices>
                <api_key><![CDATA[put-your-api-key-here]]></api_key>
                <session_key><![CDATA[put-your-session-key-here]]></session_key>
                <date_from>2013-01-01</date_from>
                <date_to>2013-06-12</date_to>
            </getInvoices>
        </command>

getInvoice

Get one invoice by ID. You can read the invoices’ ID with the getInvoices method.

Sample request XML:

        <?xml version="1.0" encoding="utf-8"?>
        <command>
            <getInvoice>
                <api_key><![CDATA[put-your-api-key-here]]></api_key>
                <session_key><![CDATA[put-your-session-key-here]]></session_key>
                <invoice_id>76</invoice_id>
            </getInvoice>
        </command>

setInvoice

Send a new invoice to CO3. You have to specify the header of the invoice first and then you can specify as many item rows as you like.

Values in the header:

crdr : outgoing, received, advance in, advance out
method : transfer, cash, bankcard, cheque, other, c.o.d., direct debit
contact_id : you have to use the CRM API to get the id of the specific contact
currency : supported currenices: USD, GBP, EUR, HUF (if you need other please contact us)
fx_rate : you have to use it if you need it
language : supported locales are hu_HU, en_US, de_DE, pl_PL, es_ES
email : if set an email will be sent with the invoice as a PDF attachement.
storno_id : if you specify a valid invoice id here the invoice will be a storno invoice. You can leave it empty in any other cases.
esignature : 0 or 1. If it is set to 1 an electronic signature will be added to the PDF documentum. It only works when email is set. Default is 0.
proforma : 0 or 1. If it is set to 1 only a proforma invoice will be created. Default is 0.
customer vat type: values can be DOMESTIC, PRIVATE_PERSON, OTHER.

If you need a print out about your invoice you need to do it through the CO3 GUI.

Sample request XML:

        <?xml version="1.0" encoding="utf-8"?>
        <command>
            <setInvoice>
                <api_key><![CDATA[put-your-api-key-here]]></api_key>
                <session_key><![CDATA[put-your-session-key-here]]></session_key>
                <crdr>outgoing</crdr>
                <method>cash</method>
                <issued_date>2013-07-02</issued_date>
                <payment_date>2013-07-02</payment_date>
                <fulfillment_date>2013-07-10</fulfillment_date>
                <selected_account>12345678-12345678-12345678</selected_account>
                <contact_id>1</contact_id>
                <customer_vat_type>OTHER</customer_vat_type>
                <invoice_description><![CDATA[Invoice description]]></invoice_description>
                <central_description><![CDATA[Invoice description 2nd line]]></central_description>
                <currency>HUF</currency>
                <esignature>0</esignature>
                <fx_rate>0</fx_rate>
                <language>hu_HU</language>
                <email><![CDATA[john.doe@gmail.com]]></email>
                <storno_id>15084</storno_id>
                <proforma>0</proforma>
                <issuer_swift>COBADEFF</issuer_swift>
                <issuer_email>accounting@acme.com</issuer_email>
                <issuer_phone>123456789</issuer_phone>
                <items>
                    <item>
                        <name><![CDATA[Apple iPhone]]></name>
                        <unit_price>20000.00</unit_price>
                        <unit><![CDATA[pcs]]></unit>
                        <quantity>1.00</quantity>
                        <vat>27.00</vat>
                        <discount>0</discount>
                        <description><![CDATA[Item description]]></description>
                        <product_id></product_id>
                    </item>
                </items>
            </setInvoice>
        </command>

generateInvoice

Get selected invoice in the selected language in PDF format.

Sample request XML:

        <?xml version="1.0" encoding="utf-8"?>
        <command>
            <generateInvoice>
                <api_key><![CDATA[put-your-api-key-here]]></api_key>
                <session_key><![CDATA[put-your-session-key-here]]></session_key>
                <invoice_id>16030</invoice_id>
                <language>en_US</language>
                <proforma>0</proforma>
            </generateInvoice>
        </command>

getDueCustomers

Get the list of cutomers with due invoices.

Sample request XML:

        <?xml version="1.0" encoding="utf-8"?>
        <command>
            <getDueCustomers>
                <api_key><![CDATA[put-your-api-key-here]]></api_key>
                <session_key><![CDATA[put-your-session-key-here]]></session_key>
            </getDueCustomers>
        </command>

getDueNotification

Get due notification letter for a selected customer in PDF format.

Sample request XML:

        <?xml version="1.0" encoding="utf-8"?>
        <command>
            <getDueNotification>
                <api_key><![CDATA[put-your-api-key-here]]></api_key>
                <session_key><![CDATA[put-your-session-key-here]]></session_key>
                <contact_id><![CDATA[1116]]></contact_id>
                <language>hu_HU</language>
            </getDueNotification>
        </command>

setBalance

Set the balance of the selected invoice.

Sample request XML:

        <?xml version="1.0" encoding="utf-8"?>
        <command>
            <setBalance>
                <api_key><![CDATA[put-your-api-key-here]]></api_key>
                <session_key><![CDATA[put-your-session-key-here]]></session_key>
                <invoice_id><![CDATA[16030]]></invoice_id>
                <amount><![CDATA[1000]]></amount>
            </setBalance>
        </command>