Create a ZUGFeRD / Factur-X e-invoice in Go

What you need

• An API key. Create one in the app under API keys and export it as FORMFEED_API_KEY. A test key (ff_test_…) is right for trying things out. See the quick start.
• Go. You need Go 1.21 or newer; the program uses the standard library only.
• The template. e-rechnung from the e-invoice example: copy it into your workspace from the example’s page, or push the folder with the CLI (formfeed templates push --publish). Any invoice template works the same way once its data has an _invoice block.
• The data. The example’s data.json next to the program: one _invoice block with seller, buyer, lines, the VAT breakdown and the totals, in the terms of the European standard EN 16931.
• A plan with e-invoices. Live e-invoices need the Starter plan or above. With a test key (ff_test_…) every plan makes test e-invoices with a test mark on the page, the Free plan up to 20 a day.

The program

The program reads data.json, posts it with the template’s name and post.einvoice, waits for the result when the API answers 202, stops with the API’s message when something is wrong, and saves the e-invoice.

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
	"time"
)

const endpoint = "https://api-eu.formfeed.dev/v1/renders"

// a render or a problem document: both are JSON objects, so one struct decodes either
type render struct {
	ID          string  `json:"id"`
	Status      string  `json:"status"`
	DownloadURL string  `json:"download_url"`
	PageCount   int     `json:"page_count"`
	Units       float64 `json:"units"`
	Title       string  `json:"title"`
	Detail      string  `json:"detail"`
}

// send makes one call with the key and decodes the answer
func send(method, url string, body []byte) (int, render) {
	request, _ := http.NewRequest(method, url, bytes.NewReader(body))
	request.Header.Set("Authorization", "Bearer "+os.Getenv("FORMFEED_API_KEY"))
	request.Header.Set("Content-Type", "application/json")
	response, err := http.DefaultClient.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()
	var answer render
	json.NewDecoder(response.Body).Decode(&answer)
	return response.StatusCode, answer
}

func main() {
	data, err := os.ReadFile("data.json")
	if err != nil {
		panic(err)
	}
	body, _ := json.Marshal(map[string]any{
		"template": "e-rechnung",
		"data":     json.RawMessage(data),
		"post": map[string]any{
			"einvoice": map[string]any{"profile": "en16931"},
		},
	})

	status, result := send("POST", endpoint, body)
	// not done within 60 seconds: the answer is 202 and the render goes on in the background;
	// its result answers the same way until the render has finished
	for status == http.StatusAccepted {
		time.Sleep(2 * time.Second)
		status, result = send("GET", endpoint+"/"+result.ID+"/result", nil)
	}
	// every error is a problem document (RFC 9457) with a title and a detail
	if status >= 400 {
		fmt.Fprintf(os.Stderr, "%s: %s\n", result.Title, result.Detail)
		os.Exit(1)
	}

	file, err := http.Get(result.DownloadURL)
	if err != nil {
		panic(err)
	}
	defer file.Body.Close()
	out, _ := os.Create("e-invoice.pdf")
	defer out.Close()
	io.Copy(out, file.Body)
	fmt.Printf("%s %d page(s), %v unit(s)\n", result.ID, result.PageCount, result.Units)
}

Run it

It prints the render’s id, the page count and the units it cost (on a live key one more than the same PDF without the XML), and e-invoice.pdf lies next to the program. A PDF viewer shows the invoice, and its attachments show the factur-x.xml inside. With a test key the render is not metered, and every test e-invoice carries a test mark, on every plan.

export FORMFEED_API_KEY=ff_test_...
go run main.go

What is particular about Go

• json.RawMessage. The sample data goes into the body as it is on disk, without being decoded into Go types first, so the program works for any template.
• One struct for both answers. A render and a problem document are both JSON objects, so a single struct with title and detail beside the render fields decodes either.
• Timeouts. http.DefaultClient has none. In a service, give the client a Timeout a little above 60 seconds: a synchronous render answers when the file is done, or after 60 seconds with 202 while it goes on in the background.

What makes the PDF an e-invoice

• post.einvoice. turns the PDF into a PDF/A-3 that carries the invoice as factur-x.xml. The example template declares the same in its settings.json, so for this template the line is optional; for your own invoice template it is the one switch.
• The _invoice block. Seller, buyer, lines, VAT breakdown and totals, named as in the standard; units and VAT categories are codes (HUR, S). The template prints the page from the same block, so the page and the XML cannot say different things.
• The check. Before the file is delivered, the XML is held to the rules of EN 16931 and the PDF to PDF/A-3b. The report is in the render’s einvoice.validation, and a value the page does not show is listed in einvoice.display.missing.
• ZUGFeRD or Factur-X. One specification under two names, and the same file. flavour decides only which name and release the render reports: ZUGFeRD 2.5 or Factur-X 1.09.

When the data is wrong

A block that breaks a rule fails the request with 422 einvoice_data_invalid before anything is rendered or counted. The problem lists every finding with its place in the data and the rule it breaks (BR-CO-15, …), and the program prints its title and detail. A file that fails the check is never delivered, and never replaced by a plain PDF.

What stays with you

Formfeed creates and checks the file. Sending it to your customer, archiving it and the VAT treatment of the invoice stay with you. When an e-invoice is required, with the official sources, is on the e-invoicing page; the fields and the rules are in the e-invoice docs.

When the API says no

• One shape for every error. Errors are problem documents (RFC 9457) with type, title, status, detail, a stable code and the request_id to quote to support; the type URL leads to a page about that error. The list is in the error reference.
• The usual ones. 401 unauthorized for a missing or revoked key, 404 template_not_found for a wrong template name, 422 template_runtime_error when the template fails on the data, 429 rate_limited above the plan’s requests per second, 402 quota_exceeded when the Free plan’s units are used up (a paid plan bills extra units up to its hard cap).
• Retry safely. Send an Idempotency-Key header with the POST, and repeat the request with the same key when you do not know whether the first attempt arrived: for 24 hours the key returns the first answer instead of rendering and billing again. The answer is stored once the first attempt has been answered, so do not retry while it may still run; and problems below 500 are stored too, so a corrected request needs a new key.

The job around this program

This guide is one program. What the job needs around it, from the template to the limits and the price, is on the page Invoice PDF API.

More Go guides

• Generate a PDF invoice from JSON in Go
• Convert HTML to PDF in Go
• Generate Open Graph images in Go
• Generate PDFs from a CSV in Go
• Merge PDFs and add a password in Go
• Async PDF rendering with a verified webhook in Go

FAQ

Which profile should I choose?

en16931, the default, carries every field of the European standard; basic is the smallest profile that is an invoice on its own. Any other profile is answered with einvoice_profile_unsupported.

Does Formfeed create XRechnung?

No. Formfeed writes ZUGFeRD / Factur-X: the XML inside a PDF/A-3. XRechnung and UBL are not available.

What does an e-invoice cost?

One unit on top of its render, so a one-page e-invoice costs two units. Live e-invoices need the Starter plan or above; on the Free plan, test renders make up to 20 a day. See pricing.

Can I have the XML as a file of its own?

xml: "both" in post.einvoice stores the XML beside the PDF as well, and the render links it as einvoice.xml_url. Inside the PDF it is there either way.

ZUGFeRD e-invoice in other languages

• Node.js (TypeScript)
• Python
• PHP
• C# (.NET)
• Java
• Ruby
• curl