Create Invoice

This section contains the description of the Create Invoice command.

This command enables applying a digital signature on the transaction data received from the taxpayer's invoicing
system. It provides non-repudiation of the signed invoice, i.e. the taxpayer cannot deny the content of the invoice
nor that the invoice was signed using his/her secure element.

Endpoints

NOTE:
Development, testing and technical review are all done in the Sandbox environment. The next step is the
administrative review process which enables getting accreditation for a specific country. Different countries have
different environment names, and every environment has its own URL. See Environments.

SDC Endpoint Example

V-SDC https://vsdc.sandbox.suf.purs.gov.rs//api/v3/invoices
https://vsdc.sandbox.taxcore.online/api/

E-SDC http://<ESDC_ip_address>:<ESDC_port>/api/v3/invoices
http://192.168.88.112:8888/api/v3/invoic

Method
POST

Authentication

V-SDC
Use client digital certificate for authentication with each request to V-SDC.Api.

E-SDC
E-SDC does not require client authentication.

Request

Headers
Headers
Add following HTTP headers to each request

• Accept: application/json
• Content-Type: application/json
• RequestId: <RequestId_value> (Unique identifier of the request, generated by POS system. It is
used only for later request search, in case a response was not received. - optional). MaxLength: 32
• Accept-Language: <Accept-Language_value> (The list of one or more languages returned
through the field supportedLanguages in the Get Status service response, ordered in POS language
preference and separated by semi-colon.)
o SDC returns Invoice Result in the first supported language from the list
o if none of the languages from the list are supported by SDC, the SDC returns HTTP status code
406
o if POs does not submit this parameter, SDC returns Invoice Result in the first language from the
list obtained through Get Status service
• PAC: <PAC_value> (PAC value for the provided client authentication certificate - only for V-SDC)

Invoice

Field Optional/Mandatory Description

dateAndTimeOfIssue Optional Current Local Date and Time in ISO

8601 format. This is an optional
element on the API level. However,
tax legislation in certain jurisdictions
might mandate including it on
invoices - so make sure you
become familiarized with the
requirements in each jurisdiction.

invoiceType Mandatory Invoice Type enumeration value: 0 -

Normal, 1 - Proforma, 2 - Copy, 3 -
Training, 4 - Advance

transactionType Mandatory Transaction Type enumeration

value: 0 - Sale, 1 - Refund

payment Mandatory List of Payments for the invoice,

where each Payment defines it's
method and amount

cashier Optional Cashier’s identification.

buyerId Optional Unique identification of the

buyer/customer. It is mandatory
only if there is a legal obligation
for buyer identification (in both
B2C and B2B transactions);
otherwise, it's optional.
buyerCostCenterId Optional Cost Center ID provided by the
buyer to the cashier or an
identification of the invoice
purpose. It is mandatory only if
there is a legal obligation for
invoice purpose identification (in
both B2C and B2B transactions);
otherwise, it's optional.

invoiceNumber Optional Invoice number generated by a POS

or the software version of the
accredited POS. This is an optional
element on the API level. However,
tax legislation in certain jurisdictions
might mandate including it on
invoices. Make sure you become
familiarized with specific
jurisdiction requirements
regarding its use and content.

referentDocumentNumber Mandatory for all Copies and Mandatory only in case Invoice
Refunds and some Normal Sale or Type is Refund, Copy or Advance
Advance Sale invoices Sale connected to an Advance Sale
(other jurisdiction-specific rules may
apply). In all cases, this field must
contain Invoice Number of the
previously issued invoice. In any
other case this field is optional.
ASCII, in the requestedBy-
signedBy-Ordinal_Number format.
Unicode MaxLength: 50

referentDocumentDT Optional SDC date and time of the

document referenced in the
referentDocumentNumber field.
It is used to calculate taxes on the
date of issue of the original
document that is refunded or
copied. If it is not provided in the
request, SDC uses the currently
active tax rates.

items (n) Mandatory Each invoice contains at least one

Item in Items collection (E-SDC
should support minimum 250,
recommended up to 500)

options Optional Key/value collection defines the

output of E-SDC invoice
fiscalization, to optimize resources.
 Key: omitQRCodeGen
Value: "1" to omit QR Code
generation by E-SDC and "0" to
generate and return QR code to
POS.
QR code must not be submitted to
the tax authority as part of an audit
package.

Key: omitTextualRepresentation
Value: "1" to omit generation of
textual representation by E-SDC and
"0" to generate return textual
representation to POS.
Textual representation of an invoice
(journal) must be submitted to the
tax authority as part of an audit
package.

Item
Each Item represents one line item on the invoice.

Field Optional/Mandatory Description

gtin Optional Global Trade Item Number (GTIN) is an identifier for trade items,
incorporated the ISBN, ISSN, ISMN, IAN (which includes the
European Article Number and Japanese Article Number) and
some Universal Product Codes, into a universal number space.

name Mandatory Human-readable name of the product or service.

quantity Mandatory The quantity of an item, with a maximum of 3 decimals. Example:

2 (pieces), 0.100 (grams).

unitPrice Mandatory Unit price of the line item. It does not take part in tax calculation.

labels Mandatory The array of labels. Each Label represents one of the Tax Rates
applied on the invoice item. Tax Items are calculated based on
totalAmount and applied labels as described in the Calculate
Taxes section. This field is mandatory (i.e. the caller must submit
a non-empty collection) for each item, even when the price is
0.00.

totalAmount Mandatory Gross price for the line item.

Payment
Payment

Field Optional/Mandatory Description

amount Mandatory Decimal amount of the payment

paymentType Mandatory Payment Type enumeration value: 0 - Other, 1 - Cash, 2 - Card, 3

- Check, 4 - Wire Transfer, 5 - Voucher, 6 - Mobile Money

Model
InvoiceRequest {
dateAndTimeOfIssue (string, optional),
cashier (string) Unicode MaxLength:50,
buyerId (string, optional) ASCII MaxLength:20,
buyerCostCenterId (string, optional) Unicode MaxLength:50,
invoiceType (string) = ['Normal', 'ProForma', 'Copy', 'Training', 'Advance'] (int) = [0,1,2,3,
transactionType (string) = ['Sale', 'Refund'] (int) = [0,1],
payment (Array[Payment]),
invoiceNumber (string, optional) Unicode MaxLength:60,
referentDocumentNumber (string, optional),
referentDocumentDT (string, optional),
options (inline_model, optional),
items (Array[Item])
}
Payment {
amount (number),
paymentType (string) = ['Other', 'Cash', 'Card', 'Check', 'WireTransfer', 'Voucher', 'MobileMo
}
inline_model {
omitQRCodeGen (string, optional) = ["0", "1"],
omitTextualRepresentation (string, optional) = ["0", "1"]
}
Item {
gtin (string, optional) MinLength:8 MaxLength:14,
name (string) Unicode MaxLength:2048,
quantity (number) Decimal(14,3) MinValue:0.001,
labels (Array[string]) MinLength:1,
unitPrice (number) Decimal(14,2),
totalAmount (number) Decimal(14,2)
}

Response

Headers
The following HTTP headers shall be returned in response

• RequestId: <RequestId from Request HTTP Headers>

Data Fields

Field Description
 Field Description

requestedBy UID of client's Secure Element digital certificate.

signedBy UID of SDC's Secure Element digital certificate.

sdcDateTime Local date and time in ISO 8601 format provided by E-SDC.

invoiceCounter Invoice Counter in format transactionTypeCounter/totalCounter

invoiceCounterExtension
For Example: 14/17NS

invoiceCounterExtension First letters of Invoice Type and Transaction Type of the invoice. NS for Normal
Sale, CR – Copy Refund, TS – Training Sale, etc.

invoiceNumber SDC Invoice Number in format requestedBy-signedBy-totalCounter

verificationUrl VerificationURL generated in the Create Verification URL process

verificationQRCode Base64 encoded byte array of GIF image created in the Create QR Code
process

journal Textual Representation of the invoice created in the Create a Textual

Representation of an Invoice (Receipt) process

totalCounter Total number of invoices signed by Secure Element. Returned by Sign Invoice
APDU command

transactionTypeCounter Total number of invoices for a requested type. Returned by Sign Invoice APDU
command

totalAmount Sum of all Items – total payable by the customer

encryptedInternalData Base64 encoded byte array returned by Sign Invoice APDU command

signature Base64 encoded byte array returned by Sign Invoice APDU command

taxItems Array of TaxItem entities

businessName Taxpayer Business Name obtained from digital certificate subject field

locationName Location Name obtained from digital certificate subject field

address Street address obtained from digital certificate subject field

tin Tax Identification Number obtained from digital certificate subject field
 district District obtained from digital certificate subject field

taxGroupRevision Revision of taxes used in the calculation

mrc Manufacturer Registration Code is mandatory for audit package sent to the tax
authority database, but it's optional for invoice response sent to POS. It always
has the format MakeCode-SoftwareVersionCode-DeviceSerialNumber.
Explanation: MakeCode -unique 2 characters received from the tax authority
during accreditation. SoftwareVersionCode - unique 4 characters received
from the tax authroty during accreditation. DeviceSerialNumber -
manufacturer serial number (max 32 characters) for each E-SDC installation. All
3 elements of MRC are mandatory.

messages (optional) Custom human-readable message that shall be printed or displayed by POS.

TaxItem
TaxItem represents tax liability on the invoice per one tax category.

Field Description

label Tax Label (A, F, G, N, P…)

categoryName Tax Category Name (e.g. VAT, Consumption)

categoryType Tax Category Type (0 - Tax on net, 1 - Tax on total, 2 - Amount per quantity)

rate Tax rate percentage for Label (i.e. 12.50%)

amount Tax amount calculated by E-SDC during invoice fiscalization

Model
InvoiceResult {
requestedBy (string, optional),
sdcDateTime (string),
invoiceCounter (string, read only),
invoiceCounterExtension (string, optional),
invoiceNumber (string, read only),
taxItems (Array[TaxItem], optional),
verificationUrl (string, optional),
verificationQRCode (string, optional),
journal (string, optional),
messages (string, optional),
signedBy (string),
encryptedInternalData (string),
signature (string, optional),
totalCounter (integer, optional),
transactionTypeCounter (integer, optional),
transactionTypeCounter (integer, optional),
totalAmount (number, optional),
taxGroupRevision (integer, optional),
businessName (string, optional),
tin (string, optional),
locationName (string, optional),
address (string, optional),
district (string, optional),
mrc (string, optional)
}
TaxItem {
categoryType (integer, optional),
label (string),
amount (number),
rate (number),
categoryName (string)
}

Examples
Below are examples of invoice requests and responses for all supported invoice and transaction types:

1.
Mapping
In case POS does not use Journal (generated by E-SDC or V-SDC) as a content for a fiscal receipt, but it
generates a custom-designed receipt instead, it must use the following element mappings:

2.
Normal Sale
This is an example of Normal Sale Invoice

3.
Normal Refund
This is an example of Normal Refund

4.
Advance Sale
This is an example of Advance Sale Invoice

5.
Advance Refund
This is an example of Advance Refund.

6.
Copy Sale
This is an example of Copy Sale

7.
Copy Refund
This is an example of Copy Refund

8.
Proforma Sale
 Proforma Sale
This is an example of Proforma Sale

9.
Proforma Refund
This is an example of Proforma Refund

10.
Training Sale
This is an example of Training Sale

11.
Training Refund
This is an example of Training Refund