Implement queryTaxPayer & registerCreditEntry function by passatgt · Pull Request #85 · ewngs/szamlazz.js

passatgt · 2025-01-21T00:05:37Z

This pull request introduces the queryTaxPayer function, which queries taxpayer details from the Számlázz.hu API(which mirrors the NAV API). The implementation ensures proper XML handling, response parsing. The response contains the validity of the tax payer id and if its valid, it will return the address and name in the following format:

{
  taxpayerValidity: true,
  taxpayerId: '12345678',
  vatCode: '2',
  countyCode: '41',
  taxpayerName: 'taxpayerName KERESKEDELMI ÉS SZOLGÁLTATÓ KORLÁTOLT FELELŐSSÉGŰ TÁRSASÁG',
  taxpayerShortName: 'taxpayerName KFT.',
  address: {
    countryCode: 'HU',
    postalCode: '1000',
    city: 'BUDAPEST',
    streetName: 'TESZT',
    publicPlaceCategory: 'UTCA',
    number: '1.'
  }
}

Also adds the registerCreditEntry function, which you can use to mark an invoice as paid by registering a credit entry.

Helps to parse NAV API response

ert78gb

thank you for the PR. I have some modification request please review them.
I would like to ask you next time please open individual pull request for every feature or bug fix.

ert78gb · 2025-01-26T16:00:53Z

lib/CreditEntry.js

@@ -0,0 +1,45 @@
+import assert from 'assert'
+import merge from 'merge'


please delete the unused import

ert78gb · 2025-01-26T16:04:19Z

lib/CreditEntry.js

+import {wrapWithElement} from './XMLUtils.js'
+import {PaymentMethod, PaymentMethods} from  './Constants.js'
+
+const defaultOptions = {


Not needed the defaultOptions just overcomplicate the code. You could simply set the default values in the line 11 and 12

ert78gb · 2025-01-26T17:25:23Z

lib/Client.js

  }

+  async queryTaxPayer (taxPayerId) {
+    assert(typeof taxPayerId === 'number' && /^[0-9]{8}$/.test(taxPayerId.toString()), 'taxPayerId must be an 8-digit number');


You expect the taxPayerId should be a number but after you convert it to string to validate with regexp.
taxPayerId is string in the xsd documentation. In the response we also return as string so I think better not expect a number type.
We have 2 options expect a string type or don't expect any type because the regexp do string coercion.

I would like if we expect string type. Don't forget to update the readme.md too

ert78gb · 2025-01-26T17:26:52Z

lib/Client.js

    return data
  }

+  async queryTaxPayer (taxPayerId) {


Please add a jsdoc especially of the input and returns type.

ert78gb · 2025-01-26T17:36:28Z

lib/Client.js

+
+    const response = await this._sendRequest('action-szamla_agent_taxpayer', xml)
+    const parsedBody = await parseString(response.data)
+    const cleanParsedBody = removeNamespaces(parsedBody);


I think the removeNamespaces utility function is not necessary it is just an overhead. We could read the properties of the object with namespace.

what if the namespace changes? happened before... :)

I have never used the Nav API. I found the https://github.com/nav-gov-hu/Online-Invoice, looks like it is up to date.
Based in it the address DetailedAddressType in the base namespace.
All of the xml example response contain descriptive namespace prefixes. I don't know why the szamlazz.hu returns with nsX. Anyway the response contains the namespace definition xmlns:nsX="http://schemas.nav.gov.hu/OSA/3.0/base". Based on that we could properly find the proper namespace prefix of the schema.

If you think it is overcomplicated and Nav never will use the same element name from more namespace we could strip the prefixes but in this case please use the built in feature of the xml parser lib.

Just for a note. I called 4 times the queryTaxPayer method and once I got NAV API is not available response. Looks like it not HA.

ert78gb · 2025-01-26T18:36:49Z

tests/resources/setup.js

+ */
+export function createCreditEntry(CreditEntry) {
+  return new CreditEntry({
+    paymentMethod: PaymentMethod.BankTransfer,


PaymentMethod does not have the BankTransfer property. I am fixing other invalid setup in the file after the CR

ert78gb · 2025-01-26T18:42:16Z

lib/Item.js


    return wrapWithElement('tetel', [
      [ 'megnevezes', this._options.label ],
+      [ 'azonosito', this._options.id ],


please extend the readme.md with this optional property

ert78gb · 2025-01-26T18:48:17Z

lib/Client.js

+      '</xmlszamlakifiz>'
+
+    const httpResponse = await this._sendRequest('action-szamla_agent_kifiz', xml)
+    const data = {


please implement error branch too

ert78gb · 2025-01-26T18:52:25Z

lib/Client.js

+    };
+  }
+
+  async registerCreditEntry (options, creditEntries) {


To follow the lib pattern please create a new complex type that contains the options and creditEntries.
Move the assert from this method to the new type.

Are you sure about this one? I don't see this being used by other already implemented functions in the Client class.

All of the public interfaces of the Client accept only 1 input argument. The options and creditEntries can be easily merge into 1 object like

const creditEntry = new CreditEntry({ invoiceId: 'something', taxNumber: '', additive: true, entries: [ new CreditItem({ date: new Date(), paymentMethod: PaymentMethods.BankTransfer, amount: 0 }) ] })

BTW just now recognised in the szamlazz.hu documentation it allows maximum 5 kifizetes type

ert78gb · 2025-01-26T19:00:08Z

tests/client.spec.js

+      beforeEach(() => {
+        nock('https://www.szamlazz.hu')
+          .post('/szamla/')
+          .replyWithFile(200, RESPONSE_FILE_PATHS.SUCCESS_WITHOUT_PDF, {


the success response of the request is xmlagentresponse=DONE text. If I read well the documentation.

ert78gb · 2025-01-28T19:58:49Z

tests/resources/valid_taxpayer.xml

@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="utf-8"?>


please keep the namespace and other meta data elements like header, funcCode, software, etc

ert78gb · 2025-01-28T20:02:29Z

lib/Client.js

+        'beallitasok', [
+          ...this._getAuthFields(),
+          ['szamlaszam', options.invoiceId],
+          ['adoszam', options.taxNumber || ''],


it is an optional filed. please don't set a default value . We save some bandwidth with it

passatgt added 5 commits January 21, 2025 00:28

Add queryTaxPayer function

fc02e47

Add removeNamespaces function

b771206

Helps to parse NAV API response

Add readme and test cases about the queryTaxPayer function

8fd26ee

Registering credit entry function

30ce21c

Update test for registerCreditEntry

bb4280e

passatgt changed the title ~~Implement queryTaxPayer function~~ Implement queryTaxPayer & registerCreditEntry function Jan 21, 2025

Add support for item ID field

0cb35b9

ert78gb requested changes Jan 26, 2025

View reviewed changes

ert78gb reviewed Jan 28, 2025

View reviewed changes

passatgt added 3 commits August 7, 2025 18:05

Additional address parameters for queryTaxPayer response

58d7b61

Add 'K.AFA' to VAT options in Item.js

7e7f480

Fix string formatting in VAT condition check

feb42fb

		@@ -0,0 +1,45 @@
		import assert from 'assert'
		import merge from 'merge'

Conversation

passatgt commented Jan 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ert78gb left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

passatgt commented Jan 21, 2025 •

edited

Loading