REST API of licensed provider SBZ, for submission and retrieval of myDATA documents

Version 2.3 – May 2026

Contents

  1. Introduction
  2. Integration overview
  3. Authentication
  4. API Services
    1. Send invoice
    2. Request transmitted documents
    3. Payment signature
    4. Send payments
    5. Cancel delivery note
    6. Send file
  5. InvoiceDoc description
    1. Entity details
      1. Type
    2. Payment Method
      1. Provider’s Payment Signature
      2. Payment flow
    3. Document header
      1. Other General Delivery Details
    4. Document details
      1. Activity Undertaking Declaration (POL 1177/2018, Article 27)
    5. Taxes totals
    6. Document summary
    7. Income classification
    8. Expenses classification
    9. Details
      1. Issuer
      2. Counterpart
      3. Additionals
  6. Responses
    1. Data submission
    2. Data retrieval
  7. Errors
  8. Reference tables
  9. Document structure, examples and tools
  10. Versions history

 

    1. Introduction

      This document describes the above services and the technical specifications necessary to implement the relevant calls of the REST API interface. Specifically, for an enterprise using an information system that uses the relevant API, the features offered are:


      • Send data for the documents it issues.
      • Retrieve data of documents issued for it and submitted by the respective issuers to IAPR.


      The following technologies are used to establish a connection with the interface.

      • HTTPS – Secure HTTP
      • Web Service
      • REST API – REST interface required for data reporting process.
      • XML – eXtensible Markup Language

      The interface is accessible to any invoicing program capable of sending HTTP messages and creating schema- conformant XML, as specified in the present specification. In addition to the relevant data, the software should be able to simultaneously and automatically send the necessary information to identify the user through the same HTTPS call.

    2. Integration overview

      Requirements
      • All XML files must be well-formed, adhere to the schema (XSD), and be encoded in UTF-8.
      • Be secured using authentication described in next chapter.

      Certification Process

      1. Create an account on https://api.sbz.gr/register.php and contact our technical department at support@sbzsystems.com to activate your trial account.
      2. Develop and test the APIs.
      3. Check and make sure you do not receive any errors. Testing for this API consists of self-tests conducted using your test account in a sandbox environment.
      4. Integration testing. When you are ready to test, contact the SBZ systems Integration Specialist assigned to your account for access to the guides and testing tools.
      5. When everything goes right then your setup is ready, and you will receive the production API- KEY and account details.
      6. After review by SBZ staff, an electronic contract is issued.


      After launch

      • You must continue to adhere to our Terms and Conditions.
      • You should monitor your API connection for any warning or errors.
      • Report any warning or errors received in any response and how they have been resolved.

 

    1. Authentication

      Each call must contain the following headers in the form of pair-values, which is necessary for user identification. In case of incorrect information, the user will receive an error message. The following headers are required:

      Key Data Type Value Required Description
      API-KEY String {API-KEY} YES The API_KEY of your sandbox or production account
      Content-Type String application/xml; charset=utf-8 YES

      By identifying the user through the headers, the interface will also gain access to the VAT number the user had stated when registering, so that it would not be necessary to submit it in every call. Please note each call to a new vat number must first be authorized from our side.

 

  1. API Services

    1. Send invoice

      The call has the following characteristics:
      • /sendinvoice.php (POST)
      • Body in xml format containing the InvoicesDoc element, which contains one or more documents. The structure of the InvoicesDoc element is described by type
        AadeBookInvoiceType

      Endpoints

      Production environment

      https://api.sbz.gr/sign/sendinvoice.php?action=production

      Sandbox environment

      https://api.sbz.gr/sign/sendinvoice.php?action=sandbox

    2. Request transmitted documents

      The call has the following characteristics:
      • /requesttransmitteddocs.php (GET)
      • With this method you can retrieve documents that have been submitted to myData. The method returns the documents that have the issuer’s VAT number of the specified parameter.

      Field Type Required Description
      issuerVAT xs:long Yes Issuer VAT number (query parameter)
      mark xs:long No Unique Invoice Registration Number (Mark). Forwarded to AADE as Mark
      maxMark xs:long No If set, returns records with MARK less than or equal to this value

       

      Remarks:

      • The SBZ API forwards to AADE the parameters issuervat, Mark and maxMark (Provider RequestTransmittedDocs method).
      • A valid Api-Key is required. The issuer VAT must belong to an entity covered by the Api-Key.
      • AADE parameters nextPartitionKey / nextRowKey are not currently forwarded by the SBZ call.


      Endpoints

      Production environment

      https://api.sbz.gr/sign/requesttransmitteddocs.php?issuerVAT={issuerVAT}&mark={mark}&maxMark={maxMark}&action=production

      Sandbox environment

      https://api.sbz.gr/sign/requesttransmitteddocs.php?issuerVAT={issuerVAT}&mark={mark}&maxMark={maxMark}&action=sandbox

    3. Payment signature

      The call has the following characteristics:
      • /paymentsignature.php (POST)
      • Main part in xml format containing the ERPpayment node, which contains a payment signature request for use with a POS card terminal.

      Field Type Required Description
      issuerVat xs:long Yes Entity VAT number
      issueDate xs:date Yes Invoice’s issue date
      branch xs:int Yes Branch number
      invoiceType xs:string Yes Type of invoice. The possible values are described in the Reference tables.
      The documents 8.5, 11.4, 5.1, 5.2 send to the terminal a refund transaction.
      The document 8.4 is a pre-loading transaction unless preload is set
      InitialTransaction xs:string No Mandatory only in case of refund
      series xs:string Yes Series of invoices. If no invoice series is issued, the field must have the value 0 It must not contain the character “-“
      aa xs:string Yes serial number of invoice. It must be unique per type of document 8.1
      invoicemark xs:long No Unique Invoice Registration Number
      amount xs:decimal Yes Payment amount
      totalNetValue xs:decimal Yes Total net value
      totalVatAmount xs:decimal Yes Total amount of VAT
      totalGrossValue xs:decimal Yes Total gross value
      terminalid xs:string Yes Payment instrument alias as defined in api.sbz.gr
      tipAmount xs:decimal No Tip value. If not defined enter 0
      instalments xs:int No Number of installments. If not defined, enter 0
      preload xs:int No 1: Pre-load transaction, 2: Check pre-loaded Deploy the line only when needed.
      PaymentType xs:int No 0: Card payment, 1: IRIS. If not defined, is 0

      Response

      Field Type Description
      SigningAuthor xs:long Electronic invoicing provider’s code
      Signature xs:date Payment Signature of the Electronic Document Issuance Service Provider
      Uid xs:int Invoice identifier
      Timestamp xs:int Time format Y-m-d\TH:i:s
      statusCode xs:string Result of call
      Comments xs:string Comments
      pos_transactionId xs:string Terminal transaction ID
      pos_answer xs:string Returned values are preloaded, success, failed
      pos_transactionText xs:string It is not returned by all terminals and is intended for informational purposes only. An additional unique number from a terminal, if exists.
      pos_TerminalID xs:string Terminal ID
      pos_PaymentType xs:int 0: Card payment, 1: IRIS payment


      Remarks:

      • The differentiation between simultaneous and heterochronous transactions lies in the use or not of SendPayments
      • For heterochronous transactions SendPayments is used after first calling PaymentSignature
      • For simultaneous transactions SendInvoice is used after first calling PaymentSignature
      • The reference VAT number is sent via the entityVatNumber field.


      Endpoints

      Production environment

      https://api.sbz.gr/sign/paymentsignature.php?action=production

      Sandbox environment

      https://api.sbz.gr/sign/paymentsignature.php?action=sandbox

    4. Send payments

      The call is made when we need to issue a receipt or POS return receipt. It is sent to myDATA with SendPaymentsMethod and receives an invoiceMark which is returned on a successful call. A call has the following characteristics:

      • /sendpayments.php (POST)
      • Headers as referred to in paragraph 3
      • Main part in xml format consisting of one or more PaymentMethodType elements. The type is described by the following diagram

      Field Type Required Description
      issuerVat xs:long Yes Entity VAT number
      issueDate xs:date Yes Invoice’s issue date
      branch xs:int Yes Branch number
      invoiceType xs:string Yes Type of invoice. The possible values are described in the Reference tables. The documents 8.5, 11.4, 5.1, 5.2 send to the terminal a refund transaction. The document 8.4 pre-loading transaction unless preload is set
      InitialTransaction xs:string No Mandatory only in case of refund
      series xs:string Yes Series of invoices. If no invoice series is issued, the field must have the value 0 It must not contain the character “-“
      aa xs:string Yes serial number of invoice. It must be unique per type of document 8.1
      invoicemark xs:long No Unique Invoice Registration Number
      amount xs:decimal Yes Payment amount
      totalNetValue xs:decimal Yes Total net value
      totalVatAmount xs:decimal Yes Total amount of VAT
      totalGrossValue xs:decimal Yes Total gross value
      terminalid xs:string Yes Payment instrument alias as defined in api.sbz.gr

      Response

      Field Type Required Description
      invoiceMark xs:long Yes Document Unique registration number
      paymentMethodMark xs:long No Unique registration number of payment method
      entityVatNumber xs: string No VAT number of the Entity
      paymentMethodDetails PaymentMethodDetailType Yes Payment Methods


      Remarks:

      • The field paymentMethodMark is composed by the service
      • The reference VAT number is sent via the entityVatNumber field,
      • The PaymentMethodDetailType object is discussed in detail in paragraph 5.2
      • When using the method, at least one PaymentMethodDetailType object per document must be of type POS
      • The total amount per PaymentMethodDetailType object must be equal to the totalGrossValue of the document to which the invoiceMark refers.


      Endpoints

      Production environment

      https://api.sbz.gr/sign/sendpayments.php?action=production

      Sandbox environment

      https://api.sbz.gr/sign/sendpayments.php?action=sandbox

    5. Cancel delivery note

      The call is made when we need to cancel a delivery note. It is sent to myDATA with the CancelDeliveryNote method and receives a cancellationMark, which it returns upon a successful call. It has the following characteristics:

      • /canceldeliverynote.php (POST)
      • Headers as referred to in paragraph 3
      • Fields are defined as parameters, for example 



      Field Type Required Description
      mark xs:long Yes Unique registration number of the document to be canceled
      entityVatNumber xs:string Yes Entity VAT number

       

      Response

      Field Type Description
      cancellationMark xs:long Unique Cancellation Number
      statusCode xs: string Status Code


      Remarks:

      • If successful, the cancellation receives its own mark, which is returned to the user, and the delivery note is considered canceled. If it fails, an error message is returned.
      • The reference VAT number is sent via the entityVatNumber field.
      • Only documents of type 9.3 can be canceled with the CancelDeliveryNote method.


      Endpoints

      Production environment

      https://api.sbz.gr/sign/canceldeliverynote.php?action=production

      Sandbox environment

      https://api.sbz.gr/sign/canceldeliverynote.php?action=sandbox

    6. Send file

      The call has the following characteristics:
      • /sendfile.php (POST)
      • Headers as referred to in paragraph 3
      • Body (multipart/form-data)

      Field Type Required Description
      issuerVat xs:long Yes Entity VAT number
      invoiceMark xs:string Yes Unique Invoice Registration Number
      file xs:string Yes PDF or JPG file (max 300 KB)

       

      Example

      Endpoints

      Production environment

      https://api.sbz.gr/sign/sendfile.php?action=production

      Sandbox environment

      https://api.sbz.gr/sign/sendfile.php?action=sandbox

      Remarks

      • The document mark must already exist in the system before uploading.
      • Each upload costs units: 1 unit per 20 KB (e.g. 100 KB = 5 units).
      • Uploading the same mark again is prohibited.

  2. InvoiceDoc description

    This section describes in detail the contents of an invoice (type AadeBookInvoiceType). The structure of the element is as follows:



    Field Type Required Description Valid values
    uid xs:string No Invoice identifier Length = 40 Filled in only by Provider
    mark xs:long No Unique Invoice Registration Number Filled in only by Provider. Unique Invoice Registration Number
    cancelledByMark xs:long No Unique Invoice Cancelation Number Filled in only by Provider
    authenticationCode xs:string No Authentication Code Filled in only by Provider
    transmissionFailure xs:byte No Provider communication failure or ERP data transmission failure Allowed value: 1. Details in the Reference tables
    issuer PartyType No Invoice issuer
    counterpart PartyType No Invoice counterpart
    invoiceHeader InvoiceHeaderType Yes Document header
    paymentMethods PaymentMethodDetailType No Payment Methods
    invoiceDetails InvoiceRowType Yes Invoice lines
    taxesTotals TaxesType No Total taxes Contains all taxes except VAT. If user uses this element, taxes will not exist in invoiceDetails
    invoiceSummary InvoiceSummaryType Yes Document summary
    API_InvoiceDetails API_InvoiceDetailsType Yes Document details


    Remarks

    • Complex types PartyType, PaymentMethodDetailType, InvoiceHeaderType, InvoiceRowType, TaxTotalsType, InvoiceSummaryType and API_InvoiceDetailsType are described later in this section.
    • The transmissionFailure field indicates a communication failure (optional, xs:byte). Allowed value: 1 — Failure of communication between the entity and the provider during invoice issuance/transmission. Details in the Reference tables.


    1. Entity details


      The issuer and the counterpart are elements of type PartyType.



      Field Type Required Description Valid values
      vatNumber xs:string Yes VAT number Any valid VAT number
      Country xs:string Yes Country code Country codes (ISO 3166)
      branch xs:int Yes Branch number Minimum value = 0
      If the branch is the headquarters or does not exist, the branch field must have the value 0.
      Name xs:string No Name
      Address AddressType No Type
      documentIdNo xs:string No Official document number Maximum 100 characters
      Valid only in the case of a tax free document (special invoice category = 4)
      supplyAccountNo xs:string No Electricity Supply Number Maximum 100 characters
      Valid only for fuel documents

      Remarks

      • The country code is two characters and comes from the respective country list of countries as described in ISO 3166.
      • In case the issuer’s establishment is the headquarters or does not exist, the branch field must have the value 0
      • For the publisher, the Name and Address details are not accepted in cases involving an entity within Greece (GR). For the receiver, the element Names are not accepted in the event that it concerns an entity within of Greece (GR)
      • The official document number is only allowed in the case of transmission of documents belonging to the Special Category of Tax free Document (the field of the document header specialInvoiceCategory has the value 4), and can be any official identification document (eg number passport) of the recipient of the document.
      • The Electricity Supply number is only allowed in the case of transmission of fuel documents (the field of the document heading fuelInvoice has the value true – only accepted for transmission by providers) and is information of the recipient of the document.
      • Address
      • The address of the issuer and the counterpart are elements of type AddressType.
        Field


      1. Type

        Required


        Field Type Required Description
        Street xs:string No Street
        number xs:string No Number
        postalCode xs:string Yes Postal Code
        City xs:string Yes City

         

    2. Payment Method

      The payment method is an element of type PaymentMethodDetailType and its structure is described below:


      Field Type Required Description Valid values
      type xs:int Yes Payment method Min value = 1 Max value = 8. Possible values are described in the
      Reference tables (Payment methods)
      amount xs:decimal Yes Amount Min value = 0 Decimal digits = 2 Field amount may refer to fraction of the document’s total value
      paymentMethodInfo xs:string No Information Field paymentMethodInfo contains additional information for the specified type
      transactionId xs:string No Transaction number from POS terminal Passed on in the case of payments with type = 7
      tid xs:string No POS terminal TID Passed on in the case of payments with type = 7


      Remarks

      • The values of the type field are described in the corresponding appendix table
      • The amount field may correspond to a part of the total value of the document
      • The Information field may contain additional information about the specific type (e.g. Bank Account No.)
      • The ProvidersSignature field is of type ProviderSignatureType, which is described below, and is transmitted for payments with type = 7 when transmission is done via the provider channel


      1. Provider’s Payment Signature


        The ProvidersSignature field is an element of type ProviderSignatureType and its structure is described below:


        Field Type Required Description
        SigningAuthor xs:string Yes Number of approval of the Electronic Invoicing Provider
        Signature xs:string Yes Signature

         

      2. Payment flow

        1. Call to paymentsignature.php with an XML request:

        The terminal ID is associated with the terminal’s TID in the api.sbz.gradmin panel, under settings, payment terminals.

        1. The API communicates with the POS and waits for a response
        2. Upon completion of the transaction, an XML is returned:

        1. Integration into sendinvoice.php and sending

    3. Document header




      Field Type Required Description Valid values
      Series xs:string Yes Invoice series If no document series is issued, the series field must have the value 0.
      Must not contain the character “-”
      Aa xs:string Yes Invoice’s serial number Maximum digits = 5
      issueDate xs:date Yes Invoice’s issue date
      invoiceType xs:string Yes Invoice type The possible values are described in the Reference tables
      vatPaymentSuspension xs:boolean No VAT payment suspension
      currency xs:string No Currency Currency code (ISO4217)
      exchangeRate xs:decimal No Exchange rate Min value = 0 Decimal digits = 5 The currency exchange rate against euro. It should be completed only when the currency is not EUR.
      correlatedInvoices xs:long No Correlated invoices The element is a list of strings containing the MARK of the associated invoices identifiers
      correlatedInvoicesLabel xs:string No Correlated invoices Names Required only when using correlatedInvoices. The element is a text field containing the Friendly Name of the associated invoices
      selfPricing xs:boolean No Self-billing indicator
      dispatchDate xs:date No Dispatch date
      dispatchTime xs:time No Dispatch time
      vehicleNumber xs:string No Vehicle number
      movePurpose xs:int No Purpose of movement Min value = 1 Max value = 20 Values described in the
      Reference tables
      movePurposeLabel xs:string No Purpose of Movement Description
      fuelInvoice xs:boolean No Fuel document (indication)
      specialInvoiceCategory xs:int No Special Category of Document Min value = 1 Max value = 13. Values in the
      Reference tables (Special invoice category)
      isDeliveryNote xs:boolean No Delivery note indicator
      multipleConnectedMarks No Multiple connected Unique Invoice Registration Numbers
      tableAA Yes Table ID Acceptable only for document type 8.6 – Maximum permissible length 50
      totalCancelDeliveryOrders xs:boolean No Indicator of total cancellation of Order Notes Accepted only for document type 8.6


      Remarks

      • The exchangeRate field is the currency exchange rate against the euro. It should be completed only when the currency is not EUR.
      • The currency code comes from the corresponding list according to the ISO4217 standard.
      • The correlatedInvoices element is a list and contains the MARK of the correlated documents
      • If no document series is issued, the series field must have the value 0
      • The selfPricing field indicates whether it is a Self-billing document
      • The possible values of the movePurpose and invoiceType fields are described in detail in the Reference tables
      • The fuelInvoice field indicates whether it is a liquid fuel sales document and submission is allowed only for providers.
      • The possible values of the specialInvoiceCategory field are described in detail in the Reference tables
      • The possible values of the invoiceVariationType field are described in detail in the Reference tables. The field is not allowed for transmission via the provider channel. Further details on how they are used from a business perspective are described in the relevant business document.
      • The otherCorrelatedEntities field (Other correlated entities) is a list of type EntityType
      • The structure of type otherCorrelatedEntities is described below
      • The structure of type otherDeliveryNoteHeader is described below
      • The isDeliveryNote field indicates whether the document is also a delivery note (e.g. document type 1.1 – Sales Invoice; if isDeliveryNote = true, it is also a movement note and additional movement details must also be sent)
      • The otherMovePurposeTitle field is completed when movePurpose = 19 (Other Movements) is selected and defines the title of the other movement
      • The thirdPartyCollection field indicates whether the business using Payment Means as a Payment Services User collects on behalf of third parties (document type 8.4 – POS Receipt) or returns transaction amounts on behalf of third parties (document type 8.5 – POS Return receipt)


      1. Other General Delivery Details




        Field Type Required Description Accepted values
        loadingAddress AddressType Yes Loading Address It is completed for documents that are delivery notes (e.g., 9.3) or invoices and delivery notes (isDeliveryNote = true)
        deliveryAddress AddressType Yes Delivery Address It is completed for documents that are delivery notes (e.g., 9.3) or invoices and delivery notes (isDeliveryNote = true)
        startShippingBranch xs:int No Dispatching Start Location (Issuer) It is completed for documents that are delivery notes (e.g., 9.3) or invoices and delivery notes (isDeliveryNote = true)
        completeShippingBranch xs:int No Receiving End Location (Recipient) It is completed for documents that are delivery notes (e.g., 9.3) or invoices and delivery notes (isDeliveryNote = true)

        Remarks:

        • The field loadingAddress is of type AddressType, which type is elaborated in a previous corresponding paragraph (Entity Address)
        • The field deliveryAddress is of type AddressType, which type is elaborated in a previous corresponding paragraph (Entity Address)
        • The field startShippingBranch specifies the branch from which the circulation begins, in case the circulation starts from a branch (installation) of the issuer of the document, which is different from the issuer’s branch for the delivery note
        • The field completeShippingBranch specifies the branch where the circulation will be completed, in case the circulation will be completed at a branch (installation) of the recipient of the document, which is different from the recipient’s branch for the delivery note


    4. Document details





      Field Type Required Description Valid values
      lineNumber xs:int Yes Line number Min value = 1
      lineCode xs:string No Item code
      recType xs:int No Line Type Min value = 1 Max value = 7. Values in the
      Reference tables (Invoice detail type / line type)
      fuelCode FuelCodes No Fuel Code Fuel Codes list Values described in the
      Reference tables
      quantity xs:decimal No Quantity Min value = 0 Default = 1
      lineQuantity xs:decimal No Quantity only for use by the provider API if the quantity does not exist Min value = 0 Default = 1
      classificationIdentifier xs:string For B2G only No CPV code
      measurementUnit xs:int No Unit of quantity Min value = 1 Max value = 7. Values in the
      Reference tables
      measurementUnitLabel xs:string No Required only when measurementUnit exists
      invoiceDetailType xs:int No Self-billing remark 1,2
      Values described in the Reference tables
      lineUnitPrice xs:decimal Yes The unit price
      totalNetPriceBeforeDiscount xs:decimal Yes Total price of all (units x quantity)
      totalDiscountValue xs:decimal Yes Total Discount Value Minimum value = 0
      netValue xs:decimal Yes Net value Min value = 0 Decimal digits = 2
      vatCategory xs:int Yes VAT category Min = 1, Max = 8 Values described in the Reference tables
      For cases where VAT is not applied, the vatCategory field will have the value of 8
      vatCategoryPercent xs:decimal Yes VAT category Description (ex. 24.00)
      vatAmount xs:decimal Yes VAT amount Min value = 0 Decimal digits = 2
      vatExemptionCategory xs:int No VAT exemption category Min value = 1 Max value = 31 Values described in the
      Reference tables
      Required if the vatCategory indicates a 0% VAT rate
      dienergia ShipType No Article 27 of POL 1177/2018
      discountOption xs:boolean No Discount option False / True
      withheldAmount xs:decimal No Withholding tax amount Min value = 0 Decimal digits = 2
      The field is completed when the corresponding tax exists (even if it is a percentage)
      withheldPercentCategory xs:int No Withholding tax rate category Min value = 1 Max value = 12 Values described in the
      Reference tables
      stampDutyAmount xs: decimal No Amount of digital transaction fees Min value = 0 Decimal digits = 2
      stampDutyPercentCategory xs:int No Digital Transaction Fee Category 1, 2, 3
      Values described in the Reference tables
      feesAmount xs:decimal No Fees amount Min value = 0 Decimal digits = 2
      The fields are completed when the corresponding tax exists (even if it is a percentage)
      feesPercentCategory xs:int No Fees rate category Min value = 1 Max value = 22 Values described in the
      Reference tables
      otherTaxesPercentCategory xs:int No Other taxes rate category Min value = 1 Max value = 30 Values described in the
      Reference tables
      otherTaxesAmount xs:decimal No Other taxes amount Min value = 0 Decimal digits = 2
      The fields are completed when the corresponding tax exists (even if it is a percentage)
      deductionsAmount xs:decimal No Deductions amount Min value = 0 Decimal digits = 2
      lineDescription xs:string
      lineComments xs:string No Line comments Filled in by user and used for information purposes only
      incomeClassification IncomeClassificationType No Income classification
      expensesClassification ExpensesClassificationType No Expenses classification
      itemDescr xs:string No Item description Max 300 chars Acceptable only in the case of documents of the special tax free category


      Remarks

      1. The possible values for the fields measurementUnit, invoiceDetailType, vatCategory, vatExemptionCategory, withheldPercentCategory, stampDutyPercentCategory, feesPercentCategory and otherTaxesPercentCategory are detailed in the respective
        Reference tables
      2. The field vatExemptionCategory is necessary in the event that vatCategory indicates a 0% VAT rate category
      3. For cases of accounting entries where VAT is not applied, the vatCategory field will have the value 8
      4. Line comments are filled in by the user and are used for information purposes to the service
        1. In the case of sending lines with recType = 2 (VAT fee line) and/or recType = 3 (Other Taxes line with VAT), it will be allowed at the same time, if desired, to send withholding/fees /other taxes/stamp/deductions and at document level and not necessarily per document summary line. In the cases of these lines, the amounts corresponding to VAT fees (recType = 2) or other taxes (recType =3 respectively, they will be sent to the field of the net value of the line (netValue), while the corresponding fields fee amount (feesAmount) or amount of other taxes (otherTaxesAmount) will not be filled. Also, other types of taxes/fees/retentions/stamps are not allowed to be sent on these lines (eg on a line with recType = 2 other taxes/deductions/withholding/stamp are not allowed on that line).
        2. Sending with recType = 7 (negative sign of values) is allowed only in the case of transmission of documents 17.3, 17.4, 17.5 and 17.6 and in this way it is indicated that the line values are negative (in the respective value fields the values are written in their absolute/positive values). It is noted that in the sums of the values in the Document Summary section (InvoiceSummaryType) the sums of the absolute values of the corresponding values of the lines will be transmitted regardless of whether there are lines that bear or not the indication recType = 7.

      5. The possible values for the fuelCode field are described in detail in the corresponding Reference tables. It is allowed to send it only in the case of providers and if it is a document Fuel (invoiceHeaderType.fuelInvoice = true). The value 999 is used in the event that in a document other than fuel there is the need for invoicing and other charges. Only one line with this code is allowed per document and the net value of that line should be less than or equal to the sum of the net value of the remaining fuel codes of the document.


      1. Activity Undertaking Declaration (POL 1177/2018, Article 27)

        Activity undertaking declaration is an element of type ShipType:




        Field Type Required Description
        applicationId xs:string Yes Activity Undertaking Declaration Number
        applicationDate xs:date Yes Application date
        doy xs:string No Tax Return Filing DOY
        shipID xs:string Yes Ship details



    5. Taxes totals

      Element TaxTotalsType which contains the total taxes has the following structure:



      Field Type Required Description Valid values
      taxType xs:byte Yes Type of tax 1 = Withheld taxes 2 = Fees 3 = Other taxes 4 = Digital transaction fee 5 = Deductions
      taxCategory xs:byte Yes Tax category See tables 8.4 – 8.8 of appendix
      underlyingValue xs:decimal No Underlying value to which the tax refers Minimum value = 0
      Decimal digits = 2
      percentage xs:decimal For B2G only Yes Deduction, withholding rate Minimum value = 0
      Decimal digits = 2
      reason xs:string For B2G only Yes Deduction, withholding description
      taxAmount xs:decimal Yes Tax amount Minimum value = 0
      Decimal digits = 2
      Id xs:byte No Line number
      ReducesPayable xs:boolean No Reduces the Payable amount Default = False
      taxTypeLabel xs:string No Description of the service

       

    6. Document summary





      Field Type Required Description Valid values
      totalNetValue xs:decimal Yes Total net value Minimum value = 0
      Decimal digits = 2
      totalVatAmount xs:decimal Yes Total amount of VAT Minimum value = 0
      Decimal digits = 2
      totalWithheldAmount xs:decimal Yes Total withholding taxes amount Minimum value = 0
      Decimal digits = 2
      totalFeesAmount xs:decimal Yes Total fees amount Minimum value = 0
      Decimal digits = 2
      totalStampDutyamount xs:decimal Yes Total digital transaction fee Minimum value = 0
      Decimal digits = 2
      totalOtherTaxesAmount xs:decimal Yes Total other taxes amount Minimum value = 0
      Decimal digits = 2
      totalDeductionsAmount xs:decimal Yes Total deductions amount Minimum value = 0
      Decimal digits = 2
      totalGrossValue xs:decimal Yes Total gross value Minimum value = 0
      Decimal digits = 2
      incomeClassification IncomeClassificationType No Income classification
      expensesClassification ExpensesClassificationType No Expenses classification


      Remarks

      • Elements incomeClassification and expensesClassification contain the sums of all combinations of fields classificationType and classificationCategory that exist in the details of the invoice.
      • All tax summary fields contain the summary of corresponding taxes of the details of the invoice or in the taxesTotals element.
      • totalGrossValue = totalNetValue + totalVatAmount + totalFeesAmount + totalStampDutyamount + totalOtherTaxesAmount – totalWithheldAmount


    7. Income classification

      Element IncomeClassificationType which contains the income classification has the following structure:




      Field Type Required Description Valid values
      classificationType xs: string Yes Classification type Possible values of fields are described in the appendix
      classificationCategory xs: string Yes Classification category Possible values of fields are described in the appendix
      amount xs:decimal Yes amount Min value = 0 Decimal digits = 2
      id xs:byte No Serial number of classification Used for serial numbering (1,2,3… etc.) of the classifications of a row


      Remarks

      • Due to sending documents through a Provider, it is not necessary to send a classification.
      • The id field is used for serial numbering (1,2,3…etc) of the designations within a line


    8. Expenses classification

      Element ExpensesClassificationType which contains the income classification has the following structure:




      Field Type Required Description Valid values
      ClassificationType xs: string Yes Classification type Possible values of fields are described in the appendix
      classificationCategory xs: string Yes Classification category Possible values of fields are described in the appendix
      amount xs:decimal Yes amount Minimum value = 0
      Decimal digits = 2
      id xs:byte No Serial number of classification Used for serial numbering (1,2,3… etc.) of the classifications of a row


      Remarks

      • Due to sending documents through a Provider, it is not necessary to send a classification.


    9. Details

      The issuer and the counterpart are elements of type PartyType.




      Field Type Required Description Valid values
      API_Issuer API_IssuerType Yes API_Issuer
      API_Counterpart API_CounterpartType Yes API_Counterpart
      API_Additionals API_AdditionalsType Yes API_Additionals



      1. Issuer

        Element API_IssuerType which contains the following structure:




        Field Type Required Valid values
        IssuerName xs: string Yes Invoice fields described in «Document structure, examples and tools
        »
        IssuerProfession xs: string Yes Invoice fields described in «Document structure, examples and tools
        »
        IssuerTaxOffice xs: string Yes Invoice fields described in «Document structure, examples and tools
        »
        IssuerAddressStreet xs: string Yes Invoice fields described in «Document structure, examples and tools
        »
        IssuerAddressNumber xs: string Yes Invoice fields described in «Document structure, examples and tools
        »
        IssuerAddressPostalCode xs: string Yes Invoice fields described in «Document structure, examples and tools
        »
        IssuerAddressCity xs: string Yes Invoice fields described in «Document structure, examples and tools
        »
        IssuerAddressCountry xs: string Yes Invoice fields described in «Document structure, examples and tools
        »
        IssuerPhone xs: string No Invoice fields described in «Document structure, examples and tools
        »
        IssuerFax xs: string No Invoice fields described in «Document structure, examples and tools
        »
        IssuerEmail xs: string Yes Invoice fields described in «Document structure, examples and tools
        »
        IssuerWebSite xs: string No Invoice fields described in «Document structure, examples and tools
        »
        IssuerRegistryNumber xs: string No Invoice fields described in «Document structure, examples and tools
        »
        IssuerEmtyLine xs: string No Invoice fields described in «Document structure, examples and tools
        »
        IssuerEmtyLine2 xs: string No Invoice fields described in «Document structure, examples and tools
        »

         

      2. Counterpart

        Element API_ConterpartType which contains the following structure:




        Field Type Required Valid values
        CounterpartCode xs: string No Invoice fields described in «Document structure, examples and tools
        »
        CounterpartName xs: string Yes Invoice fields described in «Document structure, examples and tools
        »
        CounterpartVat xs: string No Used on demand only if invoiceType is 11.1 or 11.2
        CounterpartProfession xs: string Yes Invoice fields described in «Document structure, examples and tools
        »
        CounterpartTaxOffice xs: string Yes Invoice fields described in «Document structure, examples and tools
        »
        CounterpartAddressStreet xs: string Yes Invoice fields described in «Document structure, examples and tools
        »
        CounterpartAddressNumber xs: string Yes Invoice fields described in «Document structure, examples and tools
        »
        CounterpartAddressPostalCode xs: string Yes Invoice fields described in «Document structure, examples and tools
        »
        CounterpartAddressCity xs: string Yes Invoice fields described in «Document structure, examples and tools
        »
        CounterpartAddressCountry xs: string No Invoice fields described in «Document structure, examples and tools
        »
        CounterpartPhone xs: string No Invoice fields described in «Document structure, examples and tools
        »
        CounterpartEmail xs: string No Invoice fields described in «Document structure, examples and tools
        »



      3. Additionals

        Element API_AdditionalsType which contains the following structure:




        Field Type Required Valid values
        DocumentLabel xs: string Yes The description of the payment type, described in «Document structure, examples and tools»
        DocumentComments xs: string No The description of the payment type, described in «Document structure, examples and tools»
        paymentMethodInvoiceLabel xs: string No The description of the payment type, described in «Document structure, examples and tools»
        Logo_ID xs: string No Default ID = 1. Can be set on API Portal
        DispatchPlaceFrom xs: string No The dispatch origin place
        DispatchPlaceTo xs: string No The dispatch destination place
        DispatchMethod xs:string No Shipping method
        docTime xs: string No Time of issuance of document
        b2g xs:boolean For B2G only Yes Yes, no on whether it concerns a document payable to the government
        buyerIdentifier xs: string For B2G only Yes The contracting authority
        contractReference xs: string For B2G only Yes Registry Online Authorisation Reference Number
        projectReference xs: string For B2G only Yes Contract identifier

         

  3. Responses

    1. Data submission

      When the user uses a submission service (SendInvoices), he/she will receive a ResponseDoc object in xml format. The object contains a list of response elements, one for each entity submitted.




      Field Type Description
      Index xs: int Entity’s line number inside the submitted xml
      invoiceUid xs: string Invoice identifier
      invoiceMark xs: long Unique Invoice Registration Number
      AuthenticationCode xs: string Signature
      InvoiceUrl xs: string The url to get the invoice
      myDATAUrl xs: string The link leading to the IAPR document
      Errors ErrorType Errors list
      units xs: long Units available for use
      statusCode xs: string Status Code

       

      Remarks

      • The type of response (success or failure) is determined by the value of the statusCode field.
      • If successful, the statusCode field has value Success and the answer contains the corresponding values for the invoiceUid and invoiceMark fields for each entity submitted.
      • In case of failure, the statusCode field has a value corresponding to the type of error, and the response includes a list of ErrorType error data for each entity that failed to submit. All errors by entity are in the same category that characterizes the response.
      • Field invoiceUid is returned only when the submitted entity was invoice.
      • Field classificationMark is returned only when the submitted entity was classification.
      • The authenticationCode field returns if the submission was made through a provider
      • The cancellationMark field returns only if the request was for cancellation of a document
      • The invoiceMark field contains the mark of the submitted invoice in case of submitted invoices and the mark of the invoice to which the submitted markings related, in case of submitted markings
      • The qrUrl field returns only on submissions of document types 1.1 to 11.5


    2. Data retrieval

      When the user calls a data request service (RequestTransmittedDocs), he/she will receive a RequestedDoc object in xml format. The object will include the list of requested invoices for the issueerVatNumber given as parameter, as well as the continuationToken element (in cases where data exceeds the permissible limit and is retrieved partially).




      Field Type Required Description
      nextPageKey nextPageKey No Element for partial results retrieval If a nextPageKey is returned, then execute this url by the service to receive the next results
      counterpartVatNumber Yes
      InvoiceMark Yes
      invoiceUid AadeBookInvoiceType Yes
      invoiceAuthenticationCode CancelledInvoiceType Yes
      invoiceBranchCode xs:long Yes
      invoiceType xs:long Yes
      invoiceSeries xs:date Yes
      incomeAa InvoiceIncomeClassificationType Yes
      invoiceDateIssued InvoiceExpensesClassificationType Yes
      invoiceTotalNetValue xs:string Yes
      invoiceTotalVatValue xs:string Yes
      invoiceTotalGrossValue xs:string Yes
      invoiceUrl xs:string Yes pdf document


      Remarks:

      • If the continuationToken element is returned, the nextPartitionKey and nextRowKey fields will be filled by the service and are used in the next call of the same method that had been set by the user
      • The types AadeBookInvoiceType, InvoiceIncomeClassificationType,
      • InvoiceExpensesClassificationType and PaymentMethodType are described in previous paragraphs


  4. Versions history
    • Version 1.0
      • Initial release
    • Version 1.2
      • Minor changes
    • Version 1.3
      • POS support
      • Delivery notes support
    • Version 1.4
      • B2G support
    • Version 1.5
      • Catering order notes
    • Version 1.6
      • Invoice delivery note
      • Documentation corrections
    • Version 1.7
      • Error response enrichment
      • Mark delivery notes in the administration
      • Mark order notes in the administration
    • Version 1.8
      • Exported reports improvement
    • Version 1.9
      • Added delivery note cancellation
    • Version 2.0
      • IRIS support
    • Version 2.1
      • Search in the terminal list by tid
      • Send email when a new payment terminal is registered
      • Bulk export of documents and their lines to Excel and XML
    • Version 2.2
      • Ability to upload document as PDF or JPG
    • Version 2.3
      • Documentation and examples improvements