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:

| Argument | Explanation | | -------- | ----------- | | docType | The type of document that will be retrieved from Idylis API (example: "FA_DEVIS", "FA_BL", etc). | | searchCriteria | The criteria that will be used to retrieve one or more document(s) from Idylis API (example: "DATECREATION", "CODEDEVIS", etc). | | operator | The assignment operator used for the search (possible choices: "=", ">=", "<=", "<", ">"). | | criteriaValue | The value that will be used along with the search criteria (example: "PI2105033", "03/12/2020", etc. Please note that the date format must be dd/MM/yyyy). | | orderingType | The criteria with which the documents will be ordered in the response (example: "DATECREATION", "CODEDEVIS", etc). | | orderingValue | The value that will be used along with the ordering type (possible choices: "ASC", "DESC"). | | subTable | Allows to choose whether sub tables will be present in the response or not (possible choices: 0, 1). | | enclosedDoc | Allows to choose whether enclosed documents will be present in the response or not (possible choices: 0, 1). | | withCompression | Allows to choose whether the response will be compressed or not (possible choices: 0, 1). |

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:

| Argument | Explanation | | -------- | ----------- | | mainDocType | The code which represents the type of document that will be sent to Idylis API (example: "FA_DEVIS", "FA_BL", etc). | | mainDocFieldsArray | An array containing objects of pair key value representing the field as the key and the value of that field as the value. Please note that some fields are required. For instance for a quotation, the following fields are required at minimum: CODECLIENT, CODEDEVIS, MODELEDOC, DATECREA. Please also note that the totals must be calculated precisely and correspond exactly to what is expected by Idylis. The rest of the fields depend on your personal configuration of Idylis. EXP_ fields should not be included. | | subDocType (optional)| The code which represents the sub document which will be added to the main document, if any. Leave empty if not required. | | subDocFieldsArray (optional)| An array containing objects of pair key value representing the fields to be used to create the sub document. Leave empty if not required. |

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:

| Argument | Explanation | | -------- | ----------- | | docType | The type of document that will be retrieved from Idylis API (example: "FA_DEVIS", "FA_BL", etc). | | searchCriteria | The criteria that will be used to retrieve one or more document(s) from Idylis API (example: "DATECREATION", "CODEDEVIS", etc). | | primaryKey | The primary key necessary to update any table (example: "REFBL" for delivery notes or "REFDEVIS" for quotations). | | tableUpdateArray | An array containing objects of pair key value representing the table to be updated as the key and the value to be updated as the value. | | documentToUpdateXml | This represents a document to update, in XML format, returned by the findDocument method. | | refLocatorKey | OPTIONAL This represents the key to use to find the primary key to target the table to update a given sub table. Always starts with CODE (example: 'CODEDEVIS', 'CODEBL', 'CODEARTICLE' etc). | | refLocatorValue | OPTIONAL but REQUIRED with refLocatorKey This represents the value to use to use with the refLocatorKey in order to find the primary key to update a given sub table (example: 'FR' if the refLocatorKey is 'CODETVA', or 'PI14092021' if the refLocatorKey is 'CODEDEVIS' etc).|

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:

| Argument | Explanation | | -------- | ----------- | | targetTable | This represents the type of document to which the table to delete relates to (e.g.: 'FA_DEVIS', 'FA_BL', etc). | | tableCode | This is the criteria used to first search out the document to delete in order to find the value of its primary key. | | tableToDelete | This represents the value of the table to delete with this method (e.g.: 'PI210597', 'DN967425', etc). | | primaryKey | The primary key necessary to delete any table (example: "REFBL" for delivery notes or "REFDEVIS" for quotations). |

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