In the item listing, the parent document is only returned as a reference. Using the includes parameter, you can include its properties directly in the response instead of just the reference — this is useful when, from an item, you need to get the company from the document header, for example.
Without includes
The link to the document is just a reference — you know where to look, but you don't have the data in the response:
<doklFak ref="/c/{firma}/faktura-vydana/2859.xml" showAs="KBF1">code:KBF1</doklFak>
With includes
The path in the includes parameter specifies which link should be expanded; detail=custom then determines which fields you want from the expanded document:
GET /c/{firma}/faktura-vydana-polozka/(id eq 3595).xml
?detail=custom:nazev,mnozMj,doklFak(kod,firma)
&includes=/faktura-vydana-polozka/doklFak/
The response has the document expanded inside the item:
<faktura-vydana-polozka>
<id>3595</id>
<nazev>FRadek 1</nazev>
<mnozMj>1.0</mnozMj>
<doklFak>
<faktura-vydana>
<id>2859</id>
<kod>KBF1</kod>
<firma>…</firma>
</faktura-vydana>
</doklFak>
</faktura-vydana-polozka>
ℹ️ The path in includes consists of the names of the records and links you use to reach the target — it starts with the record you're querying. It works the same way in the other direction as well, i.e., from the header to the item price list, or across several levels in sequence.
The same principle applies to a stock document — from an item to the company in the header:
GET /c/{firma}/skladovy-pohyb-polozka/(cenik.id eq 13).json
?detail=custom:nazev,mnozMj,cenik,doklSklad(firma)
&includes=/skladovy-pohyb-polozka/doklSklad/