APIv2 migration guide
This guide is primarily for users who developed an integration using our APIv1 and need to migrate to the new APIv2.
This is intended to be a description of the main differences between the two versions of the API, meant to help you update your integration; the complete documentation of our new APIs can be found in the rest of this documentation.
If you're NOT a developer of an integration with our APIs, but you're just using a plugin or application developed by other people, then you don't need to do anything. Just contact the developer of your plugin, requesting him to update his code to the new API versions. You can send him this page to help him with the development.
If this is your first time developing an integration with Fatture in Cloud, and you never used our v1 APIs before, then we suggest checking this guide instead.
đąÂ Wait a minute! Do I have to reimplement everything from scratch?â
Unfortunately, you have to modify your code to target our new APIs. But this doesn't mean you have to do everything from scratch. We created a useful set of SDKs that can make your refactoring way easier, taking care of stuff such as the authentication and model definition steps for you. If you instead prefer to implement everything from scratch, you can read the Vanilla Code Examples page to retrieve some examples that could help you in your journey.
đ§Â How should I proceed?â
The migration strategy is entirely up to you, but we suggest starting planning it as soon as possible.
The old version of the APIs is officially deprecated, but you'll still be able to use them until the dismission date. Even if you start using our new APIs, the old version will continue to be available, and you could potentially run them in parallel. We will remind you and your current users periodically to update your integrations so that you'll be able to avoid any possible dismission-related issues.
Even so, we can suggest the following migration strategies, but you can still choose your way based on your needs:
- Implement a transitory phase, where your application continues supporting both versions of the API (but you strongly suggest switching to the new version of the API at every usage of your application); in this case, you'll have to continue supporting both versions for a certain amount of time, but the transition will be smoother for your users
- Adopt A/B testing, by releasing the new version of your integration to a small number of users to search for potential bugs, and then gradually increase the percentage of migrated users until all of them will be using the new APIs
- Force the new login using the APIv2 authentication methods, releasing a new version of your application based entirely on the new APIs; this will let you drop the support for the old APIs at once, but it could be a little more traumatic for your users.
đ Authenticationâ
The two versions of the APIs use different authentication methods, so the old credentials cannot be used with our new APIs. You'll need to reimplement this step from scratch.
The APIv1 authentication was based on a single credentials pair: each company had an API UID and API KEY couple, that was provided to the third-party application by the user to authenticate the API requests. This meant that each application used by a single company received the same credentials, and it wasn't possible to invalidate them or to assign different permissions to different integrations.
The APIv2 work differently: an integration will have a dedicated set of credentials that will be used to perform the Authentication & Authorization steps. The set of credentials can be obtained by creating an application on the Fatture in Cloud page, and it will differ based on the selected authentication method.
The APIv2 app creation must be performed by the app developer, not by the user! You will need only one app for all your users, and you'll have to take care of the generated credentials on your own.
The currently supported methods for the new APIs are:
If you are uncertain about which method best suits your needs, you can read this guide.
The Device Code Flow is not generally available, it means that it is activated only for specific use cases and only after a review by our API team. Please, feel free to contact us if you think you should use the Device Code Flow.
All the methods above will provide a new Access Token that must be used by the integration code to authenticate their requests. The final user will be able to review and assign the permissions associated with each token, and it will be possible to entirely revoke a token from the Fatture in Cloud page. This token will be directly related to a single company, so you'll obtain a wide range of tokens, one for each of the users of your integration.
If you decide to implement the OAuth 2.0 flow, then you can use the OAuth Helpers contained in our SDKs to speed up your development. Check out here for more details.
đ Methods mappingâ
Our old APIs were pretty peculiar: they used a unique HTTP method (POST), and the different methods were distinguished only by their path. The new version instead is based on the REST architectural style, so the APIs are implemented in a standard way: each method uses a specific HTTP method, related to the kind of operation you're trying to perform.
To find the APIv2 method that matches the APIv1 method you're currently using, you can check the following table:
| Method type | APIv1 (path) | APIv2 (HTTP method) |
|---|---|---|
| LIST | lista | GET |
| GET | dettagli | GET |
| CREATE | nuovo | POST |
| MODIFY | modifica | PUT |
| DELETE | elimina | DELETE |
Even if the LIST and GET methods use the same HTTP method, the two methods can be distinguished because the GET request includes the resource ID as a path parameter
Let's take, for example, the methods related to the Products. The related table will look like this:
| Method | APIv1 | APIv2 |
|---|---|---|
| LIST PRODUCTS | POST /prodotti/lista | GET /c/{company_id}/products |
| GET PRODUCT | Not available | GET /c/{company_id}/products/{product_id} |
| CREATE PRODUCT | POST /prodotti/nuovo | POST /c/{company_id}/products |
| MODIFY PRODUCT | POST /prodotti/modifica | PUT /c/{company_id}/products/{product_id} |
| DELETE PRODUCT | POST /prodotti/elimina | DELETE /c/{company_id}/products/{product_id} |
Please, notice that in some cases the APIv2 will require to add the ID of the resource to manipulate directly into the path; additionally, most of the methods will require to specify the ID of the company in the same way.
The importa methods, provided by the APIv1, are currently unsupported by the APIv2. These methods permitted to import a list of resources with a single request, instead of requiring multiple CREATE requests. Batch operations are currently in our roadmap, and will be supported in the future. Stay tuned!
If you want to focus on the meaning of those parameters instead of caring about how to provide them to our APIs, the SDKs can be useful. You just need to pass these parameters to the provided methods, and the SDKs will compose the request for you.
Also, the SDKs provide the updated models for both the requests and the responses, so you can use those as support to avoid mistakes in the body structure.
To map all the APIv1 methods to the related APIv2 ones, you also need to identify the correct resource types. Below you can find a list of the different categories that composed our APIv1 and the related resources in the new version.
Please note that in most cases the APIv2 models are much more complete than the APIv1 ones, supporting more parameters than before and thus giving you more control over the resource. Additionally, we added some additional methods that make our APIs even more powerful!
đ Anagraficaâ
The ANAGRAFICA resources have been reorganized into two different resources, based on the old soggetto parameter: CLIENTS for the old clienti and SUPPLIERS for the old fornitori.
đ Prodottiâ
The PRODOTTI resources are called PRODUCTS on the APIv2.
đ¤Â Documenti emessiâ
The DOCUMENTI EMESSI resources are now ISSUED DOCUMENTS. Additionally, you will find some methods and parameters that will enable you to manage e-invoices.
The Issued Documents creation is our most popular functionality, but also one of the more complicated to implement, so we prepared an extended guide on the topic that is meant to guide you step-by-step while developing your integration.
If you are currently using one of the autocompila_anagrafica or salva_anagrafica flags you won't find anything similar in the APIv2. You will have to use the create client and list the clients methods to replicate the same behavior. We're currently working to add something similar on the APIv2, so stay tuned!
If you are instead looking for the importo: auto functionality, which permitted to set automatically the importo of the document, it has been moved, you can find a complete explanation of the new fix_payments magic field here.
đ Â Acquistiâ
The ACQUISTI resources are now called RECEIVED DOCUMENTS.
If you are currently using one of the flags autocompila_anagrafica or salva_anagrafica you won't find anything similar in the APIv2. You will have to use the create supplier and list the suppliers methods to replicate the same behavior. We're currently working to add something similar on the APIv2, so stay tuned!
đ Corrispettiviâ
The CORRISPETTIVI resources are now called RECEIPTS.
âšī¸Â Infoâ
The INFO methods were split into many different methods, which can be found below the INFO and SETTINGS categories. While in the APIv1 these categories were exclusively read-only, the new methods let you manipulate the API configurations programmatically, without having to access the Fatture in Cloud page at all.
đ Arrivi Merceâ
The ARRIVI MERCE methods are now part of the RECEIVED DOCUMENTS.
đ arrivimerce/listaâ
You can get the list of arrivimerce using the List Received Documents method, specifying the query parameter type as passive_delivery_note or passive_credit_note.
đ arrivimerce/dettagliâ
This call translates directly to a Get Received Document.
â¨Â arrivimerce/nuovoâ
To create a new arrivomerce you need to use the Create Received Document method, the type can be passive_delivery_note or passive_credit_note, here there is a simple mapping of the fields:
- nome: entity.name
- descrizione: description
- data: date
- lista_articoli: items_list
- collega_codici_prodotti: deprecated, the product_id is now required
đ Can you please help me?â
Sure. Please, check this page to discover how to contact us.