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

Name		Name	Last commit message	Last commit date
Latest commit History 46 Commits
.circleci		.circleci
bin		bin
src		src
.coveralls.yml		.coveralls.yml
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Introduction

Idylisapi functionalities

Installing idylisapi

Creating the object idylisapi

Getting SOAP client from Idylis

Getting an authorization token from Idylis

Finding a document on Idylis

Inserting a document on Idylis

Updating a document on Idylis

Deleting a document from Idylis

Unit testing the API

Credits

About

Releases 3

Packages

Languages

License

VirtuoWorks/idylisapi

Folders and files

Latest commit

History

Repository files navigation

Introduction

Idylisapi functionalities

Installing idylisapi

Creating the object idylisapi

Getting SOAP client from Idylis

Getting an authorization token from Idylis

Finding a document on Idylis

Inserting a document on Idylis

Updating a document on Idylis

Deleting a document from Idylis

Unit testing the API

Credits

About

Resources

License

Stars

Watchers

Forks

Releases 3

Packages 0

Languages

Packages