Giters

incodehq / estatio-supporting-doc-client

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

README

Table of Contents

This repo has sample code which can be used to retrieve supporting PDFs (supplier receipts and tax receipts) associated with outgoing invoices generated by Estatio. There are two REST endpoints:

  • lease.SupportingDocumentService#findInvoicesWithSupportingDocuments

    which returns a list of invoice numbers for a given year.

    As a check, the seller and buyer references of the invoice must also be supplied and must match the data held by Estatio.

  • lease.SupportingDocumentService#findSupportingDocuments

    which returns all supporting documents for a given invoice number/year.

There are two implementations for each of these functions:

  • the simpler uses the canonical data structures defined by the incodehq/estatio-canonical supporting library.

  • the alternative has no external dependencies, dealing only in terms of XML Documents.

In all this results in four classes:

Table 1. Client classes
Function Canonical Implementation Raw Implementation

Find Invoices with Supporting Documents

DocListClient.

Uses the InvoiceNumbersDto DTO (provided by canonical library).

XmlDocListClient

Uses XPath expression to process resultant XML.

Find Supporting Documents for given Invoice

DocClient

Uses the DocumentsDto DTO (provided by canonical library).

XmlDocClient

Uses XPath expression to process resultant XML.

The sections below explain how to use either set of clients together.

DocListClient & DocClient

The code below shows the typical usage.

final String host = "https://estatio.int.ecpnv.com";
final String user = "docreader";
final String pass = "pass";
final DocListClient docListClient = new DocListClient(host, user, pass);

final InvoiceNumbersDto invoiceNumbersDto = docListClient.fetch(2017, "IT01");
final List<InvoiceNumberType> invoiceNumbers = invoiceNumbersDto.getInvoiceNumbers();

for (final InvoiceNumberType invoiceNumberDto : invoiceNumbers) {
    final String invoiceNumber = invoiceNumberDto.getInvoiceNumber();
    final String sellerReference = invoiceNumberDto.getSellerReference();
    final String buyerReference = invoiceNumberDto.getBuyerReference();
    DocumentsDto documentsDto =
        docClient.fetch(invoiceNumber, year, sellerReference, buyerReference);

    // ... do whatever.
}

The InvoiceNumbersDto DTO exposes a list of invoice numbers of only those invoices that have supporting documents, for a given year, and for the given seller reference (ie company code).

Tip

If the seller reference is left as null, then invoices for all companies will be returned. Alternatively, simply call the overload which does not specify the company code (eg, docListClient.fetch(2017) ).

These invoice numbers and year can then be used to obtain the DocumentsDto exposes all supporting documents as base 64 encoded strings of PDF byte[] array.

As a convenience, the clients also include helper methods to dump the document(s) to the filesystem. For example:

docListClient.fetchAndWrite(2017, "IT01", "target/files");

This will write all documents for all invoices (for seller "IT01" and year 2017), each in a separate subdirectory.

Dependencies

As noted above, the library uses incodehq/estatio-canonical which defines the InvoiceNumbersDto and DocumentsDto structures. This library can be downloaded from the Maven repo hosted at repo.incode.cloud.

If not using Maven, you can download the JAR file directly.

There are no other third-party dependencies.

XmlDocListClient & XmlDocClient

The code below shows the typical usage.

final String host = "https://estatio.int.ecpnv.com";
final String user = "docreader";
final String pass = "pass";
final XmlDocListClient docListClient = new XmlDocListClient(host, user, pass);

final org.w3c.dom.Document xmlDoc = xmlDocListClient.fetch(2017, "IT01");

This returns an XML Document which list of invoice numbers of only those invoices that have supporting documents, for a given year, and for the given seller reference (ie company code).

Tip

If the seller reference is left as null, then invoices for all companies will be returned. Alternatively, simply call the overload which does not specify the company code (eg, xmlDocListClient.fetch(2017) ).

This resultant XML Document must then be parsed. The invoice numbers can be accessed under /invoiceNumbersDto/invoiceNumbers/invoiceNumber

As a convenience, the client also includes a helper which will dump the document(s) to the filesystem:

xmlDocListClient.fetchAndWrite(2017, "target/files-xml");

For more fine-grained control, the XmlDocClient can be used to obtain all the (PDF) documents for an invoice:

final String host = "https://estatio.int.ecpnv.com";
final String user = "docreader";
final String pass = "pass";
final XmlDocClient xmlDocClient = new XmlDocClient(host, user, pass);

final org.w3c.dom.Document xmlDoc = xmlDocClient.fetch("CAR-0259", 2017, "IT01", "ITCL10611");

Again, the resultant XML Document must be parsed. The base 64 encoded byte array for each of the PDF(s) can be accessed under /documentsDto/documents/document.

Testing

This library includes simple JUnit tests for each client, namely DocListClient_Test, DocClient_Test, XmlDocListClient_Test and XmlDocClient_Test.

Change Log

0.4

  • extends the list clients so that these can optionally also qualify on sellerReference.

0.3

  • runs against updated version of Estatio, which now requires that sellerReference and buyerReference are now supplied when querying for an invoice. These values must match those of the invoice, otherwise no documents are returned. This guards against possibly invalid data held by the caller.

  • reflected by new parameters sellerReference and buyerReference now required by DocClient / XmlDocClient.

    Note

    The document list retrieved by DocListClient / XmlDocListClient has been updated so that it includes these fields. The tests of the two XxxListClients utilize this.

  • bumps to corresponding new version of estatio-canonical.

0.2

  • DocListClient and XmlDocListClient added.

  • year parameter is now an int, not a String

  • host parameter (to constructor) now also expects the protocol (eg prefix "https://").

0.1

  • initial version of DocClient and XmlDocClient

About

Languages

Language:Java 100.0%