A credit note is linked to the invoice it credits via a relation. Using the REST API, you can either link an already existing credit note to an invoice, or have the entire credit note — including its links — created from selected items of the original document. Both approaches use nested elements in the import and work on the faktura-vydana and faktura-prijata records.

⚠️ The document into which you place the nested elements must be of type credit note. Otherwise, the import will fail with error parovaniDobropisuNeniDobropis. On records other than issued and received invoices, the elements are silently ignored and the import completes with no effect.

Linking a credit note to an invoice

A link to an existing credit note is created using the vytvor-vazbu-dobropis element:

<?xml version="1.0"?>
<winstrom version="1.0">
  <faktura-vydana>
    <!-- dobropis; může být i "faktura-prijata" -->
    <id>code:DOBROPIS1</id>
    <!-- lze normálně uvést další vlastnosti dokladu jako při běžném importu -->
    <vytvor-vazbu-dobropis>
      <dobropisovanyDokl>code:FAKTURA1</dobropisovanyDokl>
      <!-- identifikátor dobropisovaného dokladu -->
    </vytvor-vazbu-dobropis>
  </faktura-vydana>
</winstrom>

The credited document is specified in the dobropisovanyDokl element according to the usual rules for identifiers. If the invoice is not found, the import will fail with an error.

A single credit note can only be linked to one invoice. However, multiple credit notes can be linked to a single invoice. Attempting to link a credit note that is already linked to another invoice will fail with error parovaniDobropisuLzeJenJednou — you must first remove the existing link.

After a successful link, the credited document has its dobropisovano flag set to true, and the link appears in the vazby relation of both documents. In the link record, the credited invoice is stored in the a property and the credit note in the b property:

GET https://demo.flexibee.eu/c/demo/faktura-vydana/DOBROPIS1.json?relations=vazby

Important notes

The service creates only the link — the crediting document must have its line items created correctly.
The created link only connects the document headers; it does not handle linking of individual items.
The purchase price given on the items should match the stock price of the goods from the credited document; otherwise the stock balance won't be correct.
If no purchase price is given, the current stock price is used.
If the goods are not in stock, the purchase price from the price list is used.

ℹ️ If you're creating a credit note via a regular import, the quantity on its items must be negative — otherwise the import will fail with error polDoklDobropisChybaZaporneMnozstvi. Conversely, in the dobropisuj service described below, the credited quantity is given as a positive value.

Creating a credit note including links

The second option is to let the dobropisuj service create the entire credit note. This results in a fully-fledged credit note with links between items as well. In addition to the identifier of the credited invoice (dobropisovanyDokl), you specify which items are to be credited (polozkyDokladu) — for each one, its id and quantity mnozMj:

<winstrom version="1.0">
  <faktura-vydana>
    <typDokl>code:DOBROPIS</typDokl>
    <!-- lze uvést další vlastnosti dokladu jako při běžném importu -->
    <dobropisuj>
      <dobropisovanyDokl>code:VF1-0001/2021</dobropisovanyDokl>
      <polozkyDokladu>
        <polozka>
          <id>123</id>
          <mnozMj>1</mnozMj>
        </polozka>
      </polozkyDokladu>
    </dobropisuj>
  </faktura-vydana>
</winstrom>

The polozkyDokladu element is required — without it, the import will fail with error validace.notNull. The specified items must exist on the credited document, and you cannot credit a larger quantity than what remains on the item; the service keeps track of how much has already been credited.

The result is a new document with negative amounts, linked to the credited invoice, with the dobropisovano flag set on the original document. You can find the number of the new document in the return values under results.

💡 An import with the ?dry-run=true parameter only checks the input and does not create the document — in results it then returns id equal to -1. It's worth verifying the item IDs and quantities this way before the credit note is actually created.

Serial numbers

If an item has serial numbers tracked, you need to specify the corresponding number of serial numbers in the vyrobniCislaId element:

<winstrom version="1.0">
  <faktura-vydana>
    <typDokl>code:DOBROPIS</typDokl>
    <dobropisuj>
      <dobropisovanyDokl>code:VF1-0001/2021</dobropisovanyDokl>
      <polozkyDokladu>
        <polozka>
          <id>123</id>
          <mnozMj>1</mnozMj>
          <vyrobniCislaId>
            <vyrobniCisloId>456</vyrobniCisloId>
          </vyrobniCislaId>
        </polozka>
      </polozkyDokladu>
    </dobropisuj>
  </faktura-vydana>
</winstrom>

Serial numbers of sets

You can also specify serial numbers of sets in the vyrobniCislaSad element:

<winstrom version="1.0">
  <faktura-vydana>
    <typDokl>code:DOBROPIS</typDokl>
    <dobropisuj>
      <dobropisovanyDokl>code:VF1-0001/2021</dobropisovanyDokl>
      <polozkyDokladu>
        <polozka>
          <id>123</id>
          <mnozMj>1</mnozMj>
          <vyrobniCislaSad>
            <vyrobniCislaSady>
              <sadaId>789</sadaId>
              <vyrobniCislaId>
                <vyrobniCisloId>456</vyrobniCisloId>
              </vyrobniCislaId>
            </vyrobniCislaSady>
          </vyrobniCislaSad>
        </polozka>
      </polozkyDokladu>
    </dobropisuj>
  </faktura-vydana>
</winstrom>

Creating a mutual offset

If the vytvorZapocet element with the value true is specified within vytvor-vazbu-dobropis, a mutual offset is created at the same time, settling both the invoice and the credit note. In that case, the offset document type is required and is specified in the typDoklZapocet element:

<winstrom version="1.0">
  <faktura-vydana>
    <!-- dobropis; může být i "faktura-prijata" -->
    <id>code:DOBROPIS1</id>
    <vytvor-vazbu-dobropis>
      <dobropisovanyDokl>code:FAKTURA1</dobropisovanyDokl>
      <vytvorZapocet>true</vytvorZapocet>
      <typDoklZapocet>code:ZAPOCET</typDoklZapocet>
    </vytvor-vazbu-dobropis>
  </faktura-vydana>
</winstrom>

The document type is taken from the typ-vzajemnych-zapoctu records. Without the typDoklZapocet element, the import will fail with error importXmlEmptyIdentifier.

The offset creates a pair of documents in the vzajemny-zapocet records — one on the invoice side, one on the credit note side, both for the amount of the credit note. The rules governing the offset are as follows:

Field	Source
Offset date	The date from the more recent of the two documents.
Summary number	The variable symbol from the invoice.
Exchange rate for foreign currency documents	The exchange rate retrieved as of the offset date.

After the offset, the payment status of both documents changes: the credit note is marked as paid, and the invoice is marked as paid to the extent of the credit note amount (in the case of a partial credit note, this means stavUhr.castUhr).

Removing a credit note link

The link is removed using the empty zrus-vazbu-dobropis element:

<?xml version="1.0"?>
<winstrom version="1.0">
  <faktura-vydana>
    <!-- dobropis; může být i "faktura-prijata" -->
    <id>code:DOBROPIS1</id>
    <zrus-vazbu-dobropis/>
  </faktura-vydana>
</winstrom>

🚨 Only a manually created link can be removed — that is, one created using the vytvor-vazbu-dobropis element. A link created by the dobropisuj service cannot be removed — the import will return error parovaniDobropisuNelzeZrusit. Therefore, a credit note created by the dobropisuj service cannot be detached from its invoice and relinked elsewhere.

Error states

All of the cases listed below return 400, and the entire import is not performed:

Error code	Cause
`parovaniDobropisuNeniDobropis`	The document into which you nested the element is not of type credit note.
`parovaniDobropisuNenalezenDobropisovanyDoklad`	The document specified in `dobropisovanyDokl` does not exist.
`parovaniDobropisuLzeJenJednou`	The credit note is already linked to another invoice.
`parovaniDobropisuNelzeZrusit`	The link was not created manually, but by the `dobropisuj` service — it cannot be removed.
`polDoklDobropisChybaNotFound`	The item specified in `polozkyDokladu` is not on the credited document.
`polDoklDobropisChybaMaxReal`	The credited quantity is greater than the quantity remaining on the item.
`polDoklDobropisChybaZaporneMnozstvi`	An item of a credit note being created via a regular import has a non-negative quantity.
`validace.notNull`	The `dobropisuj` service is missing the required `polozkyDokladu` element.
`importXmlEmptyIdentifier`	`vytvorZapocet` is specified, but `typDoklZapocet` is missing.

Credit Notes