Bruno Quickstart
To test our API without writing a single line of code, you can use Bruno.
Bruno is an open-source API client that describes all the methods exposed by an API, making it possible for the user to modify the different request parameters and perform actual calls toward the API, obtaining the HTTP response as a result. Unlike other clients, Bruno is offline-first: collections are stored as plain text files (.bru) directly on your filesystem, so they can be versioned in your Git repository along with your code.
0️⃣ Install Bruno
To use our collection, we suggest downloading Bruno on your device; it is available for Windows, Mac, and Linux.
No sign-up is required: Bruno works entirely on your machine, and the Free Plan is more than enough to use our collection 😉
1️⃣ Import the Collection
We don't publish a native Bruno collection, but Bruno can import our Postman Collection directly and convert it for you.
The Collection is generated automatically using our OpenAPI Specification, and can be downloaded from our GitHub Repository at the postman/fic-api.json path; it is updated every time a new version of the Specification is released, so you can just redownload it to keep in sync.
Once you have downloaded the JSON file of the collection, you can import it following this procedure:
- Click the + button in the top-left corner of Bruno and select Import Collection.
- Choose Postman Collection and select the fic-api.json file you downloaded.
- Choose the folder on your filesystem where Bruno should store the converted collection.
Now you're almost ready to interact with our API!
If you prefer, you can instead use our OpenAPI Specification directly, importing it with the OpenAPI Specification option (procedure). In this case we suggest using the openapi-enriched.yaml file, since it is flattened (e.g. all the models are contained in a single file): if you use the plain openapi.yaml you also need to download the files in the models folder, otherwise, the import will fail.
Bruno can also import a specification from a URL, so you can just paste the following one to always get the latest version:
https://raw.githubusercontent.com/fattureincloud/openapi-fattureincloud/master/openapi-enriched.yaml
2️⃣ Authorization
Next, to be able to interact with our API you need to be authorized: see the Authentication page for further info.
You have two main options to retrieve a valid token:
✋ Manual Authentication
This isn't only for the Manual tokens! If you obtained a token using one of the other methods outside of Bruno (for example in your code) you can decide to test it using Bruno! Just use it as a manual token and follow the steps below, but remember OAuth 2.0 tokens expire!
Since Bruno is mainly used to test and discover our API behavior, this is a great use case for Manual Authentication. Just generate a new token with the required scopes and insert it into Bruno!
Once you have retrieved the token, you have two options to use a manual token:
-
In the Auth tab, you can select Bearer Token in the Auth Type dropdown and then paste the token in the Token field. Bruno will add the
Bearerprefix for you, so you must not add it. You can do this on a single request, or once and for all in the Collection Settings > Auth tab: in the latter case, remember to select Inherit in the Auth Type dropdown of every request that should use it. -
If you want to insert your header manually, you can leave None in the Auth tab and add the Authorization header in the Headers tab. The value of the token must be
Bearer ACCESS_TOKENwhere ACCESS_TOKEN must be replaced with the token you obtained earlier. This method is a little more complicated than the previous one, but you could use it to store and test different tokens by selecting the one you want to use and deselecting the other ones.
Instead of pasting the token in every request, you can save it in an environment variable (for example access_token) and then reference it as {{access_token}} in the Token field or in the Authorization header. This way you can switch between different tokens by just switching environments.
🔐 OAuth 2.0 Authorization Code
If you obtained a token using one of the other methods outside of Bruno (for example in your code) just use it as a manual token and follow the points above, but remember OAuth 2.0 tokens expire!
If you want to test the OAuth 2.0 flow without implementing it beforehand, you can use Bruno to retrieve your Access Token automatically from its interface.
To set Bruno up, open the Collection Settings, select the Auth tab, choose OAuth 2.0 as Auth Type and Authorization Code as Grant Type, then fill out the form.
The parameters are:
| Field | Value |
|---|---|
| Authorization URL | https://api-v2.fattureincloud.it/oauth/authorize |
| Access Token URL | https://api-v2.fattureincloud.it/oauth/token |
| Add Credentials to | Select "Request Body" |
| Add token to | Select "Headers" |
| Callback URL | See below for further info |
All the other parameters can be found on the OAuth 2.0 Authorization Code Flow page.
If you want, you can also enable the Use PKCE option: our authorization endpoint supports the Proof Key for Code Exchange extension, and it is a recommended security best practice.
The Callback URL parameter must contain your App's Redirect URL, the one you configured on your Fatture in Cloud App page. Unlike other API clients, Bruno doesn't provide a hosted callback URL of its own: it intercepts the redirect performed by our authorization server, so the URL doesn't need to be reachable, it just needs to match.
By default, the authorization page is opened inside Bruno's built-in browser; if you prefer to perform this step in your usual browser (for example because you're already logged in to Fatture in Cloud there), you can enable the System Browser option in the Callback URL section.
In either case, Bruno's Callback URL and the Fatture in Cloud App's Redirect URL must be exactly the same!!! Otherwise, the redirect will fail and you won't be able to perform the authorization flow.
Once you've set up all the variables, you can click the Get Access Token button to be redirected to the Fatture in Cloud page and perform the flow. Bruno will store the obtained token and use it for the requests that inherit the collection authorization.
Additionally, you can enable the Auto-fetch and Auto-refresh options to let Bruno retrieve a new token when it is missing, and refresh it using the Refresh Token step when the old one expires.
3️⃣ Test our APIs!
Once you've obtained an Access Token, you're finally ready to test our API using Bruno. Select the method you want to try, fill in the request parameters, and click the Send arrow (or press Ctrl/Cmd + Enter)! Have fun!
When importing the API methods from our Postman Collection, the current version of Bruno seems to add by default a "http://" prefix before the {{baseUrl}} placeholder; since baseUrl already contains the "https://" protocol, this will make all your requests fail. Luckily, to fix this issue you just need to update the URL of each API method by removing the additional "http://" prefix.
The OpenAPI file is not affected by this issue, so the API requests will immediately work once you've followed the previous steps.
Many of our methods are Company-scoped, which means they require you to specify the ID of the Company you're operating on.
The good news is that you can use Bruno to retrieve it! Check the Company-scoped Methods page for more info!