Don't have account? Sign up here.

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 header from a period of time. The return answer will contain the invoice id, invoice number, expense/income, payment method, issued date, payment date, fulfillment date, contact id, customer data, net amount, gross amount, balance, currency, status, NAV status, NAV transaction id.

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 - head and all of the item rows - 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. The custom fields have to be specified on the Finance / Settings / Custom fields before sending. The tag name of the custom fields have to be matched with the name of the custom field.

Values in the header:

  • crdr : can be outgoing, received, advance in, advance out
  • method : can be 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 are USD, GBP, EUR, HUF (if you need other please contact us)
  • fx_rate : you can 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 invoice will be sent 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 document. 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.

IMPORTANT! For Hungarian customers only. The invoice will not be sent to the Hungarian Tax Authority (NAV) with this method. To send the invoice to the NAV, you must call the generateInvoice method immediatelly after this call.

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>

                <custom_fields>
                    <text_example>ABC123456</text_example>
                    <date_example>2022-05-30</date_example>
                    <radiobutton_example>
                        <node>yes</node>
                    </radiobutton_example>
                </custom_fields>

                <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>
                        <deposit>0</deposit> <!-- Indicates that the line is a deposit (1) or not (0) -->
                        <custom_fields> <!-- Item row's custom fields -->
                            <profit_centrum>ZZZ1</profit_centrum>
                        </custom_fields>
                    </item>
                </items>
                <retentions>
                    <retention>
                        <name>Jóteljesítési Visszatartás</name>
                        <amount>110.8200</amount>
                        <due_date>2022-01-22</due_date>
                        <note/>
                        <type>2</type>
                        <vat>27.00</vat>
                    </retention>
                </retentions>                 
            </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>

getAttachment

Gives back one of the invoice's attached file based on the attachement ID.

Sample request XML:

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