Transferring Orders from an E-shop to ABRA Flexi
We recommend reading Part 1 of this article first: Transferring Data from Accounting to an E-shop.
What data needs to be transferred from the e-shop to ABRA Flexi?
The customer has completed their journey through the e-shop by placing an order, which must be transferred to and processed in ABRA Flexi. A stock issue voucher and an invoice need to be created from it, and payments then "matched" to that invoice.
Most e-shop integrations with Flexi do not create records in the objednavka-prijata register in Flexi, but instead create invoices or payment requests directly, in order to reduce the number of documents that need to be processed. However, it is of course possible to create an order first and then invoice it. Each order contains line items that specify what the customer ordered. In Flexi, it is possible to enter items from a price list or without a price list reference, as stock or non-stock items, on both orders and invoices. The customer can be selected from the company address book or entered directly on the document.
To successfully create an order, an XML or JSON file must first be assembled on the e-shop side and then sent to Flexi using the PUT or POST method.
The file for creating an order should have a structure such as:
<?xml version="1.0"?><winstrom> <objednavka-prijata><id>ext:OBP-ESHOP:123</id><!-- místo 123 použijte vnitřní identifikátor objendávky v eshopu --><typDokl>code:OBP-ESHOP</typDokl><!-- zkratka typu dokladu, který se má použít na vytvářenou objednávku --><stredisko>code:ESHOP</stredisko><!-- pokud využíváte střediskovou cenotvorbu --><firma>code:FIRMA</firma><!-- zkratka firmy pro výběr firmy z adresáře -->...<polozkyDokladu removeAll="true"><objednavka-prijata-polozka><id>ext:OBP-POL-ESHOP:234</id><!-- místo 234 použijte vnitřní identifikátor položky objednávky v eshopu --><cenik>code:CENIK</cenik><!-- zkratka objednaného zboží z ceníku--><sklad>code:SKLAD</sklad><!-- zkratka skladu ze kterého bude zboží vyskladněno --><mnozMj>1</mnozMj><!-- objednané množství --><cenaMj>100</cenaMj><!-- jednotková cena za kterou bylo zboží objednáno -->...</objednavka-prijata-polozka></polozkyDokladu></objednavka-prijata></winstrom>
TIP: We recommend that whenever you send data to ABRA Flexi, you always try to use identifiers (id elements). This allows customers to make subsequent changes to their order from the e-shop (for example, changing the ordered quantity or delivery address). Also, only fill in fields whose meaning and effect you understand. A complete list of available fields for received orders can be found at https://demo.flexibee.eu/c/demo/objednavka-prijata/properties .
Order Fulfillment
We will now fulfill the order from the e-shop. This can be done either manually or in an automated way.
To automate the process, you need to send an XML file to ABRA Flexi that looks like this, for example:
<?xml version="1.0"?><objednavka-prijata> <id>ext:OBP-ESHOP:123</id> <realizaceObj type="faktura-vydana"> <id>ext:FAV-ESHOP:123</id> <!-- nepovinné, id faktury, která se z objednávky vytvoří --> <polozkyObchDokladu> <polozka> <cisRad>1</cisRad> <!--č. řádky v obj.--> <mj>1</mj> </polozka> </polozkyObchDokladu> </realizaceObj></objednavka-prijata>
When fulfilling an order, it is advantageous to immediately assign an external identifier to the generated invoice so that we can subsequently work with it — for example, to retrieve a PDF form, submit it to EET, or send the PDF to the customer by email.
If the order was paid by card, the invoice generated from that order must be submitted to EET. Submitting documents to EET is described in the article EET automatically via REST API.
If you want to send an invoice to the customer by email, simply send the following XML file to ABRA Flexi after the order has been successfully fulfilled:
<?xml version="1.0"?><winstrom> <faktura-vydana> <id>ext:FAV-ESHOP:123</id> <stavMailK>stavMail.odeslat</stavMailK> <!-- na faktuře nastaví, že má dojít k automatickému odeslání --> </faktura-vydana></winstrom>
Sending individual invoices that are queued for dispatch is done by calling
PUT|POST /c/{firma}/faktura-vydana/automaticky-odeslat-neodeslane
Authentication via the Contacts Register
If you are thinking about where to securely store your customers' usernames and passwords, and how to provide a simple way for users to log in using these credentials, it is advantageous to use the contacts register.
For each customer, a record needs to be created in the contacts register with the username and password fields filled in:
POST /c/{firma}/kontakty/{id}.xmljanheslo
Authentication using records in the contacts register is then performed by sending a request
POST to the address:
POST /c/{firma}/kontakty/{id}/authenticate username=jan&password=heslo
Custom Queries
If you find that certain calls are unnecessarily complex or slow, or that they do not return results in exactly the format you need, you can make use of the uzivatelsky-dotaz register.
This register allows you to add custom SQL queries to ABRA Flexi that are tailored specifically to your needs. These queries make it possible to retrieve data from ABRA Flexi that is not accessible via the API, or to optimize how that data is read.
The downside of creating custom queries is that it requires knowledge of the ABRA Flexi database schema, and that — unlike the API — the system does not guarantee the stability of the database schema.
A custom query can then be called via the API as follows:
GET|POST /c/{firma}/uzivatelsky-dotaz/{id}/call.{xml|json}?parametry=hodnoty... &detail/start/limit
Web Hooks
Another way to optimize the integration is to use web hooks. This is the best way for an e-shop to be notified of changes in the ABRA Flexi system in real time.
Documentation for web hooks is available here. Web hooks will save you many unnecessarily complex queries to ABRA Flexi and allow you to load only the data that has actually changed.