OpenApi NodeJS Client

Installation

npm install @altravia/openapi

const OpenApi = require('@altravia/openapi').default;

Usage

In order to use the client, you need an active openapi.it account. You can register for free on developers.openapi.it.

We can now initialize the client with the credentials that we find in our dashboard and a valid token

const client = await OpenApi.init('production', your@email.com, your_production_api_key, your_token);

Where production (or test) is the environment we want to work in; please note that API Keys and tokens for the production and test environment are different.

If you want to see your active tokens, please visit developers.openapi.it/tokens.

Besides, the client will automatically renew the provided token when needed.

Generate a token

If we don't have a token yet, we can easily generate a new one giving either the full scope or pass just the base-url as a shorthand, which will give us access to all the endpoints and methods of the web service:

const scopes = [
    "PUT:ws.messaggisms.com/messages",
    "GET:ws.firmadigitale.com/richiesta",
    "POST:ws.firmadigitale.com/richiesta",
    'imprese.altravia.com',
    'pa.openapi.it',
    // Both syntax are accepted
];

let client = await OpenApi.init('test', your@email.com, your_api_key);
const token = await client.generateToken(scopes);

// The new token will be set and returned, 
// we can now save on a database if needed ...

// The client is now ready to make requests

Please note that wildcards for base urls are not supported at the moment:

// This will work
const token = await client.generateToken('*:pa.openapi.it/*');
// This is equivalent to the previous (just a shortcut)
const token = await client.generateToken('pa.openapi.it');

// This will NOT work
const token = await client.generateToken('*:*/*');

Heads up: undefined methods

The client will instantiate only the instances needed based on the provided token: if you get undefined method when you attempt to run a request, please check if you have all the required permissions.

Make requests

Once the client has been initialized, we can start making requests: all the available methods will be loaded based on the provided token.

As an example, let's request the list of all cities in a given CAP

const cities = await client.comuni.getCitiesByCap('00132')
try {
} catch(err) {
    // err handling logic...
}

// The client uses promises, so we can choose the syntax we prefer
client.comuni.getCitiesByCap('00132')
    .then(res => {
        
    })
    .catch(err => {

    })

Or a list of companies in Rome

const imprese = await client.imprese.search({ provincia: 'RM' })

The library is typed, so you will get hints in supported IDEs of all the available methods.

Currently, those are the available web services:

• comuni
• imprese
• geocoding
• pa
• firmaDigitale
• marcheTemporali
• pecMassiva
• valutometro
• splitpayment
• europeanVat
• visengine
• postontarget
• domains
• ufficioPostale

While most of them are straight forward, some may need additional explanation. Please check out the more comprehensive documentation:

VISENGINE

SMS