E-Invoicing for Germany: API References

Introduction

Germany is set to implement staged e-invoicing for B2B transactions starting January 1, 2025, as part of the broader EU initiative for digital VAT reforms. This move aligns with the EU's "VAT in the Digital Age" proposals and introduces a significant shift in how businesses issue and process invoices. Businesses should begin preparing their systems for these changes, particularly by adopting compliant formats and ensuring readiness for real-time data reporting.

Here are the key details for Germany’s e-invoicing rollout:

Mandatory e-invoices: Starting January 1, 2025, German businesses must be able to receive e-invoices for B2B transactions and be able to issue on later stages. Affected businesses include those with a registered office or a fixed establishment in Germany. Exceptions are made for invoices under EUR 250 or travel tickets.
Compliant formats: Accepted formats include XRechnung and ZUGFeRD (as per the EU’s CEN 16931 standard). New formats such as Peppol BIS Billing have also been introduced as valid.
Transitional rules: Businesses must be capable of receiving e-invoices by January 1, 2025. Paper invoices will be allowed until 2026 for businesses below a certain turnover threshold (EUR 800,000). By 2028, all businesses must fully transitioned to e-invoicing.
System readiness: Businesses need to review their ERP and invoicing systems for compatibility with e-invoicing formats and ensure they can handle electronic invoicing and receipt. This might involve software updates or additional tools.
Compliance enforcement: The final guidelines include provisions for ensuring authenticity and integrity of invoices, with requirements for qualified electronic signatures or internal control systems

POST/de/einvoice/onboard

Onboard to Peppol

This endpoint allows you to onboard into the Peppol Network using Flick as your Access Point. Peppol (Pan-European Public Procurement Online) facilitates the standardized exchange of e-invoices and business documents, ensuring compliance and interoperability between participants.

Request Body

Name
registered_name
Type
string: mandatory (limit: 300 chars)
Description
Registred Name of Supplier’s business
Name
identifiers
Type
array: mandatory
Description
For all VAT-registered businesses in Germany, the VAT Identification Number (DE:VAT) is mandatory. Additionally, the Local Warehouse Identification Number (DE:LWID) is required for businesses involved in warehousing or storage operations.
Name
DE:LWID
Type
string: mandatory if applicable
Description
Name
DE:VAT
Type
string: mandatory if applicable
Description
Name
city
Type
string: optional (limit: 50 chars)
Description
Registered City of the supplier.
Name
street
Type
string: optional (limit: 150 chars)
Description
Street details of the supplier. If not available, provide 'NA'.
Name
county
Type
string: optional (limit: 150 chars)
Description
County details of the supplier. If not available, provide 'NA'.
Name
country
Type
string: ISO 3166-1 alpha-2 country code
Description
Country of the supplier. DE in case of Germany.
Name
contact_number
Type
string: optional (limit: 20 chars)
Description
The telephone number of the Supplier (e.g., office, mobile, fax).

Sample Request

POST

/de/einvoice/onboard

curl 
  --url https://sandbox-api.flick.network/de/einvoice/onboard \
  --header 'x-flick-auth-key: {token}' \
  --header 'Content-Type: application/json' \
  --data '
  {
    "registered_name": "TestCompany GmbH",
    "identifiers": [
      {
        "scheme": "DE:VAT",
        "id": "DE123456789"
      },
      {
        "scheme": "DE:LWID",
        "id": "LWID987654321"
      }
    ],
    "city": "Berlin",
    "street": "Musterstraße 123",
    "county": "Musterkreis",
    "country": "DE",
    "contact_number": "+49-30-12345678"
  }'

Sample Response

200

Success

{
  "status": "success",
  "message": "Successfully Onboarded to Peppol",
  "data": {
    "supplier_uuid": "f4b173a9-9f0f-4850-b682-762290885fee"
  }
}

POST/de/einvoice/generate/invoice

Submit an Invoice

To Generate a new E-Invoice Document & share it through Peppol, this endpoint can be used along with the Supplier UUID to which it belongs to. Specify transport_mode for proper delivery of the document.

Request Body

Name
ID
Type
string: mandatory (limit: 50 chars)
Description
Unique Invoice Reference Number. This should be made in sequence.

Name

DocumentType

Type

string: mandatory (limit: 50 chars)

Description

Specifies the type of document. Refer to the official Peppol documentation for details:

Document Type	Code
Request for Payment	71
Debit Note (Goods/Services)	80
Metered Services Invoice	82
Debit Note (Financial Adjustments)	84
Tax Notification	102
Final Payment Request	218
Payment Request for Completed Units	219
Commercial Invoice	380
Debit Note	383
Prepayment Invoice	386
Tax Invoice	388
Factored Invoice	393
Consignment Invoice	395
Freight Invoice	780
Consular Invoice	870
Partial Construction Invoice	875
Partial Final Construction Invoice	876
Final Construction Invoice	877
Credit Note (Goods/Services)	381
Credit Note (Financial Adjustments)	383
Credit Note	381
Factored Credit Note	396
Forwarder's Credit Note	532

Name
IssueDate
Type
date: mandatory, schema: YYYY-MM-DD
Description
Date on which the invoice was issued.
Name
DocumentCurrencyCode
Type
string: mandatory (3 chars)
Description
Currency in which the invoice was issued. Default value: EUR.
Name
CustomerParty
Type
object: mandatory
Description
Information about the customer to whom the invoice is issued.
Name
RegisteredName
Type
string: mandatory (limit: 300 chars)
Description
Name of the Customer/Receiving company.
Name
address
Type
object: mandatory
Description
Address details of the customer.
Name
Street
Type
string: mandatory (limit: 150 chars)
Description
Street details of the customer. If not available, provide NA.
Name
ZipCode
Type
string: mandatory (limit: 10 chars)
Description
ZIP code of the customer's address.
Name
City
Type
string: mandatory (limit: 50 chars)
Description
City of the customer's address.
Name
Country
Type
string: ISO 3166-1 alpha-2 country code
Description
Country of the customer. Use DE for Germany.
Name
Identifiers
Type
array: mandatory
Description
List of public identifiers for the customer.
Name
Scheme
Type
string: mandatory
Description
Scheme type of the identifier, e.g., DE:LWID.
Name
ID
Type
string: mandatory (limit: 50 chars)
Description
The identifier value for the given scheme.
Name
InvoiceLines
Type
array: mandatory
Description
Details of the line items in the invoice.
Name
Description
Type
string: mandatory (limit: 300 chars)
Description
Description of the purchased goods or services.
Name
PriceAmount
Type
number: mandatory
Description
Amount excluding VAT for the line item.
Name
TaxType
Type
object: mandatory
Description
Tax details for the line item.
Name
TaxRate
Type
number: mandatory
Description
The VAT percentage applicable to the line item.
Name
TaxType
Type
enum: mandatory
Description
Tax category. For example, standard or reduced.
Name
TaxCountry
Type
string: ISO 3166-1 alpha-2 country code
Description
Country for which the tax is applied. Use DE for Germany.
Name
TotalIncludingVat
Type
number: mandatory
Description
Total amount of the invoice, including VAT.

Sample Request

POST

/de/einvoice/generate/invoice

curl --url https://sandbox-api.flick.network/de/einvoice/generate/invoice \
  --header 'x-flick-auth-key: {token}' \
  --header 'supplier_uuid: {supplier_uuid}' \
  --header 'transport_mode: peppol' \
  --header 'Content-Type: application/json' \
  --data '
    {
      "ID": "INV-11",
      "DocumentType": "380",
      "IssueDate": "2024-12-01",
      "DocumentCurrencyCode": "EUR",
      "CustomerParty": {
        "RegisteredName": "Test Inc.",
        "address": {
          "Street": "Street Name 987",
          "ZipCode": "9999AA",
          "City": "City Test",
          "Country": "DE"
        },
        "Identifiers": [
          {
            "Scheme": "DE:LWID",
            "ID": "11111111-STO-10"
          }
        ]
      },
      "InvoiceLines": [
        {
          "Description": "Test Item",
          "InvoicedQuantity": 2,
          "PriceAmount": 100,
          "TaxType": {
            "TaxRate": 19,
            "TaxType": "standard",
            "TaxCountry": "DE"
          }
        }
      ],
      "TotalIncludingVat": 238.00
    }'

Sample Response

200

Success

{
  "status": "success",
  "data": {
    "DocumentID": "52d08f40-a2a0-450b-857f-2e1dd865064c",
    "DeliveryStatus": "Scheduled"
  }
}

GET/de/einvoice/get-document/{uuid}

Get Document Details

This API endpoint allows users to get details of a document by querying with UUID.

GET Request Parameters

Name
uuid
Type
string
Description
UUID of the document

Sample Request

POST

/de/einvoice/get-document/{uuid}

curl 
  --url https://sandbox-api.flick.network/de/einvoice/get-document/{uuid} \

  --header 'x-flick-auth-key: {token}' \
  --header 'supplier_uuid: {supplier_uuid}'

Sample Response

200

Success

{
  "uuid": "52d08f40-a2a0-450b-857f-2e1dd865064c",
  "ID": "INV-11",
  "DocumentType": "380",
  "IssueDate": "2024-12-01",
  "DocumentCurrencyCode": "EUR",
  "CustomerParty": {
    "RegisteredName": "Test Inc.",
    "address": {
      "Street": "Street Name 987",
      "ZipCode": "9999AA",
      "City": "City Test",
      "Country": "DE"
    },
    "Identifiers": [
      {
        "Scheme": "DE:LWID",
        "ID": "11111111-STO-10"
      }
    ]
  },
  "InvoiceLines": [
    {
      "Description": "Test Item",
      "InvoicedQuantity": 2,
      "PriceAmount": 100,
      "TaxType": {
        "TaxRate": 19,
        "TaxType": "standard",
        "TaxCountry": "DE"
      }
    }
  ],
  "TotalIncludingVat": 238.00
}

GET/de/einvoice/delivery-status/{uuid}

Get Delivery Status

This API endpoint allows users to query the status of delivery of a document through Peppol.

GET Request Parameters

Name
uuid
Type
string
Description
UUID of the document

Sample Request

POST

/de/einvoice/delivery-status/{uuid}

curl 
  --url https://sandbox-api.flick.network/de/einvoice/delivery-status/{uuid} \

  --header 'x-flick-auth-key: {token}' \
  --header 'supplier_uuid: {supplier_uuid}'

Sample Response

200

Success

{
  "DocumentID": "52d08f40-a2a0-450b-857f-2e1dd865064c",
  "DeliveryStatus": "Delivered"
}

WEBHOOKEVENT LISTEN TO BE LISTENED

Received Document

You can listen to this webhook to get new documents issued against the supplier.

Request Body

Name
Event
Type
string
Description
Type of Event that happend.
Name
EventType
Type
string
Description
Type of Event Type that happend.
Name
EventGroup
Type
string
Description
Type of Event group that it belongs.
Name
uuid
Type
string
Description
UUID of the document
Name
DocumentId
Type
string
Description
Internal Document ID
Name
Status
Type
string
Description
Current status of the document

Sample Request

POST

{
  "Event": "DocumentReceived",
  "EventType": "PeppolReceived",
  "EventGroup": "Invoice",
  "uuid": "52d08f40-a2a0-450b-857f-2e1dd865064c",
  "DocumentId": "INV-123",
  "Status": "Delivered"
}