General concepts

General concepts

Some compliance related concepts that apply to most countries

note

This is not an inclusive list i.e. some concepts are described and covered at the time of configuration or in the respective country compliance documentation.

#1 Invoice behavior on exchange orders

Exchange order setting

The requirement to allow for exchange orders can be toggled via a setting called Auditing:AllowExchangeOrders. Default value is false.

In countries where exchange orders can be configured (check the list of countries here), two invoices are always created. An invoice for the credit and another for the debit. This would also mean that at the end of a checkout flow, once all transaction impacting events have occurred, users will be able to see and retrieve two invoices in the Orders overview chapter Documents tab. Further, any subsequent invoice print requests will result in automatic printing of those two invoices.

For a better understanding, let's look at some scenarios. All scenarios covered assume that an initial sales transaction of two items has occurred. Item no. 1 had a sales price of €15.00 and item no. 2 had a sales value of €60.00. The customer here ends up with the usual invoice, depicting the two purchased items with a total of €75.00. For one reason or another, the customer wants to return item no. 2 which had a sales price of €60.00 and exchange it for something else (an exchange order). This leads us to the following three possible scenarios:

Scenario 1

For the exchange, the customer opts for a more expensive item (price €80.00)

Invoice 1 - Credit invoice

Lines

60 EUR (returned)

Payments

60 EUR (exchange voucher)

Invoice 2 - Debit invoice

Lines

80 EUR (new item)

Payments

60 EUR (exchange voucher)
20 EUR (new payment)

Scenario 2

For the exchange, the customer opts for a cheaper item (price €45.00)

Invoice 1 - Credit invoice

Lines

60 EUR (returned)

Payments

60 EUR (exchange voucher)

Invoice 2 - Debit invoice

Lines

45 EUR (new item)

Payments

60 EUR (exchange voucher)
-15 EUR (new payment)

Scenario 3

For the exchange, the customer opts for an item of same value (price €60.00)

Invoice 1 - Credit invoice

Lines

60 EUR (returned)

Payments

60 EUR (exchange voucher)

Invoice 2 - Debit invoice

Lines

60 EUR (new item)

Payments

60 EUR (exchange voucher)

List of countries compatible with exchange orders

The following is the list of countries where exchange orders can be configured:

France
Italy
Japan
Macau
Portugal
South Africa
Sweden
Switzerland
The Netherlands

note

This list is being regularly updated as new countries are added.

#2 SAFT countries mixed orders

Mixed orders are not allowed in SAFT countries. As per regulations, it is not allowed to have both return and sales lines in the same order in SAFT audited countries. In turn, the user will be notified with an error modal "You cannot create a combined sale- and return order, due to the regulation within your country" in scenarios where it applies.

#3 Invoice product line description display

If for some reason you would like to override the default product Description property on an invoice order line, you can do so by using a setting called InvoiceLineDescriptionProperty. The value of this setting should be a product property. The description of that product property would replace the default product Desxription property.

#4 VAT and FiscalID

There are 2 services GetShoppingCart and GetOrder where VAT and FiscalID are present. It could get confusing as to which one the system chooses at various scenarios.

Lets clear that confusion:

VAT Number

The VAT number on the order object is leading. When a VAT number on an order is present, that would be the one shown on the invoice. If it's not present, then the VAT number under the customer object becomes the one shown.

Fiscal ID

At checkout, having a Fiscal ID tile for user input of a fiscal ID is possible. If a customer with an existing fiscal ID available i.e. under customer object, and is already attached to an order, then that fiscal ID is prefilled.

If there is no customer attached, or if the fiscal ID field on customer object was empty, a manual input would then be possible using the Fiscal ID tile. The filled in Fiscal ID in this scenario would then be set on the order object and not the customer object. Meaning that if you attach that same customer to another order, the Fiscal ID input which was made on his previous order would not autopopulate.

In another scenario, if a POS user overwrites the prefilled fiscal ID picked up form the customer object, the fiscal ID field on the order object would be the one updated and the one that would be shown on the invoice for that order. The fiscal ID on the customer object will remain the same. Again, giving the same meaning as mentioned above if that same customer is added to another order.

#5 Certified invoice stencil (Destination: Thermal or PDF)

Certified invoice stencils for Thermal and PDF are supplied by us and are not editable by you to ensure its compliance to local requirements.

However, it is possible for you to create your own partials to influence the header and footer of the certified invoices. This way you can give your own look and feel to fully certified invoices.

For information on templates and partials in general, please view the Stencil basics or the Invoice and thermal stencils docs directly.

To start creating these partials, please go to the Partial tab in the Stencil chapter. You can then enter the following specifics when creating one:

Thermal

Organization - Leave blank
Name - although free-form, it must be either InvoiceReceiptHeader or InvoiceReceiptFooter
Country - Check possible inputs from the below list. Please choose the country that would align with your input value for the Auditing:Provider setting.
Language - Leave empty if you want to use the same header and footer on all templates.
Destination - Thermal

PDF

Organization - Leave blank
Name - CertifiedInvoice-Header or CertifiedInvoice-Footer
Country - Check possible inputs from the below list. Please choose the country that would align with your input value for the Auditing:Provider setting.
Language - Leave empty if you want to use the same header and footer on all templates.
Destination - PDF

Feel free to add any content you would like in those partials.

Name must match

Be careful to name the partials exactly as named here above, since the CertifiedInvoice template contains a hardcoded reference to it.

Organization unit supplier partial

A partial template called CertifiedInvoice-Supplier can be created to use on certified invoices (PDF and Thermals). This partial can be used to set additional fields under the organization unit details of type Supplier on your certified templates. It can also used to display custom fields of such organization unit types or any other information you would like to add.

For example, the partial for a custom field would contain the following:

{{>Supplier.CustomFields.Test}}, {{>Supplier.CustomFields.TestCustomField1}}`

More on organization unit types can be found here.

Employee details on certified receipts

You can influence which employee details are mentioned on the certified receipt by means of a setting.

The setting is called Auditing:EmployeeDisplayType and its value should be one (only) of the following options:

FirstName: Prints the first name of the employee on the receipt / invoice.
LastName: Prints the last name of the employee on the receipt / invoice.
FullName: Prints the full name (first + last name) of the employee on the receipt / invoice.
ID: Prints the EVA ID of the employee on the receipt / invoice.
Number: Prints the employee number of the employee on the receipt / invoice.

This is applicable to all certified countries thermal receipts in addition to the PDF invoice of Portugal and Norway.

Foreign description

There is a part in the certified invoice stencil which, if configured, would display the invoiced product(s) product property on your invoices.

Of course, the use of it depends on whether your products follow such structure or not. For that reason, the underlying part in the certified invoice stencil is given as an "if" statement i.e. if configured it'll be visible, if not it will remain invisible.

The "if" statement points to what we call a ForeignDescription (sample below). If configured using a setting called Auditing:ForeignDescriptionProperty and a respective value that depicts the desired product property type, then you'll see that displayed on your invoices.

    {{if ForeignDescription}}
                <row>
                    <col>{{>ForeignDescription}}</col>
                </row>
    {{/if}}

The use case for this is to create bilingual receipts and invoices (e.g. the receipt shows the English product description, and the ForeignDescription is set to the property that contains the Arabic description).

Foreign description property

The ForeignDescription property is only exposed on CertifiedInvoices of Oman, Bahrain, Jordan, and the United Arab Emirates.

List of certified invoice countries

The following is a list of available countries that can be used as input for the stencil field Country.

Please choose accordingly based on your input for the Auditing:Provider setting:

Austria
France
Germany
Italy
Japan
Macau
Norway
Portugal
South Africa
Spain
Sweden
Switzerland
The Netherlands

note

Once a Auditing:Provider is specified (a mandatory setting that is part of any compliance configuration), certified invoices are automatically triggered to ensure compliance to local requirements. This does mean that any thermal receipt or invoice template(s) that already existed within your environment would be replaced with the Certified Invoice template.

#6 Emailing invoices and thermal receipts

Invoice

To send certified invoices via email, a stencil configuration is also required. Unlike the Certified invoice stencil thermal/PDF, the email invoice stencil can be freely customized to your look and feel. In other words, you are not limited to only customizing the InvoiceReceiptHeader and InvoiceReceiptFooter.

To create an invoice template, head over to the Stencil chapter via Admin Suite's Control room module, click Add and set the following fields:

Type - Template
Organization - Leave blank
Name - CertifiedInvoice
Country - Please choose the country you'd like to set this up for.
Language - As desired
Destination - Mail

Feel free to add any content you would like to these templates. A sample can be found here.

Thermal receipt

It is also possible to email the customer their thermal receipt. This can be done by configuring the ElectronicReceipt template.

Type - Template
Organization - Leave blank
Name - ElectronicReceipt
Country - Please choose the country you'd like to set this up for.
Language - As desired
Destination - Mail

Template sample

To make things just a tad easier, here's a sample of a template you could use for the ElectronicReceipt template, which requires Destination Mail.

    {#subject}New Black - Electronic Receipt{#/subject}
<div style="font-family: 'Helvetica', Arial, sans-serif;font-size: 16px;color: #82786f;">
    Invoice #{{>InvoiceNumber}}
    <br />&nbsp;
</div>

<div style="border-top: 1px solid #dad6d2; height:20px;">&nbsp;</div>

<p style="font-family: 'Helvetica', Arial, sans-serif;font-size: 12px;line-height: 16px;text-align: left;color: #525252; padding-bottom: 10px;">
    {{if Customer}}
        Dear {{>Customer}},
    <br />
    <br />
    {{/if}}

    Please find your electronic receipt attached to this e-mail. This is also your guarantee certificate, so be sure to save this e-mail.
    <br />
    <br />
    Any further questions? Please get in touch with our customer service department via the online contact form: <a href="https://newblack.io" title="FAQ and customer service" target="_blank">https://newblack.io</a>. 
    <br />
    <br />
    Important!<br />
    We recommend that you open the product's original packaging carefully and
    save the packaging it was shipped in, in case you decide you want to return your order.
    For more information about returning or exchanging articles, please see our FAQ for the returns policy</a>.
    <br />
    <br />
    We hope you enjoy your purchase!
    <br />
    <br />
    Kind regards,<br />
    {{>OrganizationUnit}}
    <br />
    <br />
    This is an automatically generated e-mail. Please do not reply to this message.<br />
    Our <a href="https://newblack.io" title="General terms and conditions" target="_blank">general terms and conditions</a> apply.
</p>

Mailing a PIN payment receipt

While the PIN payment proof part is included on the thermal receipt by default, you can also send out just the payment proof part only by mail. You can do so by configuring the ThermalLastPinReceipt.

Settings

There are a few settings which you can use to influence the default/preferred output type for producing documents in stores at checkout:

Auditing:PreferReceiptPrinting: Setting its value to true (default value is false) would default the checkmark on print Receipt at checkout.
Auditing:PreferPaperPrinting: Setting its value to true (default value is false) would default the checkmark on print invoice Paper at checkout.
Auditing:PreferElectronicReceipt: Setting its value to true (default value is false) would default the checkmark on Email receipt at checkout i.e. the ElectronicReceipt stencil emailed to the customer.
Auditing:PreferEmail: Setting its value to true (default value is false) would default the checkmark on Email Invoice at checkout.

You can mix the setting

The above settings can be concurrently configured if desired.

#7 Simplified invoices

Simplified invoices are basically a regular sales receipt however, one that includes less data. Usually an invoice includes data like full customer details: name, billing address, VAT number, etc. Simplified invoices only needs a VAT number or Fiscal ID and is only issued/allowed if a certain sales threshold is not exceeded. For example, if the total order amount does not exceed €100.

This applies to a few countries, as follows:

Country	Threshold
Poland	When the order amount is 450 Zloty or below and a NIF/VAT is set, a simplified invoice is generated.
Spain	If the order is anonymous and below €3000 or if a B2C customer is attached to the order without NIF (FiscalID) present, and the amount is below €3000, a simplified invoice is generated.
Sweden	Below 4000 SEK and NIF / VAT is set, a simplified invoice is generated.

#8 Invoice sequencing (no auditing provider)

In scenarios where a country go-live is happening, and the corresponding country has no auditing provider specified in the Auditing:Provider setting, it is then recommended you use a setting called Auditing:UseOrganizationUnitSequence and a value of true. The setting will ensure that the invoice numbers generated will be based on organization unit level and not on company level (example: OU ID-Document type / Sequence number).

This gives the invoice sequence a uniqueness aspect, and thus a smaller chance of an invoice chain lock.

#9 Terminal report auto printing

Countries applicable to

This feature is available for all supported countries except Italy.

Using a setting called Auditing:PrintTerminalReport and a value true, accompanied by the Terminal Report stencil, an automatic print of the Z report will be made once a financial period is closed. If you have multiple stations in you store, a print of all Z reports pertaining to the station you're logged into when closing your financial period will be printed.

Printer configurations

Beware that printer configurations for the respective stations need to exist in order for the Z reports to successfully print.

Stencil for Terminal report

To enable printing of X/Z reports, a stencil called TerminalReport is used, sample below.

Template editing

For compliancy purposes, this stencil is only editable by us (New Black).

Here is the stencil content

<report>
    <scope bold="true" align="center" size="1,1">
        {{>Document.Type == 0 ? 'X Report' : 'Z Report'}} #{{>Number}}
    </scope>
    
    <scope align="center" font="FontB" tabs="21">
        {#partial TerminalReportHeader}
    </scope>
    
    <feed amount="32"/>
    
    Date: {{:~date(Document.CreationTime, 'DD.MM.YYYY', 'fr-FR', 'Europe/Paris')}}
      Heure: {{:~date(Document.CreationTime, 'HH:mm:ss', 'fr-FR', 'Europe/Paris')}}
    
    <feed amount="32"/>

    <grid positions="0, 30">
        <row>
            <col width="20">
                <bold>Changement</bold>
            </col>
            <col>{{:~currency(Document.Change, ~root.CurrencyID)}}</col>
        </row>
        <row>
            <col width="20">
                <bold>Ouverture du tiroir-caisse</bold>
            </col>
            <col>{{>Document.CashDrawerOpenings}}</col>
        </row>

        <row>
            <col width="20">
                <bold>Paiements</bold>
            </col>
            <col>{{: Document.Payments ? Document.Payments.length : 0}}</col>
        </row>

        {{for Document.Payments}}
        <row>
            <col width="20">
                {{>Type.Name}} ({{>Count}})
            </col>
            <col>{{:~currency(Amount, ~root.CurrencyID)}}</col>
        </row>
        {{/for}}

        <row>
            <col width="20">
                <bold>Taxes</bold>
            </col>
            <col>{{: Document.Taxes ? Document.Taxes.length : 0}}</col>
        </row>   

        {{for Document.Taxes}}
        <row>
            <col width="20">
                {{>Name}} ({{:~rateToPercentage(Rate)}})
            </col>
            <col>{{:~currency(Amount, ~root.CurrencyID)}}</col>
        </row>        
        {{/for}}

        <row>
            <col width="20">
                <bold>Paiements par employé</bold>
            </col>
            <col>{{: Document.PaymentsPerUser ? Document.PaymentsPerUser.length : 0}}</col>
        </row>

        {{if Document.PaymentsPerUser}}
        {{for Document.PaymentsPerUser}}
        <row>
            <col width="20">
                Employé(e) {{>UserID}} ({{>Count}})
            </col>
            <col>{{:~currency(Amount, ~root.CurrencyID)}} ({{>Description}})</col>
        </row>
        {{/for}}    
        {{/if}}

        <row>
            <col width="20">
                <bold>Groupes de produits</bold>
            </col>
            <col>{{>Document.ProductGroups.length}}</col>
        </row>

        {{for Document.ProductGroups}}
        <row>
            <col width="20">
                {{>Code}} ({{>Count}})
            </col>
            <col>{{:~currency(Amount, ~root.CurrencyID)}}</col>
        </row>
        {{/for}}

        <row>
            <col width="20">
                <bold>Nomber de remise</bold>
            </col>
            <col>{{>Document.DiscountCount}}</col>
        </row>
        <row>
            <col width="20">
                <bold>Total des remises</bold>
            </col>
            <col>{{:~currency(Document.TotalDiscounts, ~root.CurrencyID)}}</col>
        </row>     

        <row>
            <col width="20">
                <bold>Nombre de retours</bold>
            </col>
            <col>{{>Document.ReturnCount}}</col>
        </row>
        <row>
            <col width="20">
                <bold>Total des retours</bold>
            </col>
            <col>{{:~currency(Document.TotalReturnsAmount, ~root.CurrencyID)}}</col>
        </row> 

        <row>
            <col width="20">
                <bold>Nomber d'exemplaires</bold>
            </col>
            <col>{{>Document.CopyReceiptsPrinted}}</col>
        </row>
        <row>
            <col width="20">
                <bold>Total d'exemplaires</bold>
            </col>
            <col>{{:~currency(Document.TotalCopyReceiptsAmount, ~root.CurrencyID)}}</col>
        </row>      

        {{* Grand totals *}}
        <row>
            <col width="20">
                <bold>Total général (paiement en espèces)</bold>
            </col>
            <col>{{:~currency(Document.GrandTotalCash, ~root.CurrencyID)}}</col>
        </row>
        <row>
            <col width="20">
                <bold>Total général</bold>
            </col>
            <col>{{:~currency(Document.GrandTotal, ~root.CurrencyID)}}</col>
        </row>        
        <row>
            <col width="20">
                <bold>Total général (retours)</bold>
            </col>
            <col>{{:~currency(Document.GrandTotalReturns, ~root.CurrencyID)}}</col>
        </row>        
        <row>
            <col width="20">
                <bold>Total général (HT)</bold>
            </col>
            <col>{{:~currency(Document.GrandTotalNet, ~root.CurrencyID)}}</col>
        </row>        
    </grid>

    <feed amount="32"/>
    
    Terminal: {{>TerminalCode}}
    
    <feed amount="16"/>

    <scope align="center">
        <qrcode data="{{:ZippedSignature}}" size="6"/>
    </scope>

    <feed amount="16"/>
</report>        

General concepts

#1 Invoice behavior on exchange orders​

Scenario 1​

Invoice 1 - Credit invoice​

Invoice 2 - Debit invoice​

Scenario 2​

Invoice 1 - Credit invoice​

Invoice 2 - Debit invoice​

Scenario 3​

Invoice 1 - Credit invoice​

Invoice 2 - Debit invoice​

List of countries compatible with exchange orders​

#2 SAFT countries mixed orders​

#3 Invoice product line description display​

#4 VAT and FiscalID​

VAT Number​

Fiscal ID​

#5 Certified invoice stencil (Destination: Thermal or PDF)​

Organization unit supplier partial​

Employee details on certified receipts​

Foreign description​

List of certified invoice countries​

#6 Emailing invoices and thermal receipts​

Invoice​

Thermal receipt​

Settings​

#7 Simplified invoices​

#8 Invoice sequencing (no auditing provider)​

#9 Terminal report auto printing​

Stencil for Terminal report​

#1 Invoice behavior on exchange orders

Scenario 1

Invoice 1 - Credit invoice

Invoice 2 - Debit invoice

Scenario 2

Invoice 1 - Credit invoice

Invoice 2 - Debit invoice

Scenario 3

Invoice 1 - Credit invoice

Invoice 2 - Debit invoice

List of countries compatible with exchange orders

#2 SAFT countries mixed orders

#3 Invoice product line description display

#4 VAT and FiscalID

VAT Number

Fiscal ID

#5 Certified invoice stencil (Destination: Thermal or PDF)

Organization unit supplier partial

Employee details on certified receipts

Foreign description

List of certified invoice countries

#6 Emailing invoices and thermal receipts

Invoice

Thermal receipt

Settings

#7 Simplified invoices

#8 Invoice sequencing (no auditing provider)

#9 Terminal report auto printing

Stencil for Terminal report