Create an app
The first thing you need to start using the API is an app: it is fundamental to obtain the credentials to authenticate your requests. You can create and manage apps in your Fatture in Cloud company account, in the Impostazioni > Sviluppatore page. To create a new app just press the Nuova app (New App) button and configure it as described below.
If you're NOT a developer, you don't need to create an app in Fatture in Cloud. If somebody told you to do it, then they must probably review their authentication flow. If this is the case, don't create the app and, even more important, never share your Client Secret if you already created one.
📃 App Configuration
The application can be configured on the app management page. On this page you can:
- Define the basic information of your app (name, description, logo);
- Change the visibility of your app (see below for more detailed info);
- Select the Authentication method.
Based on the selected Authentication method, the related credentials will be displayed on the page.
The Client Secret, used in the OAuth 2.0 flow, must NEVER be shared with third-party applications! If somebody asked you to pass their Client Secret, then they must be doing something wrong. Send them the link to this page, and delete your app if you already shared the Client Secret!
The Client Secret must always be kept in a secure location, such as an environment variable! Don't publish it on your frontend!
🔭 App visibility
The app visibility describes the set of users that will be able to use your new application. There are two possible options available:
- Private apps
- Public apps
When you create a brand new app, by default it is set to private. To turn it public, it is necessary to scroll to the Operazioni Avanzate (Advanced Operations) section and click on the Rendi Pubblica (Make Public) button.
Here you can find a simple flowchart to help you decide if you need the public app or not. If you want to know the details, below you can find the differences between the public and private apps.
🔒 Private Apps
By default, every app is created as private. A private app is not fully distributable to anyone, but it can be used only by whitelisted users.
The use cases for private apps can be:
- Simple API usage for import/export purposes on your company(/ies)
- Custom integration with your management software, CRM or ERP
- Anything else whose usage is limited to the context of your company(/ies) and not publicly distributed
The Users Whitelist can be updated in the E-mail degli utenti che possono utilizzare l'applicazione (Email of the users who can use the application) section of the app page as a Comma Separated e-mail list.
The Whitelist can contain up to 20 accounts, if you try to add more accounts you'll get an error response. Maybe you should turn your app public?
Please, make sure that at least your email is present in this section, otherwise, your API requests will result in a 403 error The given user is not authorized to use this application.
🌍 Public Apps
If, on the other hand, you want your app to be used and distributed publicly, you need a public app. A public app can be used by any user, but it requires some mandatory data to be filled and needs verification by the Fatture in Cloud team.
When you first switch an app from private to public, you’ll be asked for some contact information. We’ll check your request and we’ll contact you back to have some extra detailed info about your app. If the procedure will be successful your app will be flagged as public.
Your app's visibility will be switched to "public" only if your app fulfills the criteria explained below. To avoid wasting your time (and also ours), we suggest you read carefully the criteria and send the request only if you think it can be approved.
We will also reject a request if the provided explanation doesn't have a proper level of detail. So please, avoid sending short answers and try to describe what are you trying to accomplish.
Your visibility change request will be approved only when your integration will be ready to be deployed to production (at least in its first version). If your request seems legit, but you're still in the development phase, your request will be frozen and we will ask you to contact us back when you're ready. Be smart, complete your development before requiring the Public App!
As a side note, you can use the Private App to test your code, so you don't need a public app in the development phase!
👨⚖️ What are the public app criteria?
Valid use cases for public apps can be:
- SaaS or native integration
- Public e-commerce integration (if you're the developer of the integration)
- Anything else whose usage is public and made to be distributed (e.g. it must be able to be used by multiple FIC users not known at development time)
Invalid use cases include:
- Public e-commerce integration (if you're a user of a third-party plugin, and you're not developing the code actively)
- All the use cases listed in the Private Apps section
- All the valid use cases above, if the code is not yet ready to be released to Production (in this case we'll pause your request until you're ready, see below)
We can reject your request if:
- You don't answer our emails within a few days (usually seven days, you'll be able to open a new request later)
- Your response to our email is too concise (in this case we'll ask for additional info)
- If you fail to explain your use case in detail
- Your use case is not considered eligible for app publishing (see the lists above)
🏪 App Store
The Fatture in Cloud App Store is the showcase where our customers can find the integrations to simplify the entire business management process. As a developer, you can require to publish your integration to our App Store and reach more than 500.000 customers and 16.000 accountants who use Fatture in Cloud every day.
The prerequisite to requiring the publication to our App Store is to have an App with Public Visibility. Once your visibility change request is approved, you can read carefully the Publish to App Store guide.