Asynchrounous API

The Onboarding and Reporting endpoints are asynchronous, due to the nature of Fonoa’s interactions with 3rd party systems like tax authorities. Though most requests only take a few seconds, some may take longer.
Our API currently supports polling. Webhook support is on the roadmap.

Jobs

When onboarding an entity or reporting a transaction, a job is created. This job represents the status of the request in our system. If the execution fails for whatever reason, the job will fail and a list of errors will be returned explaining how to address the issue. If it is successful, it will indicate the location of the onboarded entity or transaction where the full details can be fetched.

Polling

When polling a job for status, we recommend separating requests by a minimum of 1 second and retrying with exponential backoff, as some requests may be slow, e.g. if a tax authority API is not responding.

Errors

When a request fails, a list of errors is provided. The error object contains a human-readable code, a type outlining the source of the error (e.g. Fonoa validation error, tax authority error), and a message explaining how to address the issue. When possible the field position is provided, giving the exact location of the erroneous data point.

“errors”: [ 
   {
     "code": "tax_amount_incorrect",
     "type": "validation",
     "message": "The tax amount provided is above the 2 cents tolerance threshold. Expected amount: $1.42",
     "field": "items[4].tax_breakdown[0].amount"
   }
]