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. A simple success response is sufficient, but some running statistics of your service is preferable.

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.