@virtuoworks/idylisapi v1.2.0

Introduction

An easy to use API to communicate with Idylis API. It can be used to find, update or insert a document on Idylis in a very straightforward and developer friendly way. This API was developed in order to facilitate the communication between any given API and Idylis. One only needs to be in possession of their credentials to connect to Idylis to use this API. Please note that basic knowledge of the way Idylis functions is necessary to take full advantage of the different available methods.

Idylisapi functionalities

• Get an authorization token from Idylis
• Get a SOAP client from Idylis
• Find a document (referred to as 'table' by Idylis) on Idylis
• Insert a document (referred to as 'table' by Idylis) on Idylis
• Update a document (referred to as 'table' by Idylis) (or sub document (referred to as 'table' by Idylis)) on Idylis
• Delete a document (referred to as 'table' by Idylis) on Idylis

Installing idylisapi

To add idylisapi to your project, just type the following command at the root of your project:

npm install @virtuoworks/idylisapi

Creating the object idylisapi

To be able to utilize the different methods provided by IdylisAPI, you first need to create the object that will contain all the methods by adding the following lines to your code:

Using idylisapi with ESM:

First of all, make sure you add the following line to your package.json file:

"type": "module",

Then you can type the following line in your main file:

import {idylisapi} from '@virtuoworks/idylisapi';

Using idylisapi with CJS:

const {idylisapi} = require('@virtuoworks/idylisapi');

Once you have imported idylisapi, you can use the following line to get the object containing all the methods:

const idylis = idylisapi(
  'https://exe.idylis.com/Idylisapi.asmx', /* This is the default address to get
  the WSDL from Idylis, but you might want to change it if, say, you choose
  to use a proxy between your API and Idylis */
  'CODEABONNE', /* This is your 'code abonné' parameter, which is basically
  your account name on Idylis */
  'IDENTIFIANT', /* This is your 'identifiant' parameter, which represents
  the username */
  'MOTDEPASSE', /* This is the password you use to connect to your Idylis
  account */
  'https://www.idylis.com/Idylisapi.asmx/', /* This is the default API end point
  to make calls to Idylis API. You may choose to use a different one */
);

Follow this link to get the WSDL. Follow this link to get the documentation.

Getting SOAP client from Idylis

In order to obtain a valid SOAP Client for Idylis, required to make API calls to Idylis API, we are going to use the method getSoapClient(). This method does not require any argument, and will return a valid SOAP Client instance base on Idylis' WSDL that can be used to make API calls to Idylis.

Please note that you do not need to use this method before using other methods, such as insertDocument() or findDocument(), for these methods already call getSoapClient().

// ESM
let idylisSOAPClient = '';

try {
  idylisSOAPClient = await idylis.getAuthToken();
  console.log('SOAP Client object: ', idylisSOAPClient);
} catch (error) {
    console.error(error.message);
}

// CJS
idylis.getAuthToken()
      .then((soapClient) => {
        idylisSOAPClient = soapClient;
        console.log('SOAP Client object: ', idylisSOAPClient);
      })
      .catch((error) => {
        console.log('Woops... could not get a SOAP Client object.');
      });

Getting an authorization token from Idylis

In order to obtain an authorization token, required to make API calls to Idylis API, we are going to use the method getAuthToken(). This method does not require any argument, and will return a valid token that can be used to make API calls to Idylis.

Please note that you do not need to use this method before using other methods, such as insertDocument() or findDocument(), for these methods already call getAuthToken().

// ESM
let authorizationToken = '';

try {
  authorizationToken = await idylis.getAuthToken();
  console.log('New token: ', authorizationToken);
} catch (error) {
    console.error(error.message);
}

// CJS
idylis.getAuthToken()
      .then((token) => {
        authorizationToken = token;
        console.log('New token: ', authorizationToken);
      })
      .catch((error) => {
        console.log('Woops... could not get a new token.');
      });

Finding a document on Idylis

The idylisapi object has a method called findDocument() which allows to find a given document on Idylis. To do so, findDocument() requires certain arguments to function. The arguments are as follow:

This method returns either a boolean if the document couldn't be found on Idylis, or the raw document itself under the form of a string if it was successfully retrieved from Idylis. Please make sure every argument passed to a method is a string, unless clearly stated as requiring a number or an object! If you need to use a variable, use a template literal

// ESM
let documentFound = '';

try {
  documentFound = await idylis.findDocument(
    'FA_DEVIS',
    'DATECREA',
    '>',
    '01/05/2020',
    'DATECREA',
    'ASC',
    1,
    0,
    0,
  );
  
  console.log(`This is the document found on Idylis: ${documentFound}`);
} catch (error) {
  console.error(error.message);
};

// CJS
let documentFound = '';

idylis.findDocument(
  'FA_DEVIS',
  'DATECREA',
  '>',
  '01/05/2020',
  'DATECREA',
  'ASC',
  1,
  0,
  0,
)      
.then((data) => {
  console.log('Document found: ', data);
})
.catch((error) => {
  console.log('Woops... could not get the document you seek.');
});

Inserting a document on Idylis

The idylisapi object has a method called insertDocument() which allows to insert a document on Idylis. This method allows you to insert one document, or one document and its sub document, for instance a quotation (FA_DEVIS) and its related products (FA_DETAILARTICLEDEVIS). To do so, insertDocument() requires certain arguments to function. The arguments are as follow:

This method returns a boolean that will give confirmation or denial about whether the insertion(s) was successful or not. Please make sure every argument passed to a method is a string, unless clearly stated as requiring a number or an object! If you need to use a variable, use a template literal

// ESM
let insertionResult = false;

try {
  insertionResult = await idylis.updateDocument(
    'FA_DEVIS',
    [
      {'CODECLIENT': 'CUST001'}, // required
      {'CODEDEVIS': 'PI00001'}, // required
      {'MODELEDOC': '133'}, // required. This number can be found in your Idylis Dashboard
      {'DATECREA': '15/09/2021'}, // required
    ]
    'FA_DETAILARTICLESDEVIS', // optional
    [
      {'CODEARTICLE': 'PROD001'},
      {'CODEDEVIS': 'PI00001'},
      {'CODETVA': '1'}, // 1 for VAT, 0 for no VAT
      {'DESCRIPTIF': 'My super new product'}, 
      {'PU': '120'}, // Price including product tax
      {'QTE': '3'},
      {'TAUXTVA': '20,00'},
      {'TOTTVA': '60,00'},
      {'TOTTTC': '360,00'},
      {'TOTHT': '300'} // Subtraction of TOTTTC - TOTTVA
    ]
  );
} catch (error) {
  console.error(error.message);
};

if (insertionResult) {
  console.log('The insertion was successful!');
} else {
  console.error('Uh-oh... something went wrong...');
};

// CJS
let insertionResult = false;

idylis.updateDocument.updateDocument(
    'FA_DEVIS',
    [
      {'CODECLIENT': 'CUST001'}, // required
      {'CODEDEVIS': 'PI00001'}, // required
      {'MODELEDOC': '133'}, // required. This number can be found in your Idylis Dashboard
      {'DATECREA': '15/09/2021'}, // required
    ]
    'FA_DETAILARTICLESDEVIS', // optional
    [
      {'CODEARTICLE': 'PROD001'},
      {'CODEDEVIS': 'PI00001'},
      {'CODETVA': '1'}, // 1 for VAT, 0 for no VAT
      {'DESCRIPTIF': 'My super new product'}, 
      {'PU': '120'}, // Price including product tax
      {'QTE': '3'},
      {'TAUXTVA': '20,00'},
      {'TOTTVA': '60,00'},
      {'TOTTTC': '360,00'},
      {'TOTHT': '300'} // Subtraction of TOTTTC - TOTTVA
    ]
  )
  .then((insertionResult) => {
    console.log('The insertion was successful!');
  })
  .catch(error) {
    console.log(error.message);
  };

Updating a document on Idylis

The idylisapi object also has a method called udpateDocument() which allows to update one or many document(s) on Idylis. To do so, udpateDocument() requires certain arguments to function. The arguments are as follow:

This method returns a boolean that will give confirmation or denial about whether the update was successful or not. Please make sure every argument passed to a method is a string, unless clearly stated as requiring a number or an object! If you need to use a variable, use a template literal

// ESM
let updateResult = false;
let documentToUpdate = '';

try {
  documentToUpdate = await idylis.findDocument(
    'FA_DEVIS',
    'CODEDEVIS',
    '=',
    'PI21032021',
    'CODEDEVIS',
    'ASC',
    1,
    0,
    0,
  );
} catch (error) {
  console.error(error);
};

try {
  updateResult = await idylis.updateDocument(
    'FA_DEVIS',
    'CODEDEVIS',
    'REFDEVIS',
    [
      {'ADRESSE1': '42, Universe Street'},
      {'NOMCONTACT': 'Doe'},
      {'PRENOMCONTACT': 'John'}
    ],
    documentToUpdate,
    // '<refLocatorKey to locate the primary key>'  /* This last parameter is optional and should only be used if you need to update a sub table */
    // '<value associated to the refLocatorKey>'  /* This last parameter is required if refLocatorKey has been given a value to update a sub table */
  );
} catch (error) {
  console.error(error.message);
};

if (updateResult) {
  console.log('The update was successful!');
} else {
  console.error('Uh-oh... something went wrong...');
};

// CJS
let updateResult = false;
let documentToUpdate = '';

let documentToUpdate = '';

idylis.findDocument(
    'FA_DEVIS',
    'CODEDEVIS',
    '=',
    'PI21032021',
    'CODEDEVIS',
    'ASC',
    1,
    0,
    0,
  )
  .then((document) => {
    documentToUpdate = document;
  })
  .catch((error) => {
    console.error(error);
  });


idylis.updateDocument(
    'FA_DEVIS',
    'CODEDEVIS',
    'REFDEVIS',
    [
      {'ADRESSE1': '42, Universe Street'},
      {'NOMCONTACT': 'Doe'},
      {'PRENOMCONTACT': 'John'}
    ],
    documentToUpdate,
    // '<refLocatorKey to locate the primary key>'  /* This last parameter is optional and should only be used if you need to update a sub table */
    // '<value associated to the refLocatorKey>'  /* This last parameter is required if refLocatorKey has been given a value to update a sub table */
  )
  .then((updateResult) => {
    console.log('Great! The update was successful!')
  })
  .catch(error) {
    console.error(error.message);
  };

Deleting a document from Idylis

The idylisapi object also has a method called deleteDocument() which allows to delete one given document on Idylis. To do so, deleteDocument() requires certain arguments to function. The arguments are as follow:

This method returns a boolean that will give confirmation or denial about whether the deletion was successful or not. Please make sure every argument passed to a method is a string, unless clearly stated as requiring a number or an object! If you need to use a variable, use a template literal

// ESM
let deletionResult = false;

try {
  deletionResult = await idylis.deleteDocument(
    'FA_DEVIS',
    'CODEDEVIS',
    'PI210839',
    'REFDEVIS',
  );
} catch (error) {
  console.error(error.message);
};

if (deletionResult) {
  console.log('The deletion was successful!');
} else {
  console.error('Hmmm... the document could not be deleted.');
};

// CJS
let deletionResult = false;

idylis.deleteDocument(
    'FA_DEVIS',
    'CODEDEVIS',
    'PI210839',
    'REFDEVIS',
  )
  .then((deletionResult) => {
    console.log('Great! The deletion was successful!')
  })
  .catch(error) {
    console.error(error.message);
  };

Unit testing the API

In order to be able to locally unit test the API, you will have to use the following command at the root of your project:

npm run test-dev <CODEABONNE> <IDENTIFIANT> <MOTDEPASSE>

This will build the application and start the tests with jest.

Credits

Virtuoworks