angro-kft / nav-connector

Node.js module which provides an interface for communicating with NAV online invoice service.

nav-connector

Node.js module which provides an interface for communicating with NAV online invoice service.

This module was developed in order to satisfy the following specification:
Online invoice interface specification

Installation

Tested with version 12.18.3 of Node.js.

$ npm install @angro/nav-connector

Example

const NavConnector = require('@angro/nav-connector');

/* Your technical user's data. */
const technicalUser = {
  login: 'login123',
  password: 'password',
  taxNumber: '12345678',
  signatureKey: 'signatureKey',
  exchangeKey: 'exchangeKey',
};

const softwareData = {
  softwareId: '123456789123456789',
  softwareName: 'string',
  softwareOperation: 'LOCAL_SOFTWARE',
  softwareMainVersion: 'string',
  softwareDevName: 'string',
  softwareDevContact: 'string',
  softwareDevCountryCode: 'HU',
  softwareDevTaxNumber: 'string',
};

const baseURL = 'https://api-test.onlineszamla.nav.gov.hu/invoiceService/v3/';

/* Create the nav connector interface. */
const navConnector = new NavConnector({ technicalUser, softwareData, baseURL });

(async function sendInvoice() {
  try {
    /* On app start You can test connection to the NAV service and user given data validity.
       testConnection() will throw if a tokenExchangeRequest operation is not successful. */
    await navConnector.testConnection();

    /* Send invoice to the NAV service.
       invoiceOperations is the InvoiceOperationListType in the specification. */
    const invoiceOperations = {
      compressedContent: false,
      invoiceOperation: [
        {
          index: 1,
          operation: 'CREATE',
          invoice: 'invoice xml in base64 encoding',
        },
      ],
    };

    const transactionId = await navConnector.manageInvoice(invoiceOperations);

    /* Check previously sent invoice processing status.
       processingResults is the ProcessingResultListType in the specification. */
    const processingResults = await navConnector.queryTransactionStatus({
      transactionId,
    });

    /* Check processingResults.length.
        If the array is empty then transactionId was invalid. */
    if (processingResults.length) {
      /* Handle invoice status responses. */
    }
  } catch (error) {
    /* Handle errors. See bellow for details. */
  }
})();

API

NavConnector

Class representing the implementation of the NAV online invoice data service specification.

/**
 * Create a navConnector.
 * @param {Object} params Constructor params.
 * @param {Object} params.technicalUser Technical user data.
 * @param {Object} params.softwareData Software data.
 * @param {String} [params.baseURL=https://api.onlineszamla.nav.gov.hu/invoiceService/v3/] Axios baseURL.
 * @param {number} [params.timeout=70000] Axios default timeout integer in milliseconds.
 */
const navConnector = new NavConnector({ technicalUser, softwareData });

Axios timeout option is needed because during NAV service outages, requests may never timeout if axios timeout option is not set.
According to the NAV online invoice service documentation the request timeout is set to 5000 ms on the service side but in practice there may be no timeout or there can be a gateway timeout after 60 seconds. The timeout is set to 70000 milliseconds (70 sec) in axios as default.
You can fine tune this value but its strongly suggested to keep it above 60 seconds to avoid dropped responses.

const navConnector = new NavConnector({
  technicalUser,
  softwareData,
  timeout: 70000,
});

navConnector.manageInvoice()

Method to send a single or multiple invoices to the NAV service. The method returns the transaction id of the operation which can be used later to get the status of the invoice processing status of this request.

/**
 * Send request to NAV service to manage invoices.
 * @async
 * @param {Object} invoiceOperations Request object for xml conversion and send.
 * @returns {Promise<string>} Manage invoice operation transaction id.
 */
const transactionId = await navConnector.manageInvoice(invoiceOperations);

Example for invoiceOperations parameter:

const invoiceOperations = {
  compressedContent: false,
  invoiceOperation: [
    {
      index: 1,
      invoiceOperation: 'CREATE',
      invoiceData: 'invoice xml in base64 encoding',
      electronicInvoiceHash: 'SHA3-512'
    },
    {
      index: 2,
      invoiceOperation: 'STORNO',
      invoiceData: 'invoice xml in base64 encoding',
    },
  ],
};

Take note You have to compress the invoice by yourself before using the manageInvoice method.

const invoiceOperations = {
  compressedContent: true,
  invoiceOperation: [
    {
      index: 1,
      invoiceOperation: 'CREATE',
      invoiceData: 'compressed invoice xml in base64 encoding',
      electronicInvoiceHash: 'SHA3-512'
    },
  ],
};

navConnector.manageAnnulment()

Method to send a single or multiple invoice annulments to the NAV service. The method returns the transaction id of the operation which can be used later to get the status of the invoice processing status of this request.

/**
 * Send request to NAV service to manage annulment invoices.
 * @async
 * @param {Object} annulmentOperations Request object for xml conversion and send.
 * @returns {Promise<string>} Manage invoice operation transaction id.
 */
const transactionId = await navConnector.manageAnnulment(annulmentOperations);

Example for annulmentOperations parameter:

const annulmentOperations = {
  annulmentOperation: [
    {
      index: 1,
      annulmentOperation: 'ANNUL',
      invoiceAnnulment: 'invoice xml in base64 encoding',
    },
    {
      index: 2,
      annulmentOperation: 'ANNUL',
      invoiceAnnulment: 'invoice xml in base64 encoding',
    },
  ],
};

navConnector.queryTransactionStatus()

Method to get the processing status of previously send invoices. The resolved return value is the ProcessingResultListType of the specification.

/**
 * Get the result of a previously sent manage invoice request.
 * @async
 * @param {Object} params Function params.
 * @param {string} params.transactionId Manage invoice operation transaction id.
 * @param {boolean} [params.returnOriginalRequest=false] Flag for api response to contain the original invoice.
 * @returns {Promise<Array>} processingResults
 */
const processingResults = await navConnector.queryTransactionStatus({
  transactionId,
  returnOriginalRequest: true,
});

processingResults.forEach(processingResult => {
  const {
    index,
    invoiceStatus,
    originalRequest,
    compressedContentIndicator,
    businessValidationMessages,
    technicalValidationMessages,
  } = processingResult;

  /* Property businessValidationMessages and technicalValidationMessages
     are always normalized to arrays even if there were no validation messages. */
});

This function does type conversion for number and boolean typed values in the response according to the NAV service documentation.

navConnector.testConnection()

Method to test connection, user auth data and keys validity with a tokenExchangeRequest.

/**
 * Test connection, user auth data and keys validity with a tokenExchangeRequest.
 * @async
 * @throws {Object} Will throw an error if there was a network expectation
 * or any user given auth data or key is invalid.
 */
try {
  await navConnector.testConnection();
} catch (error) {
  /* Log the error. */
}

navConnector.queryInvoiceData()

Method to query previously sent invoices with invoice number.

/**
 * Query previously sent invoices with invoice number
 * @async
 * @param {Object} params Function params.
 * @param {Object} params.invoiceQuery Query single invoice with invoice number.
 * @returns {Promise<Object>} response
 */

Query by invoice number

const invoiceQuery = {
  invoiceNumber: 'invoiceNumber',
  invoiceDirection: 'OUTBOUND',
};

const response = await navConnector.queryInvoiceData({
  invoiceQuery,
});

const { invoiceData, auditData, compressedContentIndicator } = response;

/* If no invoice was found with the given query then queryResult is undefined. */
if (!invoiceData) {
  return;
}

const { invoiceResult, invoiceDigestList } = queryResult;

This function does type conversion for number and boolean typed values in the response according to the NAV service documentation.

navConnector.queryInvoiceDigest()

Method to query previously sent invoices with query params.

/**
 * Query previously sent invoices with query params.
 * @async
 * @param {Object} params Function params.
 * @param {number} params.page Integer page to query.
 * @param {string} params.invoiceDirection inbound or outbound request type
 * @param {Object} params.queryParams Query multiple invoices with params.
 * @param {string} queryParams.dateFrom - REQUIRED valid date string to search from
 * @param {string} queryParams.dateTo - REQUIRED valid date string to search to
 * @param {string} queryParams.taxNumber - OPTIONAL Tax number of the invoice supplier or customer
 * @param {string} queryParams.groupMemberTaxNumber - OPTIONAL Tax number of group member for the invoice supplier or customer
 * @param {string} queryParams.name - OPTIONAL Left side text matching for the invoice supplier or customer search parameter
 * @param {string} queryParams.invoiceCategory - OPTIONAL Invoice category type
 * @param {string} queryParams.paymentMethod - OPTIONAL Payment method
 * @param {string} queryParams.invoiceAppearance - OPTIONAL Appearance of the invoice
 * @param {string} queryParams.source - OPTIONAL Data report source
 * @param {string} queryParams.currency - OPTIONAL Invoice currency
 * @param {string} queryParams.transactionId - OPTIONAL The searched transaction ID
 * @param {number} queryParams.index - OPTIONAL Index of the searched invoice within the transaction
 * @param {string} queryParams.invoiceOperation - OPTIONAL Invoice operation search parameter
 * @returns {Promise<Object>} response
 */

Query by parameters

const queryParams = {
  dateFrom: '2017-12-28',
  dateTo: '2017-12-28',
};

const response = await navConnector.queryInvoiceDigest({
  invoiceDirection: 'OUTBOUND',
  page: 1,
  queryParams,
});

const { currentPage, availablePage, queryResult } = response;

/* If no invoice was found with the given query then queryResult is undefined. */
if (!queryResult) {
  return;
}

const { invoiceDigestList } = queryResult;

This function does type conversion for number and boolean typed values in the response according to the NAV service documentation.

navConnector.queryTaxpayer()

Method to get taxpayer information by tax number.
It resolves to an object containing taxpayerValidity and taxpayerData properties.
Keep in mind the taxpayerData property is not returned by the NAV service if the tax number is non existent.

/**
 * Get taxpayer information by tax number.
 * @param {string} taxNumber Taxpayer tax number to get information for.
 * @returns {Promise<Object>} Taxpayer information with taxpayerValidity, taxpayerData, incorporation fields.
 */
const { taxpayerValidity, taxpayerData, incorporation } = await navConnector.queryTaxpayer(
  '12345678'
);

if (!taxpayerValidity) {
  /* Taxpayer is non existent or inactive. */
} else if (taxpayerData) {
  /* The taxpayerData property was returned by the service. */
}

This function does type conversion for boolean typed values in the response according to the NAV service documentation.

Error handling

All methods can throw expectation and You can fine tune how to log these error, handle them or retry the request if possible.

try {
  await navConnector.testConnection();
} catch (error) {
  /* Axios error instance.*/
  const { response, request } = error;

  if (response) {
    if (response.status === 504) {
      /* Gateway timeout, retryable. */
    } else if (response.data.result.errorCode === 'OPERATION_FAILED') {
      /* Server side error, retryable. */
    } else {
      /* Log the error and fix the request then resend it. */
    }
  } else if (request) {
    /* http.ClientRequest instance.
       Possible network error. Retryable. */
  } else {
    /* Something happened in setting up the request that triggered an Error.
       Log the error and try to fix the problem then resend the request. */
  }
}

The error.response.data object is always normalized to the following format:

{
  result: {
    funcCode: 'funcCode',
    errorCode: 'errorCode',
    message: 'message',
  },
  technicalValidationMessages: [
    {
      validationResultCode: 'validationResultCode',
      validationErrorCode: 'validationErrorCode',
      message: 'message',
    },
    {
      validationResultCode: 'validationResultCode',
      validationErrorCode: 'validationErrorCode',
      message: 'message',
    },
  ],
}

Take note properties funcCode, errorCode and message can be undefined and technicalValidationMessages length can be zero but response.data and result are always an object and technicalValidationMessages is always an array.

Tests

Copy the file named .env.example and rename it to .env in the root of the repository and replace placeholder values with your own technical user's data.
⚠️Never edit the .env.example file and never commit your sensitive data!

$ npm run test

TODO

These operations are currently not supported by the project:

• queryInvoiceChainDigest
• queryInvoiceCheck
• queryTransactionList

Maintainers

This repository is maintained by ANGRO Nagykereskedelmi Kft.

License

GPL-3.0