Vanilla Code Examples
In this section of the Developer Hub, we provide a set of useful guides to use our SDKs to interact with the Fatture in Cloud APIs. We strongly suggest using our SDKs whenever possible, but some use cases make it impossible to use them.
For example, you could be in one of the following situations:
- We don't (currently) provide an SDK for your programming language
- The SDK for your language doesn't support your version (for example, you're using an obsolete version of PHP)
- You're having some version conflict while installing our SDK
In these cases, it could be impossible to use one of our SDKs, or the effort required to use them could be unacceptable. On the other hand, some users could still decide to avoid our SDKs for various reasons, even if it would be technically possible to install them.
Whatever the case, it is still possible to use our APIs by using Vanilla Code, by implementing our SDKs' behavior on your own.
We strongly suggest using our SDKs because:
- The SDKs abstract your code, making it possible to ignore the implementation details
- Our guides are mostly based on our SDKs, so it will be faster to develop a functioning integration
- Our SDKs provide models containing all the fields that represent the API resources
- Our SDKs code is tested and used by many other users
- We offer support for our SDKs, so if a bug is detected we can fix it with the next release
- We won't debug your custom code (even if you send us the code snippet)
Since it is impossible to create vanilla code guides for every existing programming language, and since each language has a possibly huge set of similar libraries that could be used to implement the integration, we decided to not provide vanilla code examples. Instead, we decided to provide you with enough information to help you implement the code on your own.
🏎 Wanna be faster?
If your environment is incompatible with our SDKs, but you would still like to use something similar, you could try to generate your own library thanks to our OpenAPI specification. It is the same procedure we use to create our SDKs, so you could give it a try too.
For example, you could try to check if the OpenAPI Generator provides a generator compatible with your environment: the generator offers more languages than the ones we currently support, and some generator options could make the generated code compatible with your environment (targeting a language version or selecting a different library). Also, it is possible to find alternative code generators, or you can decide to use a self-generating library.
If you don't want to include our SDKs because you just need a subset of our methods, you could also download and modify our OpenAPI file, removing all the parts that are unuseful for your use case; if you use this file as input for the generator, you'll obtain a smaller library than the official one.
For additional information, you can check the resources linked to the OpenAPI specification page.
🔧 Can I modify your libraries?
Sure! Our SDKs and our Prestashop module are released under MIT License, so feel free to modify them to meet your requirements. The code is freely available on GitHub, so feel free to customize it accordingly to your needs.
If you think that the modifications you developed could be useful for the rest of the Community, then we invite you to open a Pull Request on our GitHub repositories!
Please, notice that to open a PR the first step is to create a public Fork and publish your modifications to a branch in your repo; we won't accept or review code passed through any other mode. See also: Contributing to projects
Our SDKs are in large part generated!!! This means that your modifications could be overwritten while generating a new version, so we will most probably reject your PRs on the generated code. The OAuth and Filter helpers are not generated, so we could accept your PRs involving that part.
If you want to propose an improvement to the generated code, you could try to modify the OpenAPI specification or the templates we use to generate the code. Please, notice that not all templates are added to our repository: we include only the ones that we must customize, the other templates are the standard ones provided by the generator. As an alternative, you can try to open an issue on the SDK repo and wait for our support.
If you decide to do it on your own, you can check:
If you're having a problem with a customized library, we can still try to support you to solve the issue, but first, you should publish a PR containing your modifications. We won't review code provided in any other way.
If you publish a PR it will be easier for us to check the modifications you applied to our code, and we could additionally decide to adopt your changes into our library if the new features could be useful to the rest of the community.
🤦♂️ Can you do it for us?
We usually don't accept custom modification requests, but if you have an idea for a new functionality you can try to open a new discussion in our Community: if we think that the request could be useful also for other developers we might decide to develop it for you.
If, instead, your request is useful only for your use case, or if you don't want to wait for our intervention, you can proceed and develop the modifies on your own.
🔩 The implementation details
If you prefer to implement the integration on your own (e.g. without a generator), you will still need a few libraries to make your life easier. In some cases, your language could provide them directly without external imports, while in other cases it is mandatory to select and install additional libraries.
This is an indicative set of libraries that you could need:
- An HTTP Client
- A JSON marshaller/unmarshaller
- An OAuth2 client (optional)
This set could change based on the libraries that you select: for example, the HTTP Client could require a JSON string as request, so you'll need to perform the JSON conversion on your own; in some other cases the JSON conversion is managed directly by the client, so you'll be able to avoid to install the JSON library. Also, the OAuth2 client will be unuseful if you decide to use the Manual Authentication, or you could decide to implement the OAuth2 process on your own using the HTTP client.
The HTTP Client must be used to implement the REST Requests. The request will take advantage of the structure of HTTP Requests, in particular of the following parts:
- HTTP Method
- Request Target (the URL)
- HTTP Request Headers
- Querystring parameters
- Request Body
The HTTP Response will contain the result of the request. The HTTP Response is structured as follows:
- Status Code
- Response Body
- HTTP Response Headers
Below you can find the description of the various parts. You can check the actual values that must be used by checking the API Reference or by using the Postman Collection.
💇♂️ HTTP Method
Each HTTP request must contain an HTTP Method, that defines the kind of action that you want to perform. In the following table you can find the relationship between HTTP methods and actions:
| HTTP Method | Performed Action |
|---|---|
| GET | Read opetations (Get or List actions) |
| POST | Create operations |
| PUT | Modify operations |
| DELETE | Delete operations |
The Get or List operations are distinguished by the structure of the URL (see below).
🏹 Request Target (the URL)
The request target is an URL that identifies the resource on which the action should be performed. It could contain some Path Parameters, usually one of the following:
- Company ID
- The ID of the resource to manipulate
You can usually distinguish between List and Get methods because the Get URLs additionally include the ID of the resource to retrieve.
The Company ID is mandatory if you want to use Company-scoped Methods. If you plan to manage only one company, you can insert it directly into your code as a string; if, instead, you will manage multiple companies (and you don't know them at compile time), you must retrieve their IDs programmatically. Check the Company-scoped Methods page for more info.
🔑 HTTP Request Headers
The Headers usually contain metadata that apply to the request.
In particular, our APIs use the Authorization Header to include the Access Token. If this header is missing or it isn't in the correct format, the request will be immediately discarded. Since the OAuth2 procedure can be complicated for inexperienced programmers, we provided a dedicated vanilla code guide to show some additional examples.
💄 Query string parameters
The Query string is used by our APIs to add the parameters required to use the additional functionalities of the Read operations (e.g. Get and List); it can usually be omitted if you don't need to use those functionalities. This string is used as a suffix to the URL, and it can be used to sort, paginate, customize or filter the response.
📋 Request Body
The Request Body is used in Create and Modify requests to describe the new status of the resource after the action has been applied. Our APIs use solely JSON to represent the request, so you could need a JSON marshaller to create the body string.
✅ Status Code
The Status Code is used to define if an operation was concluded with a success (2xx codes), with a client error (4xx codes), or with a server error (5xx codes).
📜 Response Body
The response body will contain the following:
- Get requests: it contains the current state of the selected resource
- List requests: it contains a set of resources with their current state
- Create request: it contains the state of the created resource, including also the ID of the resource generated by the server
- Modify Request: it contains the state of the modified resource
Our APIs always return a JSON response, so it must be managed accordingly.
🏷 HTTP Response Headers
The response headers are usually used to provide additional info, such as information related to limits and quotas.
🙏 Please, give me some examples!
You can obtain some examples automatically, by using our OpenAPI file or Postman Collection.
For example, if you download our Postman Collection you can automatically generate some useful vanilla code examples by following this guide: Generating Client Code.
As an alternative, you can use a code snippet generator to generate vanilla code snippets automatically for a huge variety of languages. You can obtain the info required to launch the generation by using our OpenAPI specification as a source.
Here you can find some snippet generators:
As a last chance, you can also check our SDK repositories to copy our code. The SDK internally uses the same procedure described above, so you could try to read the code and adapt it to your needs.