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.
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.
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.
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.
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.
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.
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:
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)
Grade | Requirements |
|---|---|
STRETCH GOAL | All below and introducing a novel functionality specific to e-invoice creation. The API design should follow defense in depth, well documented errors, relatively quick response times, and fully deployed on cloud. |
MEDIUM PRIORITY | All below and the API supports multiple input formats with enhanced usability, follows efficient REST practices. eg. API authentication, flexibility for end users, and comprehensive documentation. |
MAJOR PRIORITY | The API supports at least one input format with high accuracy and usability, follows appropriate REST practices. eg. status codes are appropriate, input and response formats are documented. |
MVP | The API supports at least one input format, and follows basic REST principles and practices. |
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:
Be in a Machine-readable format (i.e JSON, HTML, PDF)
Indicate which validation rules are violated.
Provide additional information on why the rule was violated.
*Optional* Suggest quick-fix methods to validate the rules.
Marking
Grade | Requirements |
|---|---|
STRETCH GOAL | All below and introducing a novel functionality specific to e-invoice creation. The API design should follow defense in depth, well documented errors, relatively quick response times, and fully deployed on cloud. Suggesting quick-fix methods would be a great addition as a novel functionality. |
MEDIUM PRIORITY | All below and the API supports multiple machine readable output formats with enhanced usability, follows efficient REST practices. eg. API authentication, flexibility for end users, and comprehensive documentation. Also provides more details on why the role was violated. |
MAJOR PRIORITY | The API supports enhanced validation (majority of syntax and peppol rules), one output format with high accuracy and usability, follows appropriate REST practices. eg. status codes are appropriate, input and response formats are documented. |
MVP | The API supports basic validation (wellformedness, some syntax and peppol rules), and provides at least one machine readable output format. |
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
has been converted in PDF as follows:
Marking
Grade | Requirements |
|---|---|
STRETCH GOAL | All below and introducing a novel functionality specific to e-invoice rendering. The API design should follow defense in depth, well documented errors, relatively quick response times, and fully deployed on cloud. |
MEDIUM PRIORITY | All below and the API supports multiple output formats with enhanced usability (style templates), follows efficient REST practices. eg. API authentication, flexibility for end users, and comprehensive documentation. Detailed error codes on why the input couldn’t be processed. |
MAJOR PRIORITY | The API supports rendering at a level which is accessible and follows a consistent format for invoices with different missing fields, handles invalid invoices appropriately and follows appropriate REST practices. eg. status codes are appropriate, input and response formats are documented. |
MVP | The API supports basic e-invoice rendering in one of the output formats for a valid e-invoice input, essential REST practices. |
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
Goals | Requirements |
|---|---|
STRETCH GOAL | All below and introducing a novel functionality specific to e-invoice sending. The API design should follow defence in depth, well documented errors, relatively quick response times, and fully deployed on cloud. |
MEDIUM PRIORITY | All below and the API supports multiple mediums to send e-invoices with enhanced usability (style templates), follows efficient REST practices. eg. API authentication, flexibility for end users, and comprehensive documentation. Batch processing is a recommended feature. |
MAJOR PRIORITY | The API is capable of sending e-invoices to using different mediums to multiple recipients, handles invalid invoices appropriately (with some useful output) and follows appropriate REST practices. eg. status codes are appropriate, input and response formats are documented. |
MVP | The API supports basic e-invoice sending using one of the suggested mediums and a valid communications report is returned. |
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
Grade | Requirements |
|---|---|
STRETCH GOAL | |
MEDIUM PRIORITY | |
MAJOR PRIORITY | |
MVP |
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 stores 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
Grade | Requirements |
|---|---|
HIGH DISTINCTION | |
DISTINCTION | |
CREDIT | |
PASS |