Invoicing Service

Build Status Dependencies Coverage Status

A microservice for generating invoices.

Features

  • Generates invoices for customers based on their purchased products.

  • When all data is aggregated, it is rendered into HTML through the rendering-srv and to PDF using the pdf-rendering-srv.

  • The header and footer templates for PDF rendering are served via HTML files.

  • All invoices are sent via notification objects to the notification-srv so that they can be sent via email to the customers' billing addresses.

  • The Invoice Positions sent to this service are stored on redis (db index 7) and Invoice creation is triggered by io.restorecommerce.invoice.TriggerInvoices event named triggerInvoices which sends out the notifications to customers. Invoices are also a resource owned by this microservice. After an invoice is generated, it is stored in the database along with useful metadata. Therefore, some CRUD operations are exposed via gRPC in order to remotely handle this resource.

Configuration

The following service specific configuration properties are available:

API

This microservice exposes the following gRPC endpoints:

Invoice

An Invoice resource.

io.restorecommerce.invoice.Invoice

Field Type Label Description

id

string

optional

User ID, unique, key

created

double

optional

Date when user was created

modified

double

optional

Date when user was modified

timestamp

string

optional

Invoice creation timestamp

customer_id

string

optional

The customer’s database ID

payment_status

string

optional

Default: 'unpaid'

total_amount

double

optional

Invoice total (gross)

net_amount

double

optional

Invoice net

vat_amount

double

optional

Invoice vat

document

string

optional

Generated PDF base64-encoded

invoice_number

string

optional

Generated invoice number

customer_remark

string

optional

Customer’s remark

The service exposes Read and Delete operations through gRPC. To further read about their interface please refer to resource-srv.

io.restorecommerce.invoice.InvoicesPositionsData:

Field Type Label Description

invoices_positions_data

io.restorecommerce.invoice.InvoicePositions [ ]

required

Invoice Positions Data

io.restorecommerce.invoice.InvoicePositions:

Field Type Label Description

id

string

optional

contract or customer identifier

invoice_positions

io.restorecommerce.invoice.InvoicePosition [ ]

optional

Invoice Position

recipient_customer

io.restorecommerce.invoice.RecipientCustomer

optional

Recipient customer identifier

recipient_billing_address

io.restorecommerce.invoice.BillingAddress

optional

Recipient Billing Address

sender_billing_address

io.restorecommerce.invoice.BillingAddress

optional

Sender Billing Address

recipient_organization

io.restorecommerce.organization.Organization

optional

Recipient Organization Address

sender_organization

io.restorecommerce.organization.Organization

optional

Sender Organization Address

payment_method_details

io.restorecommerce.invoice.PaymentMethodDetails

optional

Payment Method Details

invoice_no

string

optional

invoice number if not provided the service will generate one

from_date

double

optional

value performance from date

to_date

double

optional

value performance to date

io.restorecommerce.invoice.InvoicePosition:

Field Type Label Description

currency

string

optional

currency

invoiceRows

io.restorecommerce.invoice.InvoiceRow [ ]

optional

Invoice row data

totalPrice

io.restorecommerce.invoice.InvoicePrice

optional

Total price

io.restorecommerce.invoice.InvoiceRow:

Field Type Label Description

product

string

optional

currency

pricePerUnit

double

optional

price per unit

quantity

integer

optional

number of products

vat

string

optional

value added tax

amount

double

optional

total amount

io.restorecommerce.invoice.InvoicePrice:

Field Type Label Description

gross

integer

optional

gross price

net

integer

optional

net price

io.restorecommerce.invoice.RecipientCustomer:

Field Type Label Description

id

string

optional

customer identifier

customer_number

string

optional

customer number

io.restorecommerce.invoice.BillingAddress:

Field Type Label Description

email

string

optional

sender or recipient email

website

string

optional

sender or recipient website

street

string

optional

sender or recipient street name

building_number

string

optional

sender or recipient building number

postcode

string

optional

sender or recipient postcode

region

string

optional

sender or recipient region

country_name

string

optional

sender or recipient country

phone_country_code

integer

optional

sender or recipient phone country code

phone_number

integer

optional

sender or recipient phone number

timezone

string

optional

sender or recipient time zone

economic_area

string

optional

sender or recipient country economic area

io.restorecommerce.invoice.PaymentMethodDetails:

Field Type Label Description

type

string

optional

Payment Method identifier

iban

string

optional

Payment Method iban

bic

string

optional

Payment Method bic

bankName

string

optional

Payment Method bank name

transferType

string

optional

Payment Method transfer type

eMail

string

optional

Payment Method email

CRUD Operations

The microservice exposes the below CRUD operations for creating or modifying Invoice resources.

io.restorecommerce.invoice.InvoiceService

Method Name Request Type Response Type Description

Create

io.restorecommerce.invoice.InvoiceList

io.restorecommerce.invoice.InvoiceList

Create a list of Invoice resources

Read

io.restorecommerce.resourcebase.ReadRequest

io.restorecommerce.invoice.InvoiceList

Read a list of Invoice resources

Update

io.restorecommerce.invoice.InvoiceList

io.restorecommerce.invoice.InvoiceList

Update a list of Invoice resources

Delete

io.restorecommerce.resourcebase.DeleteRequest

Empty

Delete a list of Invoice resources

Upsert

io.restorecommerce.invoice.InvoiceList

io.restorecommerce.invoice.InvoiceList

Create or Update a list of Invoice resources

For the detailed protobuf message structure of io.restorecommerce.resourcebase.ReadRequest and io.restorecommerce.resourcebase.DeleteRequest refer resource-base-interface.

Events

Emitted

List of events emitted by this microservice for below topics:

Topic Name Event Name Description

io.restorecommerce.notification_req

sendEmail

send generated notifications

io.restorecommerce.rendering

renderRequest

request notifications content rendering

io.restorecommerce.jobs

jobDone

commit job failure or completion

io.restorecommerce.invoices.resource

triggerInvoices

trigger invoices

Consumed

This microservice consumes messages for the following events by topic:

Topic Name Event Name Description

io.restorecommerce.invoices.resource

storeInvoicePositions

storing invoice positions and triggering invoices

io.restorecommerce.command

restoreCommand

for triggering system restore

resetCommand

for triggering system reset

healthCheckCommand

to get system health check

versionCommand

to get system version

io.restorecommerce.rendering

renderResponse

receive rendered notifications content

io.restorecommerce.organizations.resource

deleteOrgData

for deleting organization data

Custom Commands

This service extends the command-interface in order to provide custom functionality:

  • restore - the base restore operation is extended to additionally restore the invoice number’s incremental counter in Redis

  • reset - the base reset operation is overridden in order to reset the invoice’s number incremental counter in Redis

TODO: Resource Caching with Redis

  • Resources are loaded via gRPC calls. Currently, they are stored in local variables which are then statically accessed. An efficient caching mechanism using Redis with some expiration time is to be used.

Part of the Restorecommerce.