# @angro/nav-connector 中文文档

规范地址：https://npmcn.com/package/%40angro/nav-connector/

版本：6\.1\.1
npm 元数据更新时间：2024-12-18T09:45:01.019Z
中文译文更新时间：2026-11-06T04:06:21.584Z
软件包许可：GPL-3\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40angro/nav-connector
原文对照：https://npmcn.com/package/%40angro/nav-connector/?lang=original
项目主页：https://github.com/angro-kft/nav-connector#readme
源码仓库：https://github.com/angro-kft/nav-connector

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：198 kB，46 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>= 8\.11\.2
- 运行依赖：5 个
- 首次发布：2018-04-10T06:08:49.207Z
- 最新版本发布：2024-01-10T14:59:26.779Z
- 近 30 天下载量：5433（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 0 个）

## 中文简介

提供与NAV在线发票服务通信接口的Node.js模块.

## 安装

```sh
npm install @angro/nav-connector
```

也可以使用：`pnpm add @angro/nav-connector`、`yarn add @angro/nav-connector`、`bun add @angro/nav-connector`

## README

# 导航连接器

[![codecov](https://codecov.io/gh/angro-kft/nav-connector/branch/dev/graph/badge.svg)](https://codecov.io/gh/angro-kft/nav-connector) [![npm (scoped)](https://img.shields.io/npm/v/@angro/nav-connector.svg)](https://www.npmjs.com/package/@angro/nav-connector) [![license](https://img.shields.io/github/license/angro-kft/nav-connector.svg)](https://github.com/angro-kft/nav-connector/blob/dev/LICENSE) ![nav](https://img.shields.io/badge/NAV%20service%20version%20compatible-2.10-blue.svg) ![nav-interface](https://img.shields.io/badge/NAV%20interface%20version%20compatible-3.0-blue.svg)

提供与NAV在线发票服务通信接口的Node.js模块.

本单元的开发是为了满足下列要求:  
[在线发票接口规格](https://onlineszamla-test.nav.gov.hu/api/files/container/download/Online%20Szamla_Interfesz%20specifik%C3%A1ci%C3%B3_EN.pdf)

## 安装

以Node.js的12.18.3版本被测试.

```sh
$ npm install @angro/nav-connector
```

## 示例

```js
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 密码

### 导航器

类别代表NAV在线发票数据服务规范的实施.

```js
/**
 * 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超时选项,因为在NAV服务停用期间,如果不设置Axios超时选项,请求可能永远不会超时.  
根据NAV在线发票服务文件,请求超时时间设定为服务方5000 mss 但实际上可能没有超时,或者在60秒后会有网关超时. 超时设定为在轴中为70000毫秒(70秒)作为默认.  
你可以很好地调谐这个值,但它强烈建议将其保持在60秒以上,以避免掉落的响应.

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

### navConnector.manage 语音( )

向NAV服务发送单张或多张发票的方法. 该方法返回业务的交易id,该id可用于以后获得这一请求的发票处理状态.

```js
/**
 * 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);
```

发票操作参数示例:

```js
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',
    },
  ],
};
```

请注意 在使用管理发票方法之前,您必须自己压缩发票.

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

### navConnector.manage-Annulment () (美国英语)

向NAV服务机构发送单张或多张发票废止书的方法. 该方法返回业务的交易id,该id可用于以后获得这一请求的发票处理状态.

```js
/**
 * 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);
```

无效操作参数示例:

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

### navConnector.query 交易状态( )

处理以前发来发票的方法。 解析后返回值是规格的处理ResultListType.

```js
/**
 * 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. */
});
```

此函数会根据NAV服务文档在响应中键入数字和布尔键入值的转换.

### navConnector.testConnection () () (中文(简体) )

测试连接、 用户认证数据和密钥有效性的方法 .

```js
/**
 * 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.query 语音数据( )

查询以前发出的发票的方法,发票号.

```js
/**
 * 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
 */
```

#### 按发票号码查询

```js
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;
```

此函数会根据NAV服务文档在响应中键入数字和布尔键入值的转换.

### navConnector.query 语音数据( )

以查询参数查询先前发出的发票的方法.

```js
/**
 * 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
 */
```

#### 按参数查询

```js
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;
```

此函数会根据NAV服务文档在响应中键入数字和布尔键入值的转换.

### navConnector.query 纳税人 ()

按税号取得纳税人信息的方法.  
它解决包含纳税人Validity和纳税人Data属性的对象.  
考虑到纳税人Data财产如果不存在税号,国家税务局将不予退还.

```js
/**
 * 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. */
}
```

此函数会根据NAV服务文档在响应中为布尔键入值进行类型转换.

## 处理错误

所有的方法都能够抛出期望,并且你可以精细地调谐如何记录这些错误,处理这些错误或者如果可能的话重试请求.

```js
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. */
  }
}
```

错误. response.data 对象总是恢复正常化为以下格式:

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

注意属性 funcCode, 错误代码和消息可以是未定义的, 技术性的ValidationMessages 长度可以是 0, 但是 响应.数据与结果总是一个对象,技术变量总是一个阵列.

## 测试

复制名为的文件 `.env.example` 并重命名为 `.env` 在寄存器根中,将占位符值替换为自己的技术用户数据.  
⚠️**永不编辑 `.env.example` 并且永远不要提供敏感数据!**

```sh
$ npm run test
```

## 开始

目前这些项目没有支持:

-   查问InvoiceChanDigest
-   查询发票检查
-   查询交易列表

## 维护者

这个寄存器由 [(原始内容存档于2017-10-21). ANGRO Nagykereskedelmi Kft.](https://angro.hu/)

## 许可证

[GPL-3.0 (英语)](https://npmcn.com/package/%40angro/nav-connector/LICENSE)

## 常见问题

### @angro/nav-connector 是什么？

提供与NAV在线发票服务通信接口的Node\.js模块\.

### 如何安装 @angro/nav-connector？

在项目目录运行 npm install @angro/nav-connector，或使用 pnpm add / yarn add / bun add。

### @angro/nav-connector 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/angro\_\_nav-connector 是否存在。

### @angro/nav-connector 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @angro/nav-connector 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 8\.11\.2。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @angro/nav-connector 可以商用吗？

@angro/nav-connector 使用 GPL-3\.0 许可。强 Copyleft：分发包含该代码的软件时，整个作品需以 GPL-3\.0 兼容许可开源，并附带专利与反锁定条款。仅内部使用不触发此义务。以上为概括，不构成法律意见，请以许可原文为准。

### @angro/nav-connector 的下载量有多少？

根据 npm 官方下载统计，@angro/nav-connector 在 2026/10/06 – 2026/11/04 这 30 天内被下载 5,433 次，日均约 181 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @angro/nav-connector 还在维护吗？

最新版本 6\.1\.1 发布于 2024/01/10（2 年前）；至今共发布 24 个版本，其中过去 12 个月发布了 0 个；首次发布于 2018/04/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。