Postman Collection
To test our API without writing a single line of code, we used our OpenAPI Specification to generate a dedicated Postman Collection.
Postman is an API Platform for building and using APIs. Postman Collections can describe 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.
0️⃣ Install Postman
To use our collection, we suggest downloading Postman on your device; it is available for Windows, Mac, and Linux.
Next, sign up to Postman: don't worry, to use our collection the Free Plan is enough 😉
1️⃣ Import the Collection
Our Collection is generated automatically using our OpenAPI Specification, and can be downloaded from our GitHub Repository at the postman/fic-api.json position; 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.
Now you're almost ready to interact with our API!
If you prefer, you can instead use our OpenAPI Specification directly, importing the openapi.yaml file using this procedure. You just need to be sure to download also the files in the models folder, otherwise, the import will fail. Also, you need to select the right parameters to import the collection correctly.
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 Postman (for example in your code) you can decide to test it using Postman! Just use it as a manual token and follow the following points, but remember OAuth 2.0 tokens expire!
Since Postman 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 in Postman!
Once you retrieved the token, you have two options to use a manual token:
-
In the Authorization section, you can select Bearer Token in the Auth Type dropdown and then paste the token in the Token field.
-
If you want to insert your header manually, you can leave No Auth in the Authorization section and add the Authorization header in the Headers section. The value of the token must be
Bearer ACCESS_TOKENwhere ACCESS_TOKEN must be replaced with the token you obtained before. 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.
🔐 OAuth 2.0 Authorization Code
If you obtained a token using one of the other methods outside of Postman (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 Postman to retrieve your Access Token automatically from its interface.
To set Postman up, click on the collection and select the Authorization tab, then compile the Configure New Token form.
The parameters are:
| Field | Value |
|---|---|
| Auth URL | https://api-v2.fattureincloud.it/oauth/authorize |
| Access Token URL | https://api-v2.fattureincloud.it/oauth/token |
| Client Authentication | Select "Set client credentials in body" |
| Callback URL | See below for further info |
All the other parameters can be found on the OAuth 2.0 Authorization Code Flow page.
The Callback URL parameter can be used differently based on what you want to test:
- If you want to perform the entire OAuth2.0 flow entirely from Postman, you can select the Authorize using Browser; a Postman URL will be automatically inserted, and you'll need to use it as Redirect URL in your Fatture in Cloud App page. In this case, a new page will be opened to your browser, and the dedicated Postman page will automatically redirect you back to your local Postman.
- Otherwise, you can insert your App's Redirect URL in the Callback URL field by deselecting the Authorize using Browser; in this case the process will be performed inside Postman instead of your browser.
In either case, the Postman's Callback URL and the Fatture in Cloud App's Redirect URL must be exactly the same!!! Otherwise, the redirect will fail and you'll not be able to perform the authorization flow.
Once you set up all the variables, you can click the Get New Access Token to be redirected to the Fatture in Cloud page and perform the flow. Postman will propose you the obtained token, and you'll be able to review it and select the one you want to use.
Additionally, if you also want to test the Refresh Token step you can set up the Refresh Token URL to https://api-v2.fattureincloud.it/oauth/token.
3️⃣ Test our APIs!
Once you've obtained an Access Token, you're finally ready to test our API using Postman. Select the method you want to try, compile the request parameters, and click the Send button! Have fun!
Many of our methods are Company-scoped, which means they require to indicate the ID of the Company we're operating on.
The good news is that you can use Postman to retrieve it! Check the Company-scoped Methods page for more info!