This API provides core functionality for managing financial transactions within CO3, including invoice creation, retrieval, and balance adjustments. All API calls require an API Key and a Session Key.
You must send a request body formatted as XML, containing a <command> tag with the target method. Or you can send JSON formatted body as well.
// Example using cURL (adjust based on your environment)
$api_url = "https://co3app.com/api/finance";
// The request body must be fully formed XML.
$xml = '<command>
<getInvoices>
<api_key><![CDATA[put-your-api-key-here]]></api_key>
<session_key><![CDATA[put-your-session-key-here]]></session_key>
<date_from>YYYY-MM-DD</date_from>
<date_to>YYYY-MM-DD</date_to>
</getInvoices>
</command>';
$ch = curl_init($api_url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $xml);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: text/xml; charset=utf-8',
'Content-Length: ' . strlen($xml)
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;Every method will return with an XML or JSON response depending on the request format.
Description: Retrieves a list of invoice headers within a specified date range.
Returns: An array containing invoice details (ID, invoice number, total amount, balance, status, etc.).
Parameters:
api_key (string, required): The API Key.session_key (string, required): The active session key.date_from (string, required, date): Start date of the query (YYYY-MM-DD).date_to (string, required, date): End date of the query (YYYY-MM-DD).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>2023-01-01</date_from>
<date_to>2023-12-31</date_to>
</getInvoices>
</command>Sample request JSON:
{
"getInvoices": {
"api_key": "put-your-api-key-here",
"session_key": "put-your-session-key-here",
"date_from": "2023-01-01",
"date_to": "2023-12-31"
}
}Description: Retrieves the full details of a single invoice, including line items.
Returns: An array containing detailed invoice data (items, descriptions, etc.).
Parameters:
api_key (string, required): The API Key.session_key (string, required): The active session key.invoice_id (integer, required): The ID of the invoice to retrieve.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>Sample request JSON:
{
"getInvoice": {
"api_key": "put-your-api-key-here",
"session_key": "put-your-session-key-here",
"invoice_id": 76
}
}Description: Creates an outgoing invoice. This is the most complex call, requiring both header data and item line details. 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.
Returns: Id of the invoice upon successful creation.
Parameters:
crdr (string): Transaction type (outgoing, received, advance in, advance out).method (string): Payment method (transfer, cash, bankcard, cheque, other, c.o.d., direct debit).issued_date (string, date, required): Invoice issuance date (YYYY-MM-DD).payment_date (string, date, required): Expected payment date (YYYY-MM-DD).fulfillment_date (string, date, required): Date of goods/services fulfillment (YYYY-MM-DD).selected_account (string, required): The bank account number for the transaction.contact_id (integer, required): The ID of the associated contact from the CRM API.currency (string, required): Currency code. Supported currencies are USD, GBP, EUR, HUF (if you need other please contact us)fx_rate (number, optional): Foreign exchange rate applied.language (string, optional): Language of the invoice. Supported locales are hu_HU, en_US, de_DE, pl_PL, es_ES.email (string, optional): If set an email invoice will be sent as a PDF attachment.storno_id (integer, optional): If provided, the invoice will be a 'storno' (cancellation) invoice.esignature (integer, optional): 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 (integer, optional): If it is set to 1 a proforma invoice will be created. Default is 0.customer_vat_type (string, required): Values can be DOMESTIC, PRIVATE_PERSON, OTHER.items (array, required): List of invoice items.name (string, required): Name of the item.unit_price (number, required): Price per unit.unit (string, required): Unit of measurement (e.g., pcs).quantity (number, required): Quantity purchased/sold.vat (number, required): VAT percentage/amount.discount (number, required): Discount applied.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>Sample request JSON:
{
"setInvoice": {
"api_key": "put-your-api-key-here",
"session_key": "put-your-session-key-here",
"crdr": "outgoing",
"method": "cash",
"issued_date": "2023-12-01",
"payment_date": "2023-12-01",
"fulfillment_date": "2023-12-10",
"selected_account": "12345678-12345678-12345678",
"contact_id": 1,
"currency": "HUF",
"fx_rate": 0,
"items": [
{
"name": "Apple iPhone",
"unit_price": 20000.00,
"unit": "pcs",
"quantity": 1.00,
"vat": 27.00,
"discount": 0
}
],
"retentions": [
{
"name": "Jóteljesítési Visszatartás",
"amount": 110.8200,
"due_date": "2022-01-22",
"type": 2,
"vat": 27.00
}
]
}
}Description: Generates a PDF copy of a specific invoice, in the selected language in PDF format. Sends the invoice to the Hungarian Tax Authority (NAV).
Returns: The PDF document data as base64 text.
Parameters:
api_key (string, required): The API Key.session_key (string, required): The active session key.invoice_id (integer, required): The ID of the invoice to generate the PDF for.language (string, optional): Desired language for the PDF (e.g., en_US, hu_HU).proforma (integer, optional): If set to 1, generates a Proforma Invoice PDF instead.Sample request XML:
<?xml version="1.0" encoding="utf-8"?>
<command>
<generateInvoicePDF>
<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>
</generateInvoicePDF>
</command>Sample request JSON:
{
"generateInvoicePDF": {
"api_key": "put-your-api-key-here",
"session_key": "put-your-session-key-here",
"invoice_id": 16030,
"language": "en_US",
"proforma": 0
}
}Description: Retrieves a list of customers who have outstanding or overdue invoices.
Returns: An array of customer records with due payment information.
Parameters:
api_key (string, required): The API Key.session_key (string, required): The active session key.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>Sample request JSON:
{
"getDueCustomers": {
"api_key": "put-your-api-key-here",
"session_key": "put-your-session-key-here"
}
}Description: Retrieves a formal due notification letter for a specific customer.
Returns: The notification letter data.
Parameters:
api_key (string, required): The API Key.session_key (string, required): The active session key.contact_id (integer, required): The ID of the contact.language (string, optional): Desired language for the letter (e.g., hu_HU).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>1116</contact_id>
<language>hu_HU</language>
</getDueNotification>
</command>Sample request JSON:
{
"getDueNotification": {
"api_key": "put-your-api-key-here",
"session_key": "put-your-session-key-here",
"contact_id": 1116,
"language": "hu_HU"
}
}Description: Manually adjusts or records the balance payment against a specific invoice.
Returns: Success confirmation or error details.
Parameters:
api_key (string, required): The API Key.session_key (string, required): The active session key.invoice_id (integer, required): The ID of the invoice to update.amount (number, required): The monetary amount of the payment/adjustment.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>16030</invoice_id>
<amount>1000.00</amount>
</setBalance>
</command>Sample request JSON:
{
"setBalance": {
"api_key": "put-your-api-key-here",
"session_key": "put-your-session-key-here",
"invoice_id": 16030,
"amount": 1000.00
}
}Description: Downloads a specific attachment associated with an invoice.
Returns: The file content or a temporary download URL.
Parameters:
api_key (string, required): The API Key.session_key (string, required): The active session key.attachment_id (integer, required): The ID of the attachment file.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>3</attachment_id>
</getAttachment>
</command>Sample request JSON:
{
"getAttachment": {
"api_key": "put-your-api-key-here",
"session_key": "put-your-session-key-here",
"attachment_id": 3
}
}