API Reference

Onboarding

Onboarding the various transaction participants

Every reported transaction will have up to two parties involved, depending on whether it is B2B / B2C and whether you are issuing receipts or invoices in B2C scenarios. Transaction participants are the supplier (your company or partner company, depending on the business model) and the customer (a private person or another business entity).

Here you can find up to date API documentation.

Onboard a supplier.

This endpoint is used for onboarding your own company and the underlying sellers in case you are running a marketplace.


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
}

Sequence

  1. Send the POST HTTP request to: https://api.fonoa.com/onboarding/v2/companies

    If the initial check is good (subscription, etc...), you will get 202 accepted status along with a link where you will get our actual response when the process is done. Here you will also receive a “Jobs id” (9bf457f955fc451293db323e3558019d) that you will use in step 2.

  2. Check out the status of an onboarded company by sending the GET HTTP request to: https://api.fonoa.com/onboarding/v2/jobs/{id}

  3. Success - if everything was done correctly, you now have your company or supplier created with Fonoa! You can reference the entity using the “id” (9bf457f955fc451293db323e3558019d) you obtain upon successful onboarding.

To test the integration in the Demo environment in case you don’t yet have your tax authority credentials, reach out to our team and we will set up a supplier for you for testing purposes using our Demo credentials.

Get the status of the onboarded party

Assuming the supplier was successfully onboarded; you could check the status of your onboarded suppliers and all relevant details about it. You can do this via the following URL: https://api.fonoa.com/onboarding/v2/jobs/{id}, using the id you obtain upon sending the onboarding request.

There, you will see the job status location, which will walk you through the granular details of the onboarded party.

The transaction details URL has the following structure: https://api.fonoa.com/onboarding/v2/companies/{id}

Example for the following supplier onboarding id: ab52e24c64364fc7ae0fa098c242c4d9

{
    "data": {
        "address": {
            "address_line_1": "Karlowy Tavidze",
            "city": "Budapest",
            "country_code": "hu",
            "postal_code": "5600"
        },
        "company_number": "69061864-1-33",
        "created_at": "2023-02-18T15:11:34.880572303Z",
        "id": "885e02f3af9e11edaae83a4f470e7791",
        "legal_name": "Supplier ABC",
        "meta": {
            "country_code": "hu",
            "language_code": "hu"
        },
        "tax_credentials": {
            "username": "eridbqzc4aazomg"
        },
        "tax_information": {
            "regime": "VAT",
            "tax_number": "69061864-1-33"
        }
    },
    "status": "success"
}

Searching / filtering of onboarded entities

You can search for onboarded entities and individuals via either Fonoa ID or the external ID that you associate with each onboarding.

The endpoints are both GET and will have the following format: https://api.fonoa.com/onboarding/v2/companies/{id}

If you are searching by external_id then it is also required to add ?external-id=true to the URL after the ID.


If you want to search by tax_number, you would put a request as follows: https://api.fonoa.com/onboarding/v2/companies?tax-number={tax_number}

Updating or deleting onboarded entities

To update any of the data points after the initial onboarding process was completed, you can use the following process:

  1. Send the PATCH HTTP request to: https://api.fonoa.com/onboarding/v2/companies/{id}, where ID is the ID of the onboarded company you want to update
  2. The request body should only contain the data point you want to update

Request example - updating the name of the business customer, from “Supplier ABC” to “ACME”

{
    "legal_name": "ACME"
}

To delete any of the companies after the initial onboarding process was completed, you can use the following process:

  1. Send the DELETE HTTP request to: https://api.fonoa.com/onboarding/v2/companies/{id}, where ID is the ID of the onboarded company you want to delete
  2. The request body should be empty

Request example:

{
}

Response example:

{
    "status": "success",
    "data": null,
    "message": "Company has been deleted successfully.",
    "errors": null
}

Adding Customer Data

Every reported transaction will have up to two parties involved, depending on whether it is B2B / B2C and whether you are issuing receipts or invoices in B2C scenarios.

Customer data is added directly in the e-invoicing API call, without the need to onboard them.