Student teams will develop an e-invoicing application in two phases. In phase 1, you need to develop a SaaS API to perform an e-invoicing function in the ecosystem according to one of the categories listed in the document ”Introduction to e-invoicing”. The API must be deployed and made available for other teams to use.

General API requirements

The notes below are applicable to all 6 categories. There are some general suggestions on what you should consider when designing your service.

1. Design your service: For each of the categories, except being specified by this spec, you should consider and decide what input of your service requires, then design what the output should look like.

2. Consider the cost of usage: Since your services may be required by other teams in stage 2, it is essential that you make your service easy to be used as a module by others, including providing documentation, supporting multiple formats of input and output, having reasonable performance, etc.

3. Start simple: It is hard to cover all possible formats of input and output for each of the services in this given time frame. It is important for each group to prioritise the functionalities of the service and deliver the most important functions first. You should consider starting from a very basic service, then keep iterating the service.

4. Things can change. Mentors will constantly give additional details which may change the spec during the project to add new information, answer FAQs etc. It is important that you reflect/document these changes continuously in your deployed version.

5. Understand the standard. By recommended standardised format, we mean UBL 2.1 XML format. This format and associated sample files are described in a separate document. 

6. Implement health check endpoint. When implementing your service, please implement an endpoint that indicates the aliveness of your services if your service is stateful. A simple success response is sufficient, but some running statistics of your service is preferable. This is to let a developer check if your service is still alive.

 Ecosystem summary

The figure below summarises all API categories in the ecosystem:

Open

Invoice Creation

Only standardised data can be processed by other categories of services. To reduce the barrier for customers to use the system, the customer should be able to convert data from their current system to standard e-invoices in batches.

For this category, your service should be able to create standardised e-invoices from an existing information system or allow information to be imported from external sources. Although you are not expected to be able to extract information from a random source like websites or articles, services in this category should be able to process pre-formatted data. The service should extract any useful data from the source and assemble invoices as per the standard.

Input

You should define the data structure required by your service. You may define optional and compulsory fields, but more compulsory fields generally mean you will handle fewer exceptions in the service but reduce the usability and generality of the service. Below are some possible formats for input, the implementation of your service can support some of them, or even something not on the list.

• CSV

• JSON

• XML/HTML

• Excel

• SQLTables

Output

Your output should conform to the UBL 2.1 XML format. i.e. Your output should be able to pass any correctly implemented validator mentioned in the “Invoice Validation” section of this document. Since there are many fields and constraints in the standard, a microservice should consider starting by generating minimised invoices first.

Measure of Priority (Draft)

Invoice Validation

Creates a report outlining any validation errors according to Australian rules.

Details of Validation rules can be found in Appendix A and B of the document below https://github.com/A-NZ-PEPPOL/A-NZ-PEPPOL-BIS-3.0/blob/master/Specifications/A-NZ_Invoice_Extension_v1.0.6.docx

In order to maintain an efficient system, it is essential that the invoices are validated based on the rules employed by a governing entity. The validation system aids to detect and rectify errors before a payment is initiated.

The validation microservice has four components:

• Validating Wellformedness (Checking if the input is valid and the file itself has valid contents)

• Syntax Rules (Validates EN16931 business rules) (Appendix B, BR Rules)

• PEPPOL rules (Validates Specific AUNZ business rules) (Appendix B, PEPPOL Rules)

• Schema Validation (Validates the schema of the invoice

Note: Schema rules are rules concerning what tags are allowed in the UBL XML file. For example tag cac:BillingReference is a valid tag and tag <cac:sydney> is invalid. It is also specifies how the tags are sequenced. Schema rules are contained in a XSD file. In this case, the UBL XSD file is downloadable at: docs.oasis-open.org/ubl/os-UBL-2.1/xsd/maindoc/UBL-Invoice-2.1.xsd To validate and XML file, you need to find a library that does schema validation in your programming language.

Input

The input to this microservice will be a UBL 2.1 XML format invoice. 

Output

The output of this microservice should:

1. Be in a Machine-readable format (i.e JSON, HTML, PDF)

2. Indicate which validation rules are violated.

3. Provide additional information on why the rule was violated.

4. *Optional* Suggest quick-fix methods to validate the rules.

Marking

Invoice Rendering

Not everyone can read notations for a computer like XML and JSON. People would prefer to see statistics shown in proper formatted tables or graphs. This category of service is targeted at end-users who may not be familiar with the UBL format of electronic invoices. Therefore, you should design your service to display the information contained in a machine-readable format file to a human-readable representation interface, in a reasonable manner. 

Input

Input will conform to the UBL format in the recommended format. (i.e., The input should be able to pass the validator mentioned in the “Invoice Validation” section). But you should consider and define how your service takes the input.

Output

You should design your output to make it human friendly. The output can be, but not limited to a PDF, an HTML file or an image file. If the invoice is malformed, it is preferable that your service displays a human-readable message. You may even make the service to be multilingual, which supports the request to generate output in a second language.

As an example, the input file

Open

has been converted in PDF as follows:

Open

Marking

Invoice Sending

After invoices are generated, the system needs a way to distribute the invoices to corresponding recipients. This category of services should be able to deliver invoices from the internal of the system to some external environment. You need to design the way how invoices are delivered. Some possible ways can be email, SFTP or even SMS. 

Input

Input will conform to the UBL format in the recommended format. (i.e., The input should be able to pass the validator mentioned in the “Invoice Validation” section). But you should consider and define how your service takes the input.

Output

The observable output of this service includes a report and a side effect. After the API call, your service should send the invoice, then return a communication report. The format of the report can be but not limited to JSON, HTML, PDF. If there is any communication error. it is preferable that your service reacts with a human-readable message. A simple synchronous API call without delivering information to external is acceptable as a start, but not sufficient for the service.

Marking

Invoice Receiving

Invoices may also be exchanged between different systems. Therefore, to better manage invoices, the system needs a component that can receive invoices from the external environment. This category of service should be able to retrieve e-invoices from a developer-designated media, which can possibly be API calls, email, SFTP, chatbot, or even SMS. Your service should be able to detect the new invoices.

Input

Input should conform to the UBL format in the recommended format. (i.e., The input should be able to pass the validator mentioned in the “Invoice Validation” section). But you should consider and define how your service takes the input. You should design an asynchronous mechanism to get information. A simple upload HTTP API without any validation is acceptable as a start, but not sufficient for the service.

Output

The observable output of this service includes a report. After the API call, your service should return a communication report. The format of the report can be but not limited to JSON, HTML, PDF. In a successful execution, the service should persist the invoice. If there is any communication error, it is preferable that your service reacts with a human-readable message. 

Marking

Invoice Storage

Data becomes powerful only when information starts to have relations.  It is not sufficient to only have thousands of separate electronic invoices files. A good invoicing system should include a component that is able to manage its storage. (Think about the relationship between a book, a librarian and a library.) This category of service manages the storage and saves a large number of standard invoices. Reliability and performance are the core of this type of service. You should design and implement a mechanism to store standardised e-invoices, making use of existing/open-sourcing technologies. You can include relational databases, NoSQL databases, file systems, or even caching mechanisms in your storage mechanism. In some cases, you may need to discuss the use cases and balance reliability and performance. To deliver extreme experiences, consider reliability and performance separately in different situations. 

Input

Input will conform to the UBL format in the recommended format. (i.e., The input should be able to pass the validator mentioned in the “Invoice Validation” section). But you should consider and define how your service takes the input.

Output

An information system or an implemented mechanism to persist invoices. If an input is malformed, it is preferable that your service displays a human-readable message. Your service should allow someone else to extract invoices from your services. It is meaningless to only receive information without taking it out. Supporting more types of querying like filtering, modification or deletion can also enhance the service.

Marking