White-label

Introduction

Many software platforms use Invopop, from Point-of-Sale (POS) and Enterprise Resource Planning (ERP) systems to vertical SaaS solutions. These platforms typically have basic invoicing features and integrate Invopop to provide compliant e-invoicing to their customers. We call this use case white-labeling, and we’ve built Invopop to excel at supporting it programmatically.

To illustrate this integration, we’ll follow the example of Hotelpop, a hotel management SaaS platform. Through Hotelpop’s interface, front desk staff can input customer information, add charges, and create PDF invoices. As the platform expands internationally, hotels need to comply with local e-invoicing regulations that require converting invoices to XML formats and submitting them to tax authorities.

To meet these requirements, Hotelpop chose to white-label Invopop.

Prerequisites

Before starting, you should understand Invopop basics, including our API, GOBL, workflows. You should have followed a country-specific guide (or the PDF guide) and tested uploading an invoice to Invopop and sending it to a workflow.

Main Workflows

Hotelpop needs to handle three main processes:

Issuing invoices: Receptionists create new invoices through a form where they input guest billing details and add line items from a product catalog or sales list.
Correcting invoices: Receptionists correct issued invoices when needed (e.g., wrong product charges or rejected tax IDs). Since submitted invoices can’t be edited, this process creates a credit note to cancel the original invoice and issues a new one.
Onboarding issuers: Some jurisdictions require onboarding of entities before they can issue their first e-invoice through Invopop. For example, Mexican hotels must upload a digital certificate to Invopop. This process is fully automated using Invopop’s API.

Issuing Invoices

Let’s examine the process of issuing a new invoice from the perspective of a recepcionist using Hotelpop.

Upload a Silo Entry

The process begins when a receptionist fills out an invoice form in Hotelpop. At this stage, the invoice remains in “draft” status within Hotelpop, allowing the user to edit or save it without fiscal impact.

When ready to issue the invoice, the receptionist clicks Send Invoice. Hotelpop converts the invoice to GOBL and uploads it using the Create an Entry endpoint, which requires a unique UUID from Hotelpop.

This endpoint performs three functions:

Validation: Invopop verifies invoice fields, ensuring correct formatting and required fields. For example, it checks whether a Tax ID has the correct number of digits (e.g., 11 in Italy) or whether a mandatory Municipality Code is present (as required in Colombia).
Calculation: Invopop calculates tax totals, discounts, and invoice totals. If your system has already calculated these, Invopop overwrites them to align with tax authority requirements, preventing failures due to rounding differences. More on this in section “Ensuring Calculation Consistency” below.
Storage in the Silo: If validation and calculation succeed, the invoice is stored in Invopop, and the API call will return 200 status. Invopop’s storage is called the Silo, and each document, such as an invoice, is called a Silo Entry. If there’s any error in the validation and calculation step, Invopop will not store the invoice and return a 4xx status and an error message.

{
   "key": "validation",
   "message": "validation",
   "fields": {
       "data": {
           "doc": {
               "customer": {
                   "tax_id": {
                       "code": "unknown type"
                   }
               }
           }
       }
   }
}

Create a Job

The Create an Entry endpoint is synchronous, typically responding in milliseconds. Consequently, when the receptionist presses Send Invoice, Hotelpop can wait for Invopop’s feedback, for example, with a spinner on the button or a “pressed” animation on the button.

Successful Upload

After successful storage, Hotelpop sends the entry to an Invopop workflow using the Create a Job endpoint. Each workflow instance is a “job” that handles tasks like format conversion, tax authority submission, and webhook triggers.

Since this endpoint performs minimal validation and responds quickly, Hotelpop should maintain the button’s spinner/pressed status until receiving a successful response. Once confirmed, Hotelpop displays a confirmation message indicating the invoice was sent for e-invoicing and updates its internal invoice status to processing.

While most tax authorities respond within seconds, some may experience delays. For example, Italy’s tax authority can take up to two days to respond. Consider these potential delays when designing your global user experience.

Unsuccesful Upload

If Create an Entry returns an error, Hotelpop will parse the error (e.g., Tax ID of customer is incorrect) and show it to the receptionist. The invoice will stay in “draft” status in Hotelpop, so the receptionist can correct the error and click on “Send Invoice” again, going back to Step 1.

Receive Webhook

Once the job is running, Hotelpop needs a way to receive feedback from it. If successful, it may want to fetch the XML and PDF invoices for user display and update the invoice status. On the other hand, if errors occur, Hotelpop wants to notify users to correct the invoice or create a new one.

While you could poll regularly for the job until it’s finished, our recommended approach is to include webhooks in the workflow, listen to them, and use them as triggers to fetch the Silo Entry (step 4).

Fetch the Silo Entry

After receiving the webhook, fetch the Silo Entry to update invoice status, show errors, and manage output files.

The Silo Entry contains:

State: Indicates whether the workflow completed successfully.
Faults Array: Lists errors encountered, helping users correct the invoice.
Attachments: Includes generated files such as PDF and XML invoices.

Correcting Invoices

Correcting an invoice follows a similar process to issuing a new one: you upload a document to the Silo and send it to a workflow. The key difference is that this document will be a GOBL document of credit-note type. A credit note contains all fields from the original invoice plus a preceding field that references the original invoice.

To see an example of a credit note, you can visit the GOBL builder and click correct document. A modal will prompt you for the information needed to correct the invoice. Once completed, the builder will display the credit note that your system should generate and upload to Invopop.

You can also find examples of credit notes for your jurisdiction in the GOBL repository.

{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	"$regime": "DE",
	"$addons": [
		"eu-en16931-v2017",
		"de-xrechnung-v3"
	],
	"$tags": [
		"reverse-charge"
	],
	"uuid": "3aea7b56-59d8-4beb-90bd-f8f280d852a0",
	"type": "standard",
	"series": "SAMPLE",
	"code": "001",
	"issue_date": "2022-02-01",
	"currency": "EUR",
	"tax": {
		"ext": {
			"untdid-document-type": "380"
		}
	},
	"supplier": {
		"name": "Provide One GmbH",
		"tax_id": {
			"country": "DE",
			"code": "111111125"
		},
		"addresses": [
			{
				"num": "16",
				"street": "Dietmar-Hopp-Allee",
				"locality": "Walldorf",
				"code": "69190",
				"country": "DE"
			}
		],
		"emails": [
			{
				"addr": "billing@example.com"
			}
		]
	},
	"customer": {
		"name": "Provide One S.L.",
		"tax_id": {
			"country": "ES",
			"code": "B98602642"
		},
		"addresses": [
			{
				"num": "42",
				"street": "Calle Pradillo",
				"locality": "Madrid",
				"region": "Madrid",
				"code": "28002",
				"country": "ES"
			}
		],
		"emails": [
			{
				"addr": "billing@example.com"
			}
		]
	},
	"lines": [
		{
			"i": 1,
			"quantity": "20",
			"item": {
				"name": "Development services",
				"price": "90.00",
				"unit": "h"
			},
			"discounts": [
				{
					"reason": "Special discount",
					"percent": "10%",
					"amount": "180.00"
				}
			],
			"taxes": [
				{
					"cat": "VAT",
					"rate": "exempt+reverse-charge",
					"ext": {
						"untdid-tax-category": "AE"
					}
				}
			]
		}
	],
	"payment": {
		"instructions": {
			"key": "credit-transfer+sepa",
			"credit_transfer": [
				{
					"iban": "DE89370400440532013000",
					"name": "Random Bank Co."
				}
			],
			"ext": {
				"untdid-payment-means": "58"
			}
		}
	},
	"notes": [
		{
			"key": "legal",
			"src": "reverse-charge",
			"text": "Reverse Charge / Umkehr der Steuerschuld."
		}
	]
}

Onboarding Issuers

Every time Hotelpop onboards a new customer, they configure their company details (name, tax ID, address) in a configuration page in Hotelpop. When the hotel clicks on “Enable invoicing” in Hotelpop, the system creates an org.party GOBL document, uploads it to Invopop, and sends it to a registration workflow.

This process is similar to issuing an invoice: upload a document, send it to a workflow, and wait for the webhook. The specific requirements depend on the country. We recommend following the guide for your target country to learn the details of the onboarding process.

Other Considerations

Errors After Job Created

In Step 1, we discussed that most invoice errors are caught by GOBL validations and returned to you synchronously when uploading the invoice. At Invopop, we put a lot of effort into including as many validations in GOBL as possible to catch errors early.

However, some validations can only be performed by the tax authority, such as whether a business with a seemingly valid tax ID is actually registered in the country. As a result, some invoices may fail during processing. So, how can the user correct these cases?

If an invoice fails within a job, users can correct it in two ways:

Correct the same Silo Entry: Allow users to edit the invoice in your UI, PATCH the original Silo Entry, and resend it to the workflow.
Void and reissue: Void the original invoice by creating a credit note and generating a new, corrected Silo Entry.

While option 1 is simpler, some jurisdictions, especially those with fiscalization requirements (e.g., TicketBAI, VeriFactu, Portugal), do not allow invoice modifications past a certain stage. We will provide more details soon.

Calculation Consistency

As discussed in Step 1, Invopop recalculates invoice fields to ensure compliance with tax authorities. Each tax authority defines its own calculation algorithm, and we must align with their requirements. For example, some authorities require summing all line items under the same tax rate before applying the rate, while others prefer multiplying each line item by the rate before summing. These different approaches can lead to inconsistencies if not handled correctly.

Since Hotelpop calculates invoice line sums, totals, and discounts before sending them to Invopop, how can they ensure their calculations match Invopop’s?

Here are three ways to achieve this:

Match GOBL’s algorithms: Invopop’s calculation algorithm is included in the open-source GOBL library. Hotelpop can use this information to align their algorithm with GOBL’s implementation.
Use the Build GOBL Document endpoint: Invopop provides a Build GOBL Document endpoint that validates and calculates all invoice fields. Hotelpop can call this endpoint when calculating draft invoices to ensure accurate calculations.
Implement the GOBL library: Hotelpop can integrate the GOBL library directly into their system for all calculations. This approach is particularly beneficial for systems using Go internally.

Introduction

API

Guides

Introduction

Prerequisites

Main Workflows

Issuing Invoices

Correcting Invoices

Onboarding Issuers

Other Considerations

Errors After Job Created

Calculation Consistency

FAQs

Introduction

API

Guides

​Introduction

​Prerequisites

​Main Workflows

​Issuing Invoices

​Correcting Invoices

​Onboarding Issuers

​Other Considerations

​Errors After Job Created

​Calculation Consistency

​FAQs

Introduction

Prerequisites

Main Workflows

Issuing Invoices

Correcting Invoices

Onboarding Issuers

Other Considerations

Errors After Job Created

Calculation Consistency

FAQs