REST API SBZ – Document Structure, Examples and Tools

← API Documentation

Contents

  1. Document structure
  2. XML examples
    1. Create document
    2. Request transmitted documents
    3. Payment signature request
  3. Special characters
  4. API portal
    1. Document verification
    2. Document XML based on EN 16931-1:2017
  5. POS – Cash Register Integration
  6. Provider’s obligations

 

  1. Document structure
    A document has the following structure
  2. XML examples
    1. Create document
      Request
      Method POST with HEADER (API-KEY and CONTENT-TYPE)…/sendinvoice.php


      Response

      You can run more tests using Postman
    2. Request transmitted documents

      Request
      Method GET with HEADER (API-KEY and CONTENT-TYPE)../requesttransmitteddocs.php

      Response

    3. Payment signature request
      Request
      Method POST with HEADER (API-KEY and CONTENT-TYPE)../paymentsignature.php


      Response
  3. Special characters
    The following characters are not accepted in any XML text field and must be sent as shown.

    Character Correct way to send
    < Not supported
    > Not supported
    & Not supported
  4. API portal
    Note: the API portal is available after certification. Sign in with the credentials we send you after certification.In the portal you have these options:
    • Upload your company logo for issued documents and set it by changing logo_id.
    • Add units by buying a package with a credit or debit card.
    • View all documents issued via API.
    • Download all documents issued via API.
    • Check your balance.
    • Get the latest REST API version.
    1. Document verification
      To verify an issued document, on the home page open Document verification then enter the MARK or authentication code and click the search icon.
    2. Document XML based on EN 16931-1:2017
      In the admin, in the MARK column next to the document XML there is an EU icon to download XML based on EN 16931-1:2017 — Electronic Invoicing. Example:

  5. POS – Cash Register Integration
    Connecting a cash register (ΥΠΑΗΕΣ) to EFT/POS through the SBZ provider follows decision A.1155/2023. To connect POS, you use the Provider’s Payment Signature and the payment API services; transmission to myDATA is real-time.

    Connection flow
    1. Request a payment signature (paymentsignature.php) before the POS payment.
    2. Complete the transaction on the EFT/POS, then send payments (sendpayments.php) with the signature, invoiceuid, and VAT number.
    3. The sum of POS amounts cannot exceed the total amount of the related documents.

    Signature validity

    • Up to 24 hours for ordinary transactions.
    • Up to 2 hours for catering (accept or reject).

    If you request a signature and it is not correlated in time with a document and Unique Payment Identity, documents under issuance are transmitted to myDATA marked as “Under Issuance”.

    The provider encrypts and validates the Cash Register (ΥΠΑΗΕΣ) Payment Signature and follows the A.1155/2023 interconnection rules within its scope of responsibility. Call details are in the main API documentation (payment signature / send payments).
    Provider’s obligations

    1. As a provider, we update and update the list of counterparty entities with which we contract, directly, with any changes. This list contains basic information such as name, address, VAT number and the nature of the contracting relationship.
    2. We are responsible for identifying the entity we support and with which we contract. The entity identification process is done through the TAXISNET codes assigned to each entity that offers or receives services through the platform.
    3. As a provider, we are obliged to declare within ten (10) days, in an electronic service of the A.A.D.E., the conclusion of a contract with the entity we are contracting with. The same obligation to declare and within the same time frame is imposed on the contracted entity, which must also declare the details of the provider and the services it offers.
    4. We take all necessary measures to ensure that the e-invoicing service provider software, which we make available for use, fully ensures the issuance of a document, as well as its authentication (certification of origin and integrity of its content). We are responsible to the liable entity for ensuring the issuance, authentication of all its documents and their transmission to the ‘myDATA’ interface through the services provided by us. The documents are authenticated only if there is communication, otherwise the issue is discontinued.
    5. We are obliged to provide immediate access to all data concerning each entity with which we contract, to the entity itself and to the competent services of the AADC for the purpose of carrying out tax audits. In the event that we are requested to access such data by the competent authorities, we will ensure that such data is provided promptly and adequately. There is a possibility in the management of our system for the audit to be carried out by the AADC remotely.
    6. We have in operation an appropriate interface to the AADC to receive documentary data of the entities with which we contract. The interface allows us to retrieve directly all the data of each document, based on the format and search criteria posted on the website of the SAI, until the end of the calendar year following the calendar year of its issue. In addition, our interface allows us to retrieve a list of all the documents issued by an entity in a given calendar period. There is a possibility in the management of our system for the control to be carried out by the AADC and remotely.
    7. At the request of the AADC, as a provider we are obliged to deliver within five (5) working days, the set of data of the documents of all entities contracted with us, for a specific calendar period. The method of delivery of the data is via a formatted format posted on an APA website and includes the required data. In addition, there is a possibility in the administration of our system for the control to be carried out by the SAI remotely.
    8. In case of termination of the cooperation between us and the contracted entity, we as providers are obliged to deliver to the entity all their documents in electronic form, time-stamped and digitally signed. The delivery will be carried out in electronic media agreed between us and the contracted entity, in a secure manner and taking care of the confidentiality of the data. In addition, there is a simplified procedure for receiving documents in the admin of our system by selecting the desired period.
    9. As a provider, we apply the security policy approved in the granted e-invoicing service provider, certified security license, regarding the availability and integrity of the data we manage. We ensure that the security policy is regularly updated, and the appropriate infrastructure is in place to ensure the seamless availability and integrity of data.
    10. As a provider, we transmit data of the issued accounting records (data) to the A.A.D.E., in accordance with the provisions of article 15A of the law. 4174/2013, as in force. We provide the IAPR with the necessary data within the time limits provided by law to ensure compliance of the contracted entities with their tax obligations. In addition, we apply all necessary security measures to protect the data we manage.
    11. As a provider, we have an obligation to preserve the data of the documents and the corresponding authentication and documentation data for each entity with which we contract, for as long as we agree with the entity – user of our services and at least for as long as the obligated entity is expected to preserve them, in accordance with the provisions of article 7 of Law No. 4308/2014 and Article 13 of Law No. Therefore, we ensure that the documents and their data will remain safe and protected as long as they are kept on 2 more servers in different locations other than the issuing server.
    12. As a provider, we make available to the contracting entities, with each e-invoicing service provider contract, electronic instructions in Greek and in English. This ensures that our partners can use our services effectively and have a full understanding of how they work. The instructions can be found at https://www.sbzsystems.com/category/support-electronic-signatures
    13. We train the obligated entity on the procedures for using our services for the electronic issuance of Electronic Invoicing Provider data and inform them of their contractual obligations. We provide training materials on our website https://www.sbzsystems.com/category/support-electronic-signatures and provide a telephone hotline available Monday through Friday, 9:00 a.m. – 6:00 p.m. Our aim is to ensure that the obligated entity use our services correctly and fully comply with their obligations.
    14. As a provider, we are obliged to ensure the anonymity of the retail items issued to the contracting entity. This means that we ensure that information relating to their transactions is not made available to third parties unless required by law or ordered by a judicial authority. Our servers are accessed by technicians who have signed a confidentiality agreement.
    15. The time of the service provided to any entity – user Electronic Invoicing Provider is at least 99% of the time provided by the telecommunication network. This is recorded on the website https://api.sbz.gr/check_mydata_availability_cron.php?analysis=1. We continuously monitor the performance of the system and make upgrades and improvements to ensure the stability and reliability of our service.
    16. We provide access to the relevant Audit Authorities and Services so that they can check that the conditions of our licence are met. In addition, it is possible in our system’s administration to check the documents remotely.
    17. As a provider, we provide support for the tax audit through our software Electronic Invoicing Provider. The software is installed in our users’ businesses and has the ability to fully present the issued documents even in the event of a communication breakdown with the provider. In addition, the issued documents are kept under the responsibility of the issuer, thus offering full support in meeting tax requirements.
    18. The above software, after entering the necessary time range parameters, presents a comprehensive and detailed report on all issued documents. It is possible to see precisely the net value amounts per VAT category, the corresponding VAT tax amounts and the total amount for each category.

    1. In the event of our permanent closure, we hand over to the AADC all the data of the contracted entities’ documents. We ensure that the contracted entities do not lose any information or data that has been collected in our system. In addition, we provide any necessary documentation regarding the structure and operation of our system so that the APA can effectively manage the data and full access to a website that enables downloading of all records.
    2. We respect the confidentiality of data and information obtained in the context of our contractual relationships with the entities we work with. We do not disclose any such data or information to third parties and do not use it for our personal benefit or for the benefit of third parties. We ensure that the confidentiality of data is respected and appropriately protected.
    3. We are obliged, in the event that the Commission decides that there are grounds for withdrawing our authorisation to be eligible, to inform the entities with which we cooperate of this decision. It is worth noting that we always respect the terms of our contracts and try to maintain a positive relationship with the entities that work with us.