API Reference

Get the result

Webhooks

Webhooks are the recommended way to get the results. Please refer to webhooks documentation for more information on how to get set up.

The advantage of webhooks over polling is that we will deliver the result to you when it’s ready. For some tax authorities, it may take days for them to send us the result. Making polling a less efficient approach

Listen to a webhook

Once the transaction has been processed, the webhook will be sent to the URL set during the client onboarding process.

It can take up to 48 hours to process a transaction depending on the Tax Authority system’s availability.

Here’s an example payload you will receive from us.

Content-Type: application/json
X-Fonoa-Hmac-SHA256: SIGNATURE (docs)

{
  "event_type": "transactions.transaction_completed",
  "delivered_at": "2006-01-02T15:04:05Z",
  "resource_id": "4d697215-76c9-11ed-bfa7-660c4038a014",
  "resource_url": "https://api.fonoa.com/v1/transactions/4d697215-76c9-11ed-bfa7-660c4038a014",
  "webhook_id": "875bd24499d303cbe8afb3db1987d8aa522d63bb"
}

resource_id field matches the Fonoa generated operation_id generated on submitting a transaction.

Clients can access transaction details by sending a GET request to resource_url. If the transaction was successfully processed, a payload is returned which contains a combination of

  • Data submitted by the client
  • Any data enrichments performed by Fonoa
  • Identifiers for the data in Fonoa’s system
  • Pointers to documents that may have been created

⚠️ Generated documents

URLs to documents (see resource_url in the attachments array below) will change in the future. Clients should not rely on these URLs to be long lived [1]. They should not be passed to the client’s end users.

[1] Depends on contractual obligations. Data will be stored in cold storage for the duration by law. Data in hot storage will be subject to contractual agreements.

We recommend downloading the files immediately once a webhook is received and storing them on your system.

GET https://api.fonoa.com/v1/transactions/4d697215-76c9-11ed-bfa7-660c4038a014

200 OK
{
  "operation_id": "4d697215-76c9-11ed-bfa7-660c4038a014",
  "transaction_id": "MY_EXTERNAL_TRANSACTION_ID",
  "document_generated_at": "2019-08-24T14:15:22Z",
  "transaction_number": "00001",
  "unique_transaction_number": "2022-00001",
  "tax_authority_id_1": "50610082300310279826500300001040000000009195917993",
  "status": "SUCCESS",
  "attachments": [
    {
	"kind": "VISUAL",
      "resource_id": "4983240cf1d84f5c91e078d0a41c6001",
      "resource_url": "https://api.fonoa.com/invoicing/v1/invoices/4983240cf1d84f5c91e078d0a41c6001/pdf",
      "type": "PDF"
    }
  ],
  ... // removed full payload for brevity
}

Processing a webhook

Putting it all together, these are the high level steps to go through when you receive a webhook from Fonoa:

  1. Verify the message (see docs)
  2. Fetch the transaction result using the resource_url
  3. Check if any errors or warnings are present (see Asynchronous Errors)
  4. If errors are present, take the required steps to resolve them
  5. If no errors are present, you can store the details and download any attachments present

Polling

Clients may poll for the result in cases when webhooks are not an option. The transaction may be polled using the GET api.fonoa.com/v1/transctions/<operation_id> endpoint.

The polling procedure looks like this:

  1. Submit a transaction - POST api.fonoa.com/v1/transactions
  2. Obtain the operation_id from the API response
  3. Poll for the result using the previously obtained operation_id until the status is no longer PROCESSING - GET api.fonoa.com/v1/transctions/<operation_id>

We suggest using exponential backoff for polling the transaction status in most cases.

Processing times depend on the load of the tax authority system and may take 48 hours or more depending on the country.

A transaction may have one of the following statuses:

  • SUCCESS
  • PROCESSING
  • FAILURE

In case of failure, you can see the error reasons with the errors field. Up to date API documentation about the request/response of these endpoints can be
found here. You may see errors filled even for success transactions because some tax authorities return
warnings even when they accept a transaction as successfully reported. You can read more about warnings here

Transaction history

Here you can find up-to-date API documentation about this operation.

A single transaction may be submitted multiple times. Fonoa assigns each transaction attempt a unique operation ID. Fonoa allows you to fetch all the transaction attempts for a given transaction ID and see their statuses and respective operation IDs.

Here’s an example:

GET https://api.fonoa.com/v1/transactions/history/<transaction_id>

// 200 OK - when transaction ID exists in Fonoa system
{
	"history": [
		{
			"operation_id": "018c5da4-aba6-75df-9c41-5b6f4d394e43",
			"status": "SUCCESS"
		}
	]
}

// 404 Not Found - when transaction ID does not exist in Fonoa system
{
	"message": "transaction with ID MY_NONEXISTENT_TRANSCTION_ID not found.",
	"transaction_id": "MY_NONEXISTENT_TRANSCTION_ID"
}

💡 Transaction history is eventually consistent, meaning that you might not see the result immediately after submitting the transaction. Don’t use this endpoint for polling purposes. Instead, you should rely on webhooks for the transaction result.