mydata-client

A TypeScript/JavaScript client library for the Greek myDATA (AADE) API, supporting both ERP and Provider users. Works in both Node.js and browser environments.

Table of Contents

• Installation
• Features
• Usage
  • TypeScript (Browser & Node.js)
  • JavaScript (CommonJS)
  • JavaScript (ESM)
• Testing
• Development Workflow
• Official Documentation
• Examples
• License

Installation

npm install @logismix/mydata-client

Features

• Full TypeScript support with type definitions
• Support for all myDATA API endpoints for both ERP and Provider users
• XML generation compliant with official XSD schemas (v1.0.10)
• Works with both CommonJS and ESM module systems
• Browser and Node.js compatible
• Automatic XML parsing of API responses
• Comprehensive error handling

Usage

TypeScript (Browser & Node.js)

import { MyDataClient } from '@logismix/mydata-client';

// Initialize client
const myDataClient = new MyDataClient({
  userId: 'your_aade_user_id', // Your AADE User ID
  subscriptionKey: 'your_aade_subscription_key', // Your AADE Subscription Key
  production: false // Set to true for production API
});

// Example invoice data
const invoice = {
  issuer: {
    vatNumber: process.env.MYDATA_ISSUER_VAT!,
    country: 'GR',
    branch: 0
  },
  counterpart: {
    vatNumber: process.env.MYDATA_RECEIVER_VAT!,
    country: 'GR',
    branch: 0
  },
  invoiceHeader: {
    series: 'A',
    aa: '1',
    issueDate: new Date(),
    invoiceType: '1.1',
    currency: 'EUR'
  }
  // ... rest of invoice structure
};

// Send invoice (Provider example)
myDataClient
  .sendProviderInvoices([invoice], true)
  .then(response => console.log('Success:', response))
  .catch(error => console.error('Error:', error));

JavaScript (CommonJS)

const { MyDataClient } = require('@logismix/mydata-client');
require('dotenv').config();

const myDataClient = new MyDataClient({
  userId: process.env.MYDATA_USR,
  subscriptionKey: process.env.MYDATA_KEY,
  production: process.env.MYDATA_PRODUCTION === 'true'
});

// ... rest of usage similar to TypeScript example

JavaScript (ESM)

import { MyDataClient } from '@logismix/mydata-client';
import dotenv from 'dotenv';

dotenv.config();

const myDataClient = new MyDataClient({
  userId: process.env.MYDATA_USR,
  subscriptionKey: process.env.MYDATA_KEY,
  production: process.env.MYDATA_PRODUCTION === 'true'
});

// ... rest of usage similar to TypeScript example

Testing

For testing purposes, the library includes XSD validation capabilities and requires additional configuration:

1. Install testing dependencies:

npm install dotenv --save-dev

2. Create a .env file with your test credentials:

MYDATA_USR=your_aade_user_id
MYDATA_KEY=your_aade_subscription_key
MYDATA_PRODUCTION=false
MYDATA_ISSUER_VAT=your_vat_number
MYDATA_RECEIVER_VAT=customer_vat_number

3. The test suite validates XML against the official XSD schemas (v1.0.10) located in /schemas

Development Workflow

Versioning Workflow

1. Update CHANGELOG.md:

   • Add new entries under [Unreleased] section as changes are made
   • Group changes by type (Added, Changed, Deprecated, Removed, Fixed, Security)
   • Include issue/PR references when applicable (e.g., #123)

2. Update package.json version:

   npm version patch|minor|major

   This will:

   • Update package.json version
   • Create a git commit with the version bump
   • Create a git tag with the version

3. Update CHANGELOG for release:

   • Rename [Unreleased] to new version (e.g., [1.2.3] - 2025-04-14)
   • Add new [Unreleased] section at top

4. Create GitHub Release:

   git push origin main --tags

   Then create a release on GitHub using the new tag, copying relevant CHANGELOG entries

5. Automation (optional): Consider adding these npm scripts to package.json:

   "scripts": {
     "release": "standard-version",
     "release:minor": "standard-version --release-as minor",
     "release:major": "standard-version --release-as major"
   }

   Then install standard-version:

   npm install --save-dev standard-version

Official Documentation

The repository includes official myDATA API documentation in both English and Greek, as well as the original XSD schemas for validation:

ERP Documentation

• English Markdown
• Greek Markdown
• Original Greek PDF

Providers Documentation

• English Markdown
• Greek Markdown
• Original Greek PDF

XSD Schemas

All official XSD schemas (v1.0.10) for document validation are available in the /schemas directory.

Note: These documentation files and schemas are only available in the GitHub repository and are not included when installing the package via npm.

API Documentation

MyDataClient Class

The primary way to interact with the myDATA API is through the MyDataClient class.

Constructor

new MyDataClient(config: {
  userId: string;
  subscriptionKey: string;
  production: boolean;
})

ERP User Methods

• sendErpInvoices(invoices: AadeBookInvoiceType[]): Promise<ResponseDoc> - Sends one or more invoices, including corrected/amending ones.
• sendErpIncomeClassification(classifications: IncomeClassificationsDoc): Promise<ResponseDoc> - Sends one or more income classifications, corresponding to already submitted invoices.
• sendErpExpensesClassification(classifications: ExpensesClassificationsDoc): Promise<ResponseDoc> - Sends one or more expense classifications.
• sendErpPaymentsMethod(payments: PaymentMethodsDoc): Promise<ResponseDoc> - Sends payment methods for an invoice.
• cancelErpInvoice(markToCancel: number, entityVatNumber?: string): Promise<ResponseDoc> - Cancels a previously transmitted invoice.
• requestErpDocs(params: RequestDocParams): Promise<RequestedDoc> - Requests documents (invoices, classifications, cancellations) received from others.
• requestErpTransmittedDocs(params: RequestDocParams): Promise<RequestedDoc> - Requests documents (invoices, classifications, cancellations) previously transmitted by the user.
• requestErpMyIncome(params: RequestMyDataParams): Promise<RequestedBookInfo> - Requests aggregated income data for a period.
• requestErpMyExpenses(params: RequestMyDataParams): Promise<RequestedBookInfo> - Requests aggregated expense data for a period.
• requestErpVatInfo(params: RequestVatE3Params): Promise<RequestedVatInfo> - Requests VAT related data for a period.
• requestErpE3Info(params: RequestVatE3Params): Promise<RequestedE3Info> - Requests E3 related data for a period.

Provider User Methods

• sendProviderInvoices(invoices: AadeBookInvoiceType[], validate?: boolean): Promise<ResponseDoc> - Sends one or more invoices.
• sendProviderUnsignedInvoices(invoices: AadeBookInvoiceType[]): Promise<ResponseDoc> - Sends one or more invoices pending issuance (unsigned).
• sendProviderPaymentsMethod(payments: PaymentMethodsDoc): Promise<ResponseDoc> - Sends payment methods for an invoice.
• requestProviderTransmittedDocs(issuerVat: string, mark: number, nextPartitionKey?: string, nextRowKey?: string): Promise<RequestedProviderDoc> - Requests summaries of documents previously transmitted by the provider for a specific issuer.
• requestProviderReceiverInfo(vatNumber: string): Promise<ReceiverInfoDoc> - Requests information about a recipient's registered providers and emails.

Examples

The /examples directory contains complete usage examples for both TypeScript and JavaScript:

TypeScript Examples

ERP Examples

• invoice-example.ts - Sending an invoice
• cancel-erp-invoice-example.ts - Canceling a transmitted invoice
• request-erp-docs-example.ts - Requesting received documents
• request-erp-transmitted-docs-example.ts - Requesting transmitted documents
• request-erp-my-expenses-example.ts - Requesting aggregated expense data
• request-erp-my-income-example.ts - Requesting aggregated income data
• request-erp-vat-info-example.ts - Requesting VAT related data
• request-erp-e3-info-example.ts - Requesting E3 related data
• send-erp-expenses-classification-example.ts - Sending expense classifications
• send-erp-income-classification-example.ts - Sending income classifications
• send-erp-invoices-example.ts - Sending invoices
• send-erp-payments-method-example.ts - Sending payment methods

Provider Examples

• send-provider-invoices-example.ts - Sending invoices
• send-provider-payments-method-example.ts - Sending payment methods
• send-provider-unsigned-invoices-example.ts - Sending unsigned invoices
• request-provider-transmitted-docs-example.ts - Requesting transmitted documents
• request-provider-receiver-info-example.ts - Requesting receiver information

Common Examples

• retrieve-docs-example.ts - Retrieving documents
• validate-sample-invoices.ts - XML validation examples
• validate-sample-invoice-xmls.ts - Advanced XML validation

JavaScript Examples

• invoice-example.js - Browser-compatible invoice example
• retrieve-docs-example.js - Browser-compatible document retrieval

License

MIT License

Copyright (c) 2025 Logismix

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.