Transcription
myDATAElectronic Books AADETechnical documentation of REST API interfacefor submitting and retrieving dataVersion 0.6 – March 2020
Table of contents1Introduction . 32Objective. 43Technical requirements for invoicing programs. 54Description of RESTAPI . 64.1Portal for developers . 64.2Interface description . 74.2.1 User registration . 74.2.2 Using services . 84.2.3 Headers. 84.3Services . 94.3.1 SendInvoices . 94.3.2 SendIncomeClassification . 104.3.3 SendExpensesClassification . 114.3.4 CancelInvoice. 124.3.5 RequestDocs . 124.3.6 RequestTransmittedDocs . 135InvoiceDoc description . 145.1Party . 165.1.1 Address . 175.2Payment Method . 175.3Invoice header . 185.4Invoice details . 205.4.1 Activity Undertaking Declaration (POL 1177/2018, Article 27) . 235.5Taxes totals . 245.6Invoice summary . 255.7Income classification . 275.8Expenses classification . 286Responses . 306.1Data submission . 306.2Data retrieval . 32myDATA REST API1
97Errors . 347.1Technical errors . 347.2Operational errors . 358Appendix . 378.1Invoice type . 378.2VAT category . 418.3VAT Exemption Cause. 418.4Withholding taxes. 428.5Other taxes . 428.6Stamp duty . 438.7Fees. 438.8Income Classification Category . 438.9Income Classification Type . 448.10Expenses Classification Category. 458.11Expenses Classification Type . 458.12Payment methods . 478.13Unit of measurement . 478.14Purpose of movement . 488.15Remark. 48History of changes . 499.1Version 0.5.2 . 49Version 0.6. 49myDATA REST API2
1IntroductionmyDATA (my Digital Accounting and Tax Application) is the name of the new electronicplatform by which AADE introduces electronic books into the daily lives of businesses.Electronic Books is a very important step in the digital transformation of the State and thebusinesses. Our goal is primarily to serve businesses by providing an innovative digitalplatform for fulfilling their tax obligations, which will lead to the automation of taxdeclaration and will relieve them of their current obligations, such as Filing of CustomersSuppliers Lists.The myDATA online platform provides easy solutions for everyone. Both for businesses thathave computerized accounting systems that can submit the necessary data in bulk andautomated, and for other companies that can submit data in a simple way, through aregistration form on the website of AADE.myDATA REST API3
2ObjectiveFor the needs of businesses and professionals with computerized accounting systems, AADEprovides a RESTAPI interface installed on public cloud infrastructure (Microsoft Azure). Thisenables ERP systems or other accounting-trading systems to seamlessly interconnect withAADE for the exchange of relevant data.Specifically, for an enterprise using an information system that uses the relevant API, thefeatures offered are: Send data for the invoices it issues. Sending income classification for the invoices it issues. Retrieve data of invoices issued for it and submitted by the respective issuers to AADE. Send expense classification data to AADE.This document describes the above services and the technical specifications necessary toimplement the relevant calls of the RESTAPI interface.myDATA REST API4
3Technical requirements for invoicing programs1) The following technologies are used in order to establish a connection with theinterface HTTPS - Secure HTTP Webservice REST API - REST interface required for data reporting process XML - eXtensible Markup Language2) The interface is accessible to any invoicing program capable of sending HTTP messagesand creating schema-conformant XML, as specified in the present specification.3) In addition to the relevant data, the software should be able to simultaneously andautomatically send the necessary information to identify the user through the sameHTTPS call.myDATA REST API5
4Description of RESTAPIIn summary, the interface provides the following services: /SendInvoices: submit one or more invoices, including corrected/modified/RequestDocs: retrieve one or more invoices, classifications or invoice cancelations thatother users have submitted/RequestTransmittedDocs: retrieve one or more invoices, classifications or invoicecancelations the user has submitted/SendIncomeClassification: submit income classification for one or more alreadysubmitted invoices/SendExpensesClassification: submit expenses classification for one or more alreadysubmitted invoices/CancelInvoice: cancels an invoiceA detailed description of the services is described later in this document.4.1 Portal for developersFor the development and testing phase, the available RestAPI services are available at URL:https://mydata-dev.azure-api.netA dedicated portal for developers exists at URL: https://mydata-dev.portal.azure-api.net/The portal contains documentation of all the services available, code samples in differentprogramming languages and offers the ability to execute direct test calls through the portalitself. In addition, the user profile provides analytics reports on calls made. Also, from theprofile, the user can reissue/change the subscriptionkey.Finally, for functionality issues, problems or suggestions for improvement, you can refer tothe URL: https://mydata-dev.portal.azure-api.net/issues via the ReportIssue option.myDATA REST API6
4.2 Interface description4.2.1User registrationUsing interface services requires a user authentication process. Authentication isaccomplished by sending a username and a subscriptionkey in the headers of every call. Thesubscriptionkey is a string, unique per user, and is common for all interface services.In order for a user to obtain the above credentials, he/she must create an account in theregistry of the interface through a special registration process offered by the myDATA onlineplatform.The necessary information in order to create an account is the following: Desired User Name (username) Contact email Type of authorization.The type of authorization is required when the codes are given to a third party entity,authorized by the user to submit data in his/her behalf. Such cases may include accountantauthorization, billing assignment or self-billing authorisation.In the event of a successful registration, the user is created in the relevant RESTAPI registry,and a special subscriptionkey is provided that the user will use to identify him/her whencalling interface services. A confirmation message of the registration is also sent to theregistered email address.After the registration step the user will be able to log in to the portal of the interface withtheir account details from where they can view and change the subscriptionkey.*Note: For the development and testing phase, the registration process for myDATARESTAPIservices will be done through the application available at A REST API7
4.2.2Using servicesEach service is performed by sending a HTTPS call (GET or POST, depending on the function)to the corresponding URL.The call must contain the appropriate header containing the information needed to identifythe user and a body in XML format whose structure will depend on the service being called.For each call the user will receive an answer with information about the outcome of theircall in XML format.In submission services (POST calls) the user can send one or more objects (Invoices, IncomeClassifications, etc), incorporating them into the body of the call in a specific XML format.The answer will contain, for each document, one or more error messages or a successfulsubmission message. If an item is resubmitted, having the same identifiers as a previouslyshipped item, the latter is retained in the Electronic Books database as valid, and theprevious one is canceled accordingly.In retrieval services (GET calls) the user sends the necessary parameters for the relevantobject retrieval query.4.2.3HeadersEach call must contain the following headers in the form of pair-values, which is necessaryfor user identification. In case of incorrect information the user will receive an keyData TypeStringStringVALUE{User name}{Subscription Key}DESCRIPTIONUser name of the accountUser’s subscription keyBy identifying the user through the headers, the interface will also gain access to the VATnumber the user had stated when registering, so that it would not be necessary to submit itin every call.myDATA REST API8
4.3 Services4.3.1SendInvoicesThe call has the following characteristics: /sendInvoices (POST) Header as described in section 4.2.3 Body in xml format containing the InvoicesDoc element, which contains one or moreinvoices. The structure of the element InvoicesDoc is described by typeAadeBookInvoiceType and is discussed in Chapter 5*Note: For the development and testing phase, the method is available at yDATA REST API9
4.3.2SendIncomeClassificationThe call has the following characteristics: /SendIncomeClassification (POST) Header as described in section 4.2.3 Body in xml format containing one or more InvoiceIncomeClassificationTypeelements. The structure of the element isFieldTypeMandatoryDescriptionValid ngNotransactionModexs:intYes (3)Unique trationNumberTransaction Type1 ntIncomeClassificationTypeYesYes (3)Line numberIncomeClassification TypeRemarks1) Field classificationMark is filled in by the service2) When field transactionMode has value 1, means rejection of invoice3) User must include either field transactionMode, either a list ofinvoicesIncomeClassificationDetails elements4) Every invoicesIncomeClassificationDetails element contains lineNumber and a list ofinvoiceIncomeClassificationDetailData elements5) Field lineNumber refers to the corresponding line number of the invoice identifiedby the given mark*Note: For the development and testing phase, the method is available at ssificationmyDATA REST API10
4.3.3SendExpensesClassificationThe call has the following characteristics: /SendExpensesClassification (POST) Header as described in section 4.2.3 Body in xml format containing one or more InvoiceExpensesClassificationTypeelements. The structure of the element esclassificationMarkxs: lassificationTypeYes (3)YesYes (3)Unique InvoiceRegistration NumberUnique ClassificationRegistration NumberTransaction TypeLine numberValidvalues1 Reject1) Field classificationMark is filled in by the service2) When field transactionMode has value 1, means rejection of invoice3) User must include either field transactionMode, either a list of or moreinvoicesExpensesClassificationDetails elements4) Every invoicesExpensesClassificationDetails element contains lineNumber and a listof expensesClassificationDetailData elements5) Field lineNumber refers to the corresponding line number of the invoice identifiedby the given mark*Note: For the development and testing phase, the method is available at lassificationmyDATA REST API11
4.3.4CancelInvoiceThis method (POST method) is used to cancel one invoice without sending a new one. Usercall the method by submitting as a parameter the MARK of the invoice he/she wants tocancel. No xml body is required.In case of success, the user receives the MARK of cancellation. Otherwise an error messageis esUnique Invoice Registration Number*Note: For the development and testing phase, the method is available at ?[mark]4.3.5RequestDocsWith this method can retrieve invoices, classifications and invoice cancelations that havebeen submitted to myDATA by other users.The retrieval is done via a HTTP call (GET), which takes as parameter a Unique InvoiceRegistration Number (mark). The method returns the invoices that have the user's VATnumber and Unique Invoice Registration Number greater than the specified oUnique Invoice Registration NumberParameter for partial retrieval of resultsParameter for partial retrieval of resultsNote: If the results exceed the maximum limit, they are returned in increments. ThenextPartitionKey and nextRowKey fields will be included in each part of the results and willbe used as parameters in the call to receive the next part of results.*Note: For the development and testing phase, the method is available at mark]&[nextPartitionKey]&[nextRowKey]myDATA REST API12
4.3.6RequestTransmittedDocsWith this method can retrieve invoices, classifications and invoice cancelations that havebeen submitted to myDATA by him/her.The retrieval is done via a HTTP call (GET), which takes as parameter a Unique InvoiceRegistration Number (mark). The method returns the invoices that have the user's VATnumber and Unique Invoice Registration Number greater than the specified oUnique Invoice Registration NumberParameter for partial retrieval of resultsParameter for partial retrieval of resultsNote: If the results exceed the maximum limit, they are returned in increments. ThenextPartitionKey and nextRowKey fields will be included in each part of the results and willbe used as parameters in the call to receive the next part of results.*Note: For the development and testing phase, the method is available at DATA REST API13
5InvoiceDoc descriptionThis section describes in detail the contents of an invoice (type AadeBookInvoiceType).The structure of the element is as follows:myDATA REST API14
criptionValid valuesInvoice identifierLength 40Filled in by theserviceUnique InvoiceFilled in by theRegistration Number serviceUniqueInvoice Filled in by theCancelation Number serviceAuthentication Code Filled in only byprovidersInvoice issuerInvoice counterpartPayment MethodsInvoice headerInvoice linesTotal taxesInvoide SummaryRemarks1) Uid is the identifier of every invoice and is filled in by the service. It is calculated by2)3)4)5)the SHA-1 hash of 6 fields of the document which are: Issuer’s VAT number Date of issue Branch number in Taxis Registry Invoice Type Series Serial Number (ΑΑ)Field mark is the Unique Invoice Registration NumberField taxesTotals contains all taxes except VAT. If user users this element, taxes willnot exist in invoiceDetailsComplex types PartyType, PaymentMethodDetailType, InvoiceHeaderType,InvoiceRowType, TaxTotalsType and InvoiceSummaryType are described later in thissection.Unique Invoice Cancellation Number exists only when the invoice has been cancelledand contains the cancellation MARK.myDATA REST API15
5.1 PartyThe issuer and the counterpart are elements of type tringAddressTypeYesYesYesΝοNoVAT numberCountry codeBranch numberNameAddressValid valuesAny valid VAT numberCountry codesMin value 0Remarks1) The country code is two characters and comes from the corresponding country listas described in ISO 3166.2) If the branch is headquarters or doesn’t exist, the branch field must have a value of0.3) For the issuer fields name and address are valid only in case the entity is not fromGreece. For the counterpart field name must not be submitted if the entity is fromGreece.myDATA REST API16
5.1.1AddressThe address of the issuer (or the counterpart) is an element of type ingΝοΝοYesYesStreerNumberPostal codeCity5.2 Payment MethodPayment method is an element of type iontypexs:intYesamountxs:decimal YesPaymentmethodAmountpaymentMethodInfo xs:stringNoValid valuesMin value 1Max value 9Min value 0Decimal digits 2InformationRemarks1) Possible values of field type are described in the appendix2) Field amount may refer to fraction of the invoice’s total value3) Field paymentMethodInfo contains additional information for the specified typemyDATA REST API17
5.3 Invoice headermyDATA REST API18
YesInvoice seriesInvoice’s serialnumberInvoice’s issue dateInvoice gxs:intNoNoNoNoVAT paymentsuspensionCurrencyExchange rateCorrelated invoicesSelf-billingindicationDispatch dateDispatch timeVehicle numberPurpose ofmovementValid values1.1, 1.2, 1.3, 1.4, 1.5,1.6, 2.1, 2.2, 2.3, 2.4,3.1, 3.2, 4, 5.1, 5.2,6.1, 6.2, 7.1, 8.1, 8.2,11.1, 11.2, 11.3, 11.4,11.5, 12, 13.1, 13.2,13.3, 13.4, 13.30,13.31, 14.1, 14.2, 14.3,14.4, 14.5, 14.30,14.31, 15.1, 16.1, 17.1,17.2, 17.3, 17.4, 17.5,17.6Currency codeMin value 0Decimal digits 5Min value 1Max value 8Remarks1) The exchangeRate field is the currency exchange rate against euro. It should becompleted only when the currency is not EUR.2) The currency code is derived from the corresponding list in accordance withISO4217.3) The correlatedInvoices element is a list of strings containing the associated invoicesidentifiers4) In case of non-issuance of series of an invoice, the series field must have a value of 05) The selfPricing field specifies if it is self-billing invoice6) The possible values of fields movePurpose and invoiceType are described in detail inthe corresponding tables in the AppendixmyDATA REST API19
5.4 Invoice detailsInvoice’s details (InvoiceDetails) are composed of one or more InvoiceRowType records.myDATA REST API20
malxs:intxs:intxs:decimalYesNoNoNoYesLine numberQuantityUnit of quanitySelf-billing remarkNet valuevatCategoryxs:intYesVAT categoryvatAmountxs:decimalYesVAT txs: decimalNoVAT exemptioncategoryArticle 27 of POL1177/2018Discount optionWithholding taxamountWithholding tax ratecategoryStamp duty :decimalNoStamp duty ratecategoryFees amountfeesPercentCategoryxs:intNoFees rate categoryotherTaxesPercentCategory xs:intNootherTaxesAmountxs:decimalNoOther taxes ratecategoryOther taxes amountdeductionsAmountxs:decimalNoDeductions sClassificationTypeNoNoNoLine commentsIncome classificationExpenses classificationmyDATA REST APIValid valuesMin value 1Min value 01,2,31,2Min value 0Decimal digits 2Min value 1Max value 8Min value 0Decimal digits 2Min value 1Max value 23False / TrueMin value 0Decimal digits 2Min value 1Max value 12Min value 0Decimal digits 21, 2, 3Min value 0Decimal digits 2Min value 1Max value 8Min value 1Max value 9Min value 0Decimal digits 2Min value 0Decimal digits 221
Remarks1) The possible values for the measurementUnit, invoiceDetailType, vatCategory,vatExemptionCategory, withheldPercentCategory, stampDutyPercentCategory,feesPercentCategory and otherTaxesPercentCategory fields are described in detail inthe corresponding tables in the Appendix2) Fields withheldAmount, feesAmount, otherTaxesAmount are filled in when thecorresponding tax exists (even if it is percentage)3) The vatExemptionCategory field is required if the vatCategory indicates a 0% VATrate4) For cases where VAT is not applied, the vatCategory field will have the value of 85) Line comments are filled in by the user and are used for information purposes only6) Classifications (income if submitter is issuer, expenses if counterpart) must besubmitted with the invoice in the corresponding fields.myDATA REST API22
5.4.1Activity Undertaking Declaration (POL 1177/2018, Article 27)Activity undertaking declaration is an element of type ingxs:stringYesNoYesActivity UndertakingDeclaration NumberApplication dateTax Return Filing DOYShip detailsmyDATA REST API23
5.5 Taxes totalsElement TaxTotalsType which contains the total taxes has the following structure:FieldTypeMandatoryDescriptionValid ValuestaxTypexs:byteYesType of taxtaxCategoryxs:byteYesTax imalYesUnderlying valueto which the taxrefersTax amount1 Withheld taxes2 Fees3 Other taxes4 Stamp duty5 DeductionsSee tables 8.4 – 8.8 ofappendixMin value 0Decimal digits 2Idxs:byteNoLine numbermyDATA REST APIMin value 0Decimal digits 224
5.6 Invoice icationTypeNoDescriptionValid valuesTotal net valueMin value 0Decimal digits 2Total VAT amountMin value 0Decimal digits 2Total withholdingMin value 0taxes amountDecimal digits 2Total fees amountMin value 0Decimal digits 2Total stamp duty Min value 0amountDecimal digits 2Total other taxesMin value 0amountDecimal digits 2Total deductions Min value 0amountDecimal digits 2Total gross valueMin value 0Decimal digits myDATA REST API25
1) Elements incomeClassification and expensesClassification contain the sums of allcombinations of fields classificationType and classificationCategory that exist in thedetails of the invoice.2) All taxes summary fields contain the summary of corresponding taxes of the detailsof the invoice or in the taxesTotals element.myDATA REST API26
5.7Income classificationElement IncomeClassificationType which contains the income classification has the followingstructure:FieldclassificationTypeTypexs: ssificationCategoryxs: Amountidxs:byteNoSerial number ofclassificationValid valuesE3 106, E3 205, E3 210, E3 305,E3 310, E3 318, E3 561 001,E3 561 002, E3 561 003,E3 561 004, E3 561 005,E3 561 006, E3 561 007, E3 562,E3 563, E3 564, E3 565, E3 566,E3 567, E3 568, E3 569, E3 570,E3 595, E3 596, E3 597,E3 880 001, E3 880 002,E3 880 003, E3 880 004,E3 881 001, E3 881 002,E3 881 003, E3 881 004category1 1, category1 2,category1 3, category1 4,category1 5, category1 6,category1 7, category1 8,category1 9, category1 10,category1 95Min value 0Decimal digits 2Remarks1) Possible values of fields classificationType and classificationType are described in theappendix2) Field id is used for serial numbering (1,2,3 κλπ) of the classifications of a rowmyDATA REST API27
5.8Expenses classificationElement ExpensesClassificationType which contains the income classification has thefollowing structure:FieldclassificationTypemyDATA REST APITypexs: id valuesE3 101, E3 102 001,E3 102 002, E3 102 003,E3 102 004, E3 102 005,E3 102 006, E3 104, E3 201,E3 202 001, E3 202 002,E3 202 003, E3 202 004,E3 202 005, E3 204, E3 207,E3 209, E3 301, E3 302 001,E3 302 002, E3 302 003,E3 302 004, E3 302 005,E3 304, E3 307, E3 309, E3 312,E3 313 001, E3 313 002,E3 313 003, E3 313 004,E3 313 005, E3 315,E3 581 001, E3 581 002,E3 581 003, E3 582, E3 583,E3 584, E3 585 001,E3 585 002, E3 585 003,E3 585 004, E3 585 005,E3 585 006, E3 585 007,E3 585 008, E3 585 009,E3 585 010, E3 585 011,E3 585 012, E3 585 013,E3 585 014, E3 585 015,E3 585 016, E3 586, E3 58
myDATA REST API 3 1 Introduction myDATA (my Digital Accounting and Tax Application) is the name of the new electronic platform by which AADE introduces electronic books into the daily lives of businesses. Electronic Books is a very important step in the digital transformation of the State and the
