E-Invoicing for Finland: API References

Introduction

Finland has long been a leader in digital invoicing, implementing regulations that require the use of e-invoices for both public and private sector transactions. As part of the EU's digital transformation agenda, Finland mandates that businesses comply with the Finvoice and TEAPPSXML formats, helping to automate invoicing processes, reduce errors, and improve tax reporting accuracy.

Standard Formats: Finland uses Finvoice and TEAPPSXML formats, which are fully compliant with EU e-invoicing standards.
Mandatory Compliance: Since 2020, businesses are required to accept e-invoices in these formats when requested by other businesses, ensuring seamless integration with Finnish tax and financial systems.
PEPPOL Integration: Finland is part of the PEPPOL network, which allows businesses to exchange invoices across EU borders with ease.
Tax Reporting: The e-invoicing system is tightly integrated with VAT reporting, improving the efficiency of tax compliance and reducing the risk of fraud.

POST/fi/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 Finland, the VAT Identification Number (FI:OVT) is mandatory.
Name
FI:OVT
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 .
Name
contact_number
Type
string: optional (limit: 20 chars)
Description
The telephone number of the Supplier (e.g., office, mobile, fax).

Sample Request

POST

/fi/einvoice/onboard

curl 
  --url https://sandbox-api.flick.network/fi/einvoice/onboard \
  --header 'x-flick-auth-key: {token}' \
  --header 'Content-Type: application/json' \
  --data '
  {
    "registered_name": "TestCompany",
    "identifiers": [
      {
        "scheme": "FI:OVT",
        "id": "VAT12345"
      }
    ],
    "city": "Helsinki",
    "street": "Esimerkkikatu 12",
    "county": "Uusimaa",
    "country": "FI",
    "contact_number": "+358-9-1234567"
  }'

Sample Response

200

Success

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

POST/fi/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. For example, Invoice, CreditNote or DebitNote.
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 FI for Finland.
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., FI:OVT.
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 FI for Finland.
Name
TotalIncludingVat
Type
number: mandatory
Description
Total amount of the invoice, including VAT.

Sample Request

POST

/fi/einvoice/generate/invoice

curl --url https://sandbox-api.flick.network/fi/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": "Invoice",
      "IssueDate": "2024-12-01",
      "DocumentCurrencyCode": "EUR",
      "CustomerParty": {
        "RegisteredName": "Test Inc.",
        "address": {
          "Street": "Street Name 987",
          "ZipCode": "9999AA",
          "City": "City Test",
          "Country": "FI"
        },
        "Identifiers": [
          {
            "Scheme": "FI:OVT",
            "ID": "11111111-STO-10"
          }
        ]
      },
      "InvoiceLines": [
        {
          "Description": "Test Item",
          "InvoicedQuantity": 2,
          "PriceAmount": 100,
          "TaxType": {
            "TaxRate": 19,
            "TaxType": "standard",
            "TaxCountry": "FI"
          }
        }
      ],
      "TotalIncludingVat": 238.00
    }'

Sample Response

200

Success

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

GET/fi/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

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

curl 
  --url https://sandbox-api.flick.network/fi/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": "Invoice",
  "IssueDate": "2024-12-01",
  "DocumentCurrencyCode": "EUR",
  "CustomerParty": {
    "RegisteredName": "Test Inc.",
    "address": {
      "Street": "Street Name 987",
      "ZipCode": "9999AA",
      "City": "City Test",
      "Country": "FI"
    },
    "Identifiers": [
      {
        "Scheme": "FI:OVT",
        "ID": "11111111-STO-10"
      }
    ]
  },
  "InvoiceLines": [
    {
      "Description": "Test Item",
      "InvoicedQuantity": 2,
      "PriceAmount": 100,
      "TaxType": {
        "TaxRate": 19,
        "TaxType": "standard",
        "TaxCountry": "FI"
      }
    }
  ],
  "TotalIncludingVat": 238.00
}

GET/fi/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

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

curl 
  --url https://sandbox-api.flick.network/fi/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"
}