API documentation

API for sales invoices

This document contains description of a REST interface that allows sending sales invoices to mKsiegowa.pl.

General assumptions

  • Information exchange is based on XML messages.

  • Https protocol is used to ensure security

  • UTF-8 is used for non-ANSI characters

  • Decimal sign used is ‘.’ (dot) for all numbers

  • Both sides of communication use a security key for authentication; the security key should be setup in mKsiegowa and should be used for authentication

  • mKsiegowa records following caller data: IP address, domain

  • An external system sends POST to the below specified address. XML file is sent with the message.

Requirements related to XML file:

  • the file cannot be empty; it contains at list the header

  • file size is less than 10k

In the case of wrong format mKsiegowa.pl replies with an error message.

API setup

Before using API please configure it in Setup module -> API Setup.

Webservice address

https://mksiegowa.pl/interfejsy-programu/method_name 

Example of API call:

curl --form 'xml=@TestXMLaccess.xml' https://mksiegowa.pl/interfejsy-programu/TestXMLAccess

TestXMLAccess method

This method can be used to test access to the program and configuration correctness.

Input:

instance_name - name of mKsiegowa instance. This instance must be registered on mksiegowa.pl website.

instance_key - unique security key. The key should be identical as the one preset in mKsiegowa configuration. 

 Input file example: 

<?xml version="1.0" encoding="UTF-8"?>

-<Envelope>

-<Header>

<method>TestXMLAccess</method>

<instance_name>test</instance_name>

<instance_key>vU8A4UGYmy4YVESYqeSubYNErAWy#A9YzAmE@ySu7Ysu4AhY7Y%U@E8eHapE</instance_key>

</Header>

</Envelope>

Output format:

As an output the following XML structure is sent if all ok:

<Envelope>

<Header>

<return>OK</return>

</Header>

Errors:

<Envelope>

<Body>

<return>Error: error code</return>

</Body>

</Envelope>

Error codes:

  • security key is incorrect: Wrong key!

  • instance does not exist: instance xyz does not exist!

 

WriteSalesInvoices method

This method can be used to send sales invoices to mKsiegowa. If correctly imported, invoices are automatically booked to pre-configured GL accounts.

Input:

instance_name - name of mKsiegowa instance. This instance must be registered on mksiegowa.pl website.

instance_key - unique security key. The key should be identical as the one preset in mKsiegowa configuration. 

invoice - the structure of the Sales invoice. There can be many invoices imported with 1 XML file.

customer - the data of a customer. The customer is identified by VAT number. If not exists, the other fields are used to add the customer to the database.

invoice_header - the invoice must not exist with this number for the customer.

invoice_lines:

  • items specified in item_code section must be available in the item database.
  • name field is used only in invoice print out and is optional
  • vat_rate must be a valid VAT rate in the system (23, 8, 0, zw) and must be the same as setup for the item in mKsiegowa

Input file example: 

<?xml version="1.0" encoding="UTF-8" ?>

<Envelope>

<Header>

<method>WriteSalesInvoices</method>

<instance_name>test</instance_name>

<instance_key>vU8A4UGYmy4YVESYqeSubYNErAWy#A9YzAmE@ySu7Ysu4AhY7Y%U@E8eHapE</instance_key>

</Header>

<invoice>

<customer>

<VAT_number>1234567890</VAT_number>

<name>Sukces sp. z o.o.</name>

<address1>ul. Puławska 1</address1>

<address2>00-000 Warszawa</address2>     

<bank_account>01114020040000000000000000</bank_account>

</customer>

<invoice_header>

<number>FV 1/10/21</number>

<invoice_type>F</invoice_type>

<invoice_date>2021-10-10</invoice_date>

<sales_date>2021-10-01</sales_date>

<due_date>2020-11-15</due_date>

<payment_terms>1</payment_terms>

<pos_id>1</pos_id>

<comment>komentarz</comment>

</invoice_header>

<invoice_lines>

<line_item>

<item_code>2</item_code>

<name>Usługa 8%</name>

<vat_rate>8</vat_rate>

<quantity>1</quantity>

<net_amount>1000</net_amount>

</line_item>

</invoice_lines>

</invoice>

</Envelope>

Output format:

As an output the following XML structure is sent if all ok:

<Envelope>

<Header>

<Authorization>OK</Authorization>

</Header>

<Invoice invoice_number="1">
<Respond>Transaction added FV 1/10/21.</Respond>
<Customer>Customer found in database. VAT nuber: 1234567890, ID: 4</Customer>
</Invoice>

</Envelope>

Customer not found in database

<Invoice invoice_number="1">
<Respond>Transaction added FV 1/10/21.</Respond>
<Customer>Add new customer. VAT nuber: 1234567890, ID: 5</Customer>
</Invoice>

Error - duplicate invoice reference:

<Invoice invoice_number="1">
<Errors>The reference (FV 2/10/21) was used before; document was ignored.</Errors>
<Customer>Customer found in database. VAT nuber: 1234567890, ID: 4</Customer>
</Invoice>

Error - invalid item code, item tax type or sales account:

<Invoice invoice_number="1">
<Errors>Invalid item code, item tax type and/or empty sales account.</Errors>
<Customer>Customer found in database. VAT nuber: 1234567890, ID: 4</Customer>
</Invoice>