The e-Invoicing API is used in 3 steps:
- Onboard party (optional if the party is already onboarded)
- Submit a transaction
- Listen to webhook response (alternatively poll until the result is ready - not recommended)
Prerequisites
- Your account is set up with Fonoa and an API key was provided. Check here how to setup the key on API requests.
- Your product configuration must be set up by a Fonoa solutions engineer (logo, colours, a list of countries that the customer will use, webhook URL, …)
1. Onboard a party
Here you can find the complete onboard documentation.
This step is used for onboarding your own company and the underlying sellers in case you are running a marketplace. If the supplier is already onboarded it's not necessary to onboard them again.
Make an API call to POST api.fonoa.com/onboarding/v2/companies - there, you need to enter the information required to onboard a supplier.
Below is an example JSON body for onboarding a company using the /companies endpoint:
{
"meta": {
"country_code": "hu",
"language_code": "hu",
"external_id": "Account0001HU"
},
"legal_name": "Supplier ABC",
"company_number": "69061864-2-99",
"address": {
"country_code": "hu",
"city": "Budapest",
"postal_code": "5600",
"address_line_1": "Karlowy Tavidze"
},
"tax_information": {
"tax_number": "69061864-2-99",
"regime": "VAT"
},
"tax_credentials":
{
"certificate_base64": "", // Signature Key from NAV
"certificate_password": "", // Replacement (Exchange) Key from NAV
"username": "USERNAME",
"password": "PASSWORD"
}
}
Example of the response
"status": "success",
"data": {
"job_id": "9bf457f955fc451293db323e3558019d",
"job_status_location": "https://api.fonoa.com/onboarding/v2/jobs/9bf457f955fc451293db323e3558019d"
},
"message": "Create company job successfully queued for execution",
"errors": null
}
Get the supplier Identification
Make an API call to GET https://api.fonoa.com/onboarding/v2/jobs/{job_id} - where the job_id is part of the response of the previous request.
Below is an example of the body response when the party is onboarded with success.
{
"status": "success",
"data": {
"id": "8d4a5c0303234432ab11a3beecdbb4c3",
"location": "https://api.fonoa.com/onboarding/v2/companies/8d4a5c0303234432ab11a3beecdbb4c3"
},
"message": null,
"errors": null
}
2. Submit a transaction
Here you can find the complete submit transaction documentation.
To submit a transaction send HTTP POST api.fonoa.com/v1/transactions with the following body containing the details of the transactions and the ID of the party onboarded.
The placeholder suplier_idmust be replaced with the value of the id received in the previous request.
{
"country_code": "PT",
"language_code": "PT",
"currency_code": "EUR",
"transaction_date": "2023-06-15T01:00:00+00:00",
"transaction_id": "ref111",
"operation_regime": "GENERAL",
"type": "FULL",
"direction": "SENT",
"items": [
{
"number": 1,
"name": "Service ABC",
"description": "Service ABC",
"quantity": 1.0,
"unit": "pcs",
"code": "1",
"ean": "1",
"unit_price": 5000.245,
"net_price": 5000.245,
"type": "GOODS",
"tax_breakdown": [
{
"rate": 23,
"amount": 1150.05635,
"regime": "IVA",
"type": "PT"
}
]
}
],
"supplier": {
"id": "{supplier_id}"
},
"customer": {
"legal_name": "Customer Legal Name",
"address": {
"country_code": "PT",
"address_line_1": "Lisboa Street 55A",
"postal_code": "1700-031",
"city": "Lisboa"
},
"tax_information": {
"tax_number": "123456789"
},
"type": "INDIVIDUAL"
},
"payments": [
{
"type": "CREDIT",
"amount": 6150.30135
}
],
"total_amount": 6150.30135,
"total_net_amount": 5000.245,
"total_tax_amount": 1150.05635
}
If there are no validation errors clients shall receive 202 Accepted with the following response body:
{
"operation_id": "4d697215-76c9-11ed-bfa7-660c4038a014"
}
3. Get the result
There are two ways to get the results of an operation
- Get a notification via webhook (recommended).
- Polling the result only applicable when setting up a webhook is not available.
Here you can find the complete documentation about these two options.
For this quickstart page we will use the request used for polling just to illustrate the change on state of the transaction.
The transaction may be polled using the GET https://api.fonoa.com/v1/transctions/{operation_id} endpoint - where the operation_id is the id received in the response of the Submit transaction step.
Here you can find the complete documentation about the get transaction endpoint.
Below and example of response of this API:
{
"attachments": [
{
"expiration_date": "2024-06-21T07:17:43.808448872Z",
"kind": "VISUAL",
"resource_id": "01903482-1212-7d01-99c3-9ce15a41e5ab",
"resource_url": "<https_url_with_expiration_without_auth_where_you_can_get_your_resource_from>",
"type": "PDF"
}
],
"business_model": "B2C",
"country_code": "PT",
"currency_code": "EUR",
"customer": {
"address": {
"address_line_1": "Lisboa Street 55A",
"city": "Lisboa",
"country_code": "PT",
"postal_code": "1700-031"
},
"legal_name": "Customer Legal Name",
"tax_information": {
"tax_number": "123456789"
},
"type": "INDIVIDUAL"
},
"direction": "SENT",
"document_generated_at": "2024-06-20T07:17:40.7719296Z",
"items": [
{
"code": "1",
"description": "Service ABC",
"ean": "1",
"name": "Service ABC",
"number": 1,
"quantity": 1,
"tax_breakdown": [
{
"rate": 23,
"regime": "IVA",
"type": "PT",
"amount": 1150.06
}
],
"type": "GOODS",
"unit": "pcs",
"unit_price": 5000.24,
"net_price": 5000.24
}
],
"language_code": "PT",
"operation_id": "0e5842c2-3535-11ee-8fa3-86f6c0599b7f",
"operation_regime": "GENERAL",
"payments": [
{
"amount": 6150.30,
"type": "CREDIT"
}
],
"reported_at": "2024-06-20T07:17:42.040754399Z",
"status": "SUCCESS",
"supplier": {
"id": "<your_supplier_id>"
},
"tax_authority_id_1": "abv123",
"tax_authority_id_2": "ABC-1111",
"total_amount": 6150.30,
"total_net_amount": 5000.24,
"total_tax_amount": 1150.06,
"transaction_date": "2023-06-15T01:00:00Z",
"transaction_id": "214121221",
"transaction_number": "FT XYZ/1111",
"type": "FULL",
"unique_transaction_number": "PT1234567895-2023-FT XYZ/1111"
}