Getting Started with Webservices Integration

Introduction

In order to facilitate data integration between VIF products and existing IS, VIF provides webservices. The purpose of this document is to describe this integration mode.

Some definitions

What is a webservice?

It is a service provided by a server, intended for another server, communicating with each other via the Internet. Therefore, it is a machine-to-machine communication using HTTP technology to transfer data written in multiple formats such as XML or JSON.

And the JSON format ?

JSON (JavaScript Object Notation) is a data exchange format in readable text. It is useful to represent data structures and simple objects.

Example of JSON representation for an item entity:

{
  "companyCode": "C1",
  "code": "MEAT1",
  "label": "ITEAM MEAT 1",
  "validityEndDate": "2030-12-31T00:00:00Z",
  "firstUnitCode": "COL",
  "secondUnitCode": "KG",
  "unitConversions": [
	{
  	"referenceUnitCode": "COL",
  	"referenceQuantity": 1,
  	"unitCode": "KG",
  	"quantity": 3.6,
  	"constantQuantity": true
	},
	{
  	"referenceUnitCode": "COL",
  	"referenceQuantity": 1,
  	"unitCode": "UVC",
  	"quantity": 12,
  	"constantQuantity": true
	}
  ],
  "stockInfos": {
	"firstUnitCode": "COL",
	"secondUnitCode": "KG",
	"thirdUnitCode": null
  }
}

Integration diagram

Data integration to any VIF app goes through the VIF Hub component, which is responsible for guiding the data to the targeted apps.

Since webservices are provided by VIF, client’s IS has to invoke them. This integration component does not send requests (webservices, notification …) to the outside world.

Which data can we integrate?

VIF Hub integration component provides a large number of webservices to meet all customer needs. It allows to integrate:

technical data (item, area, customer, …) feeding Data Hub
dynamic data (manufacturing ordre, sales, …) feeding other targeted apps.

The list of integrable data is updated regularly and is enriched over new versions. This exhaustive list is available on the page technical documentation.

For each entity, some operations are available. For instance, with the entity "Item", you will find the following operations:

read a list of items
read an item according to its code
create/Update an item
delete an item (this will move the item to the trash)
import a list of items

The list of available operations depends on the entity.

Access to webservices

Each client environment is accessible by an address respecting the following model :
https://<ClientName>-<EnvironmentName>.cloud.vif.fr/

The application name is added to this address. For instance, to access Data Hub :
https://<ClientName>-<EnvironmentName>.cloud.vif.fr/data-hub/

Accessing webservices follows the same model. They are accessible using this address prefix: https://<ClientName>-<EnvironmentName>.cloud.vif.fr/api-ext/

Security

Webservices securisation is similar to the one implemented for standard web interfaces (Data Hub, VIF MES Performance, VIF S&OP …).

The principle is as follows:

Request an authentication token by calling Admin Hub or having an API Token.
Using this token to request webservices by setting it as a header (X-Token).

Request a token

Two methods can be use to get a token.

Authentication token

Requesting this token goes through the same process as a login via the user interface, then it is necessary to provide an email and a password. To more easily identify the origin of the data, we advise to create a user dedicated to webservices.

To ask for a token, you need to build a REST request having all of the following parameters :

with the POST method
with the HTTP header : "Content-Type: application / json"
with the request body:

{
    "login": "<WebservicesUsername>",
    "password": "<WebservicesPassword>"
}

the address https://<ClientName>-<EnvironmentName>.cloud.vif.fr/admin/rest/auth

In the case all query parameters are correct, then the response :

returns a 200 (Accepted) HTTP code.
returns the token in the body, similar to the following one :

eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MTgxNjM4NDQsImp0aSI6Im0wdEpTLVpkdmFTdEN0bnlZMW1aYlEiLCJpYXQiOjE1MTY4Njc4NDQsIm5iZiI6MTUxNjg2NzcyNCwic3ViIjoiZGxAd
mlmLmZyIiwiaXNzIjoiVklGIiwiYXV0aGVudGljYXRlZFVzZXIiOiJlSnpOVTh0dXdqQVEvQlhMWi9wSWU4dXBMYVJTcEFBcFVIcEFxRExKUWl3NWRtUnZrQ2ppZy9vZC9iSGFCbEdDVUNzNDll
YWRuWm1kYk93MUZXckJKUTFwdedefjhfdjdfddgdsgffrfrfjjsqlderuoifeldknjscvbfjds
frd,krkjvTGg2V2ZINDkxN1JGNTF3YjdMRVNMTjVoY21VaHdmWklFclg3THg2U0MtdEdQWHZPVkZrNVlyaW1QS2RoNEpEY2tRZVJaODVBdU9McmM4RUY0Mml4aW1tUVNFTlp
DN0ZwVVRESVpvS2JvdlRvc2MxdGNNcUdESkYwbVVZdXlSTUlBV1Nnc2dJT3pDOU5nN3lFRHlXZEpLcTFxdUFtWlpvYmVoelUwSEN5blhGM091b3dUaEp5UmRLay96cU8vYWFhMFg2Um5aUHEzNj
VyNjNoL09saUVobmlnT2YrSEhSeXlVMjJuaURPR1QxdVUxVmdvelpHRGNlNlBuVzdjODc5c2QxL2JCNmthWEV2UlNyamVWck9adW05cHFvS0xWSDZuZjZtc2poYk1wRHpEV3RzTzZocnNKbmdHMH
NCb1ZYbWpOMnVFSUpuRU9IY1BHSlpGUFh0SGUwSDNqV1MzdTVHdmlLVlVTTWJ4TTkxOEE2WXZSL0k9In0.NFMgxLSa7FsFa2nzx1OPoz2lSdrKbPxYiFv5m0AsAIw

Here are the possible errors:

401 return code : authentication failure
403 return code : offer requested is not allowed
404 return code : the requested address is incorrect
460 return code : no tenant provided
461 return code : account of the user temporarily blocked
462 return code : authentication failed
463 return code : password is out of date
464 return code : provided tenant is unknown

This token is valid for 15 days by default, so it is advisable to renew it regularly.

Note : An example of this query in the Postman tool is provided at Testing webservices.

API Token authentication

Token is valid for 15 days, so to avoid renewing authentication every 15 days to get a new token, it is possible to use an API Token.

API Token has no expiration date, then be careful to keep it safe. If the case you lose it, you can easily revoke it and generate a new one.

API Token is available in user details section of Admin application (https://<ClientName>-<EnvironmentName>.cloud.vif.fr/admin-hub/#/technicaldata/users/).

In user details, there is a new section called "API Token" in which you can generate a new token. As soon as a new token is generated, you can use it directly in your API Call into X-Token Header instead of the Auth Token.

You can revoke a token and it’s immediatly taken into account.

Secure request from a webservice

All webservices are described in the technical documentation section. In terms of security, webservices work the same way. It means that any request must have the two following HTTP headers :

X-Token which is the authentication token or API Token
X-Application must have the value 'CLIENT'.

HTTPS protocol explanation

All webservices are accessible by the HTTPS protocol to be more secured. Here is an explanation.

Technical documentation

It references data for integration. For each of them, we find the list of authorized operations.

Read operations

For read operations (unitary or list), the HTTP GET verb is used.
This request generally requires parameters (to be included in the request address) specified in the documentation:

When the settings are correct, the response has the following characteristics:

an HTTP 200 return code
a message format according to the one specified in the documentation:

When the settings are incorrect, the response has a 404 HTTP code.
When the webservice component fails to process the request, the response is a 500 HTTP code.

Create/Update operation

One single webservice is available for both creation and update operations. It works as follows :

if the submitted data is unknown, then it is created
otherwise, the known version is updated

For this creation/update webservice, the HTTP POST verb is used.
This request requires parameters (to be included in the request address) specified in the documentation:

In addition to these parameters, this type of request requires a structured message that describes the data to be created/updated. Its structure is described in the documentation:

In the description, we find:

the data structure
the name of the attributes
the type of data expected
the mandatory nature of certain attributes (required)
possibly business rules (maximum length of a string of characters …)

When the request is an update, only attributes mentioned in the request are updated, other attributes remain unchanged.

When the parameters are correct, the response has the following characteristics:

201 HTTP return code
a message containing the created/updated object

When the submitted object does not respect the business rules, the response has a 400 HTTP code.

When one of the VIF components fails to process the request, the response has a 500 HTTP code.

Delete operation

For the delete operation, the HTTP DELETE verb is used.

Depending on the data, either it is actually deleted or moved to the bin. In case of technical data (managed in Data Hub), it is moved to the bin.

This requets type requires parameters (to be included in the request address) specified in the documentation:

When the settings are correct, the response has a 204 HTTP code and none message is returned.

When the submitted object does not respect the business rules, the response has a 400 HTTP code.

When one of the VIF components fails to process the request, the response presents a 500 HTTP code.

Import operation

One webservice is provided to manage bulk imports. Unlike the previous ones, it works in asynchronous mode. It means that as soon as the webservice request is done, a 202 HTTP code response is returned immediately. The import processing is done in background.

Important note:

Due to the asynchrone mode, it is recommended to sequence requests of this type by spacing them by 30 seconds. Thus, data treatments have enough time to succeed one another.

For this import webservice, the HTTP POST verb is used.

This type of request requires parameters (to be included in the request address) specified in the documentation:

In addition to these parameters, this type of request requires a structured message describing the data to be imported. Its structure is described in the documentation:

In the description of this format, we find:

the list of data to import into the "data" attribute
a "callback" attribute which makes it possible to set an address to receive the report at the end of the import (Cf Import reports)

When the settings are correct, the response has a 202 HTTP code.

When the submitted object does not respect the business rules, the response has a 400 HTTP code.
When one of the VIF components fails to process the request, the response presents a 500 HTTP code.

Import reports

During an import, it is possible to enter a "callback" attribute.

This attribute must be given with an address that points to a webservice. If the "callback" attribute is filled in, this webservice will receive a report at the end of the import with the following structure :

a POST request
a structured JSON message describing the import results

This address must be accessible from VIF Hub without authentication.

Here is an example of a report which is sent to the webservice :

{
  "detailedReportUrl": "/integration-hub/#/messages/ID-qreleasetrain-cloud-vif-fr-1552311374910-0-132/metadata",
  "result": true,
  "report": "143 errors, 0 creation, 0 update, 0 deletion",
  "executionId": 833,
  "errors": [
    {
      "error": "Company code entered in task 'RE' does not correspond to imported code 'LE' of data source (file, etc.)",
      "content": "Company code entered in task 'RE' does not correspond to imported code 'LE' of data source (file, etc.)"
    },
    {
      "error": "Company code entered in task 'RE' does not correspond to imported code 'LE' of data source (file, etc.)",
      "content": "Company code entered in task 'RE' does not correspond to imported code 'LE' of data source (file, etc.)"
    }

Limits and Best practices

Here are the limitations that you need to know :

Call type

HTTP method

Maximum body size per request

Maximum number of requests per minute

Creation of a data

POST

10 Mb (recommended)
20 Mb (maximum)

60 (synchronous)

Modification of a data

PUT

Retrieving a list of data

GET

Deactivation/Deletion of data

DELETE

None

Importing a list of data

POST

10 Mb (recommended)
20 Mb (maximum)

6 (because asynchronous)

Here are the best practices :

Data manipulation

Creation/Modification of data ⇒ cancels and replaces
Importing a list of data ⇒ adding or modifying the elements present in the list only

Data import

Import only data created/modified since the last import ⇒ Exclude unchanged data
Cut the lists of data to import according to the volume

Use limitations of webservices

Max body size per request

To guarantee a good quality of service, VIF recommends to respect the following constraints :

Successive requests from the import webservices must respect an interval of 30 seconds. Since these requests are asynchronous, this timelapse ensures the requested processing is correctly supported.
Any request to webservices is limited in the size of the transmitted data. This limit is set to 20MB. Therefore, it is necessary to ensure that the JSON data sent meets this threshold.

Since the unit size of each data is variable, the maximum number of data to be sent depends on the entity. For instance, here is a table illustrating it :

Entity model

Entity size (en octets)

Maximal number of entities to be sent

Unit

184

114 000

Item

1638

12800

Activity

4400

4700

Maximum calls per minute

To guarantee a good quality of service, VIF sets maximum calls limits per minute :

6 asynchronous calls per minute
60 synchronous calls per minute

Testing webservices

In order to fully understand the operating mode of these webservices, VIF advises to test them through a webservices query tool. In the rest of this document, the Postman tool will be introduced.

Setting up Postman tool

To do it, go to the tool’s website (https://www.getpostman.com) and download the matching version to its operating system : Windows, Mac, or Linux.

Then, install it by clicking on the downloaded file.

Once the installation is complete, it opens on an interface of this type :

Create environments

Once installed, it is necessary to define the addresses of environments you will be testing on.

Here is the procedure to add an environment:

click on the gear wheel at the top right of the interface

click on "Manage Environments"
copy and save each content below in two separate files env_test.json and env_prod.json) :

{
  "id": "5c248332-567b-98fa-0b4d-e1487a09d9fb",
  "name": "Environnement de TEST",
  "values": [
    {
      "enabled": true,
      "key": "env.url.prefix",
      "value": "https://client-test.vif.fr",
      "type": "text"
    }
  ],
  "timestamp": 1517931635235,
  "_postman_variable_scope": "environment",
  "_postman_exported_at": "2018-02-06T15:40:37.472Z",
  "_postman_exported_using": "Postman/5.5.2"
}

{
  "id": "f97e3106-6ce7-b054-5b58-8e1db632089d",
  "name": "Environnement de PROD",
  "values": [
    {
      "enabled": true,
      "key": "env.url.prefix",
      "value": "https://client-prod.vif.fr",
      "type": "text"
    }
  ],
  "timestamp": 1517931686661,
  "_postman_variable_scope": "environment",
  "_postman_exported_at": "2018-02-06T15:41:29.210Z",
  "_postman_exported_using": "Postman/5.5.2"
}

click on the "Import" button at the bottom of the window that has just opened

successively select each of the created files, you must then obtain this screen:

click on "PROD environment", edit the address according to the customer and click on "Update":

then do the same for "TEST environment"
close the environment management window
in the drop-down list at the top left, select "TEST environment"

Postman is now configured to query both PROD and TEST environments.

Request an authentication token

Once the environments are configured, define the request asking for an authentication token.

Copy and save the content below in a file named authentication.json :

{
	"info": {
		"name": "Authentification",
		"_postman_id": "50db204d-7643-8426-f151-6156f283295a",
		"description": "Requête de récupération du jeton d'authentification.",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
	},
	"item": [
		{
			"name": "Récupération d'un jeton",
			"request": {
				"method": "POST",
				"header": [
					{
						"key": "Content-Type",
						"value": "application/json"
					}
				],
				"body": {
					"mode": "raw",
					"raw": "{\n  \"login\":\"email\",\n  \"password\":\"motDePasse\"\n}"
				},
				"url": {
					"raw": "{{env.url.prefix}}/admin/rest/auth",
					"host": [
						"{{env.url.prefix}}"
					],
					"path": [
						"admin",
						"rest",
						"auth"
					]
				},
				"description": ""
			},
			"response": []
		}
	]
}

Click on the "Import" button at the top left of the Postman interface:

Select the created file, the query will appear in the list of collections:

click on the request "Request a token" then on the "Body" tab:

replace the values "email" and "password" by your own credentials. (cf : request an authentication token)
click on the "Send" button to launch the request:

the token appears at the bottom of the window:

This token will be used later to request webservices.

Launch webservice queries

Once the token is fetched, your environment is ready. For the rest of this document, we will take the entity "Unit" as an example.

Copy the content below and save it in a file named Units.json :

{
	"info": {
		"name": "Webservices",
		"_postman_id": "ac6c5caa-6db5-8a5d-5cd8-3de2a3021af6",
		"description": "",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
	},
	"item": [
		{
			"name": "Lecture des unités",
			"request": {
				"method": "GET",
				"header": [
					{
						"key": "X-Token",
						"value": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MTkyMjcxMzUsImp0aSI6IloySGgtb2xTX2FUU3Rwc0xpaUVCQlEiLCJpYXQiOjE1MTc5MzExMzUsIm5iZiI6MTUxNzkzMTAxNSwic3ViIjoiVklGIiwiaXNzIjoiVklGIiwiYXV0aGVudGljYXRlZFVzZXIiOiJlSnpOazk5cXdqQVV4bDlGY3JXQll3cmJMbnJYMWFoRis0ZFdKekpreEhyVVFKcVVKTDF3NGdQdE9mWmlTNm80TjloVk50aGR6emxmZnZsSXY3TkhUR3dvUng1NkN2dW9qZFpVS2gyVEVrekhYNVdVVTZVbDBWQkxNMlRrUER1cUdlRWJVL1F6ODEySXNpSjhoN3c5b2l2azNYZHNhMlcxQVc2a1MyQ21HRWhSVjlBSzN0OUtRVTIvSWhLNFJoNnZHVHUwRVNoTmxveXFiZGwwajZ5SDdwblZ1YnRnNGFOV2dSVzNjaUdYRktTNmdEcFowYlNFVjhIdE1WeExVY0Z0U2lSVjZMdExoYnpuLytuejVPb1QyK24rNkdvaXBJU1NNdkxudGhadFJHcTlGWkpxQ3NyZWttTy9sd3lhWnp5bEtMaTQ3NHZZU0tSZ1RUcDdVUmpiR0I0V0ZqbExzbEUrVEZJM1NqNU4wL0U4R1BwaDdBYUtZaHdsK1R6R2JwaFI1by9pRzV3Ly9nTEdEZEdVYm9ocDJ2TW5PSFA4UTM0V2hia0x3MlJ6UzFSS0MxMUxNMXdUcHNDa21oYkFGVXgybFQyUXpReE1BeWRjaDJZRlVBRW00eS9hN1AyNVB6NnRRV0JIcmF1Sm1WMmp3d2YzKzdqSiJ9.sUOPVheA6pRvtRMAUoP7i7UFGhnkG4F6iFtKa4qh_p4"
					},
					{
						"key": "X-Application",
						"value": "CLIENT"
					},
					{
						"key": "Content-type",
						"value": "application/json"
					}
				],
				"body": {
					"mode": "raw",
					"raw": "          {\n  \"unit1\": \"WSAG1\",\n  \"unit2\": \"XXX\",\n  \"quantity1\": 1,\n  \"quantity2\": 200\n}"
				},
				"url": {
					"raw": "{{env.url.prefix}}/api-ext/units",
					"host": [
						"{{env.url.prefix}}"
					],
					"path": [
						"api-ext",
						"units"
					]
				},
				"description": ""
			},
			"response": []
		},
		{
			"name": "Lecture d'une unité",
			"request": {
				"method": "GET",
				"header": [
					{
						"key": "X-Token",
						"value": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MTkyMjcxMzUsImp0aSI6IloySGgtb2xTX2FUU3Rwc0xpaUVCQlEiLCJpYXQiOjE1MTc5MzExMzUsIm5iZiI6MTUxNzkzMTAxNSwic3ViIjoiVklGIiwiaXNzIjoiVklGIiwiYXV0aGVudGljYXRlZFVzZXIiOiJlSnpOazk5cXdqQVV4bDlGY3JXQll3cmJMbnJYMWFoRis0ZFdKekpreEhyVVFKcVVKTDF3NGdQdE9mWmlTNm80TjloVk50aGR6emxmZnZsSXY3TkhUR3dvUng1NkN2dW9qZFpVS2gyVEVrekhYNVdVVTZVbDBWQkxNMlRrUER1cUdlRWJVL1F6ODEySXNpSjhoN3c5b2l2azNYZHNhMlcxQVc2a1MyQ21HRWhSVjlBSzN0OUtRVTIvSWhLNFJoNnZHVHUwRVNoTmxveXFiZGwwajZ5SDdwblZ1YnRnNGFOV2dSVzNjaUdYRktTNmdEcFowYlNFVjhIdE1WeExVY0Z0U2lSVjZMdExoYnpuLytuejVPb1QyK24rNkdvaXBJU1NNdkxudGhadFJHcTlGWkpxQ3NyZWttTy9sd3lhWnp5bEtMaTQ3NHZZU0tSZ1RUcDdVUmpiR0I0V0ZqbExzbEUrVEZJM1NqNU4wL0U4R1BwaDdBYUtZaHdsK1R6R2JwaFI1by9pRzV3Ly9nTEdEZEdVYm9ocDJ2TW5PSFA4UTM0V2hia0x3MlJ6UzFSS0MxMUxNMXdUcHNDa21oYkFGVXgybFQyUXpReE1BeWRjaDJZRlVBRW00eS9hN1AyNVB6NnRRV0JIcmF1Sm1WMmp3d2YzKzdqSiJ9.sUOPVheA6pRvtRMAUoP7i7UFGhnkG4F6iFtKa4qh_p4"
					},
					{
						"key": "X-Application",
						"value": "CLIENT"
					},
					{
						"key": "Content-type",
						"value": "application/json"
					}
				],
				"body": {
					"mode": "raw",
					"raw": "          {\n  \"unit1\": \"WSAG1\",\n  \"unit2\": \"XXX\",\n  \"quantity1\": 1,\n  \"quantity2\": 200\n}"
				},
				"url": {
					"raw": "{{env.url.prefix}}/api-ext/units/KG",
					"host": [
						"{{env.url.prefix}}"
					],
					"path": [
						"api-ext",
						"units",
						"KG"
					]
				},
				"description": ""
			},
			"response": []
		},
		{
			"name": "Création d'une unité",
			"request": {
				"method": "POST",
				"header": [
					{
						"key": "X-Token",
						"value": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MTkyMjcxMzUsImp0aSI6IloySGgtb2xTX2FUU3Rwc0xpaUVCQlEiLCJpYXQiOjE1MTc5MzExMzUsIm5iZiI6MTUxNzkzMTAxNSwic3ViIjoiVklGIiwiaXNzIjoiVklGIiwiYXV0aGVudGljYXRlZFVzZXIiOiJlSnpOazk5cXdqQVV4bDlGY3JXQll3cmJMbnJYMWFoRis0ZFdKekpreEhyVVFKcVVKTDF3NGdQdE9mWmlTNm80TjloVk50aGR6emxmZnZsSXY3TkhUR3dvUng1NkN2dW9qZFpVS2gyVEVrekhYNVdVVTZVbDBWQkxNMlRrUER1cUdlRWJVL1F6ODEySXNpSjhoN3c5b2l2azNYZHNhMlcxQVc2a1MyQ21HRWhSVjlBSzN0OUtRVTIvSWhLNFJoNnZHVHUwRVNoTmxveXFiZGwwajZ5SDdwblZ1YnRnNGFOV2dSVzNjaUdYRktTNmdEcFowYlNFVjhIdE1WeExVY0Z0U2lSVjZMdExoYnpuLytuejVPb1QyK24rNkdvaXBJU1NNdkxudGhadFJHcTlGWkpxQ3NyZWttTy9sd3lhWnp5bEtMaTQ3NHZZU0tSZ1RUcDdVUmpiR0I0V0ZqbExzbEUrVEZJM1NqNU4wL0U4R1BwaDdBYUtZaHdsK1R6R2JwaFI1by9pRzV3Ly9nTEdEZEdVYm9ocDJ2TW5PSFA4UTM0V2hia0x3MlJ6UzFSS0MxMUxNMXdUcHNDa21oYkFGVXgybFQyUXpReE1BeWRjaDJZRlVBRW00eS9hN1AyNVB6NnRRV0JIcmF1Sm1WMmp3d2YzKzdqSiJ9.sUOPVheA6pRvtRMAUoP7i7UFGhnkG4F6iFtKa4qh_p4"
					},
					{
						"key": "X-Application",
						"value": "CLIENT"
					},
					{
						"key": "Content-type",
						"value": "application/json"
					}
				],
				"body": {
					"mode": "raw",
					"raw": "{\n    \"code\": \"KG\",\n    \"label\": \"Kilo\",\n    \"unitFamily\": \"PDS\",\n    \"nbDecimals\": 4,\n    \"ediReference\": \"KGM\"\n}"
				},
				"url": {
					"raw": "{{env.url.prefix}}/api-ext/units",
					"host": [
						"{{env.url.prefix}}"
					],
					"path": [
						"api-ext",
						"units"
					]
				},
				"description": ""
			},
			"response": []
		},
		{
			"name": "Import d'une kiste d'unités",
			"request": {
				"method": "POST",
				"header": [
					{
						"key": "X-Token",
						"value": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MTkyMjcxMzUsImp0aSI6IloySGgtb2xTX2FUU3Rwc0xpaUVCQlEiLCJpYXQiOjE1MTc5MzExMzUsIm5iZiI6MTUxNzkzMTAxNSwic3ViIjoiVklGIiwiaXNzIjoiVklGIiwiYXV0aGVudGljYXRlZFVzZXIiOiJlSnpOazk5cXdqQVV4bDlGY3JXQll3cmJMbnJYMWFoRis0ZFdKekpreEhyVVFKcVVKTDF3NGdQdE9mWmlTNm80TjloVk50aGR6emxmZnZsSXY3TkhUR3dvUng1NkN2dW9qZFpVS2gyVEVrekhYNVdVVTZVbDBWQkxNMlRrUER1cUdlRWJVL1F6ODEySXNpSjhoN3c5b2l2azNYZHNhMlcxQVc2a1MyQ21HRWhSVjlBSzN0OUtRVTIvSWhLNFJoNnZHVHUwRVNoTmxveXFiZGwwajZ5SDdwblZ1YnRnNGFOV2dSVzNjaUdYRktTNmdEcFowYlNFVjhIdE1WeExVY0Z0U2lSVjZMdExoYnpuLytuejVPb1QyK24rNkdvaXBJU1NNdkxudGhadFJHcTlGWkpxQ3NyZWttTy9sd3lhWnp5bEtMaTQ3NHZZU0tSZ1RUcDdVUmpiR0I0V0ZqbExzbEUrVEZJM1NqNU4wL0U4R1BwaDdBYUtZaHdsK1R6R2JwaFI1by9pRzV3Ly9nTEdEZEdVYm9ocDJ2TW5PSFA4UTM0V2hia0x3MlJ6UzFSS0MxMUxNMXdUcHNDa21oYkFGVXgybFQyUXpReE1BeWRjaDJZRlVBRW00eS9hN1AyNVB6NnRRV0JIcmF1Sm1WMmp3d2YzKzdqSiJ9.sUOPVheA6pRvtRMAUoP7i7UFGhnkG4F6iFtKa4qh_p4"
					},
					{
						"key": "X-Application",
						"value": "CLIENT"
					},
					{
						"key": "Content-type",
						"value": "application/json"
					}
				],
				"body": {
					"mode": "raw",
					"raw": "{\n\t\"data\":[\n\t\t{\n\t\t    \"code\": \"KG\",\n\t\t    \"label\": \"Kilo\",\n\t\t    \"unitFamily\": \"PDS\",\n\t\t    \"nbDecimals\": 4,\n\t\t    \"ediReference\": \"KGM\"\n\t\t},\n\t\t{\n\t\t    \"code\": \"G\",\n\t\t    \"label\": \"Gramme\",\n\t\t    \"unitFamily\": \"PDS\",\n\t\t    \"nbDecimals\": 4,\n\t\t    \"ediReference\": \"GM\"\n\t\t},\n\t\t{\n\t\t    \"code\": \"T\",\n\t\t    \"label\": \"Tonne\",\n\t\t    \"unitFamily\": \"PDS\",\n\t\t    \"nbDecimals\": 4,\n\t\t    \"ediReference\": \"T\"\n\t\t}\n\t]\n}"
				},
				"url": {
					"raw": "{{env.url.prefix}}/api-ext/units/import",
					"host": [
						"{{env.url.prefix}}"
					],
					"path": [
						"api-ext",
						"units",
						"import"
					]
				},
				"description": ""
			},
			"response": []
		},
		{
			"name": "Suppression d'une unité",
			"request": {
				"method": "DELETE",
				"header": [
					{
						"key": "X-Token",
						"value": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MTkyMjcxMzUsImp0aSI6IloySGgtb2xTX2FUU3Rwc0xpaUVCQlEiLCJpYXQiOjE1MTc5MzExMzUsIm5iZiI6MTUxNzkzMTAxNSwic3ViIjoiVklGIiwiaXNzIjoiVklGIiwiYXV0aGVudGljYXRlZFVzZXIiOiJlSnpOazk5cXdqQVV4bDlGY3JXQll3cmJMbnJYMWFoRis0ZFdKekpreEhyVVFKcVVKTDF3NGdQdE9mWmlTNm80TjloVk50aGR6emxmZnZsSXY3TkhUR3dvUng1NkN2dW9qZFpVS2gyVEVrekhYNVdVVTZVbDBWQkxNMlRrUER1cUdlRWJVL1F6ODEySXNpSjhoN3c5b2l2azNYZHNhMlcxQVc2a1MyQ21HRWhSVjlBSzN0OUtRVTIvSWhLNFJoNnZHVHUwRVNoTmxveXFiZGwwajZ5SDdwblZ1YnRnNGFOV2dSVzNjaUdYRktTNmdEcFowYlNFVjhIdE1WeExVY0Z0U2lSVjZMdExoYnpuLytuejVPb1QyK24rNkdvaXBJU1NNdkxudGhadFJHcTlGWkpxQ3NyZWttTy9sd3lhWnp5bEtMaTQ3NHZZU0tSZ1RUcDdVUmpiR0I0V0ZqbExzbEUrVEZJM1NqNU4wL0U4R1BwaDdBYUtZaHdsK1R6R2JwaFI1by9pRzV3Ly9nTEdEZEdVYm9ocDJ2TW5PSFA4UTM0V2hia0x3MlJ6UzFSS0MxMUxNMXdUcHNDa21oYkFGVXgybFQyUXpReE1BeWRjaDJZRlVBRW00eS9hN1AyNVB6NnRRV0JIcmF1Sm1WMmp3d2YzKzdqSiJ9.sUOPVheA6pRvtRMAUoP7i7UFGhnkG4F6iFtKa4qh_p4"
					},
					{
						"key": "X-Application",
						"value": "CLIENT"
					},
					{
						"key": "Content-type",
						"value": "application/json"
					}
				],
				"body": {
					"mode": "raw",
					"raw": ""
				},
				"url": {
					"raw": "{{env.url.prefix}}/api-ext/units/KG",
					"host": [
						"{{env.url.prefix}}"
					],
					"path": [
						"api-ext",
						"units",
						"KG"
					]
				},
				"description": ""
			},
			"response": []
		}
	]
}

Click on the "Import" button at the top left of the Postman interface:

Select the created file Units.json, the query will appear in the list of collections:

Read units

click on the query "Read units"
click on the "Headers" tab

enter the value of the X-Token header with the token previously retrieved.
click on the "Send" button: the list of available units appears in the lower part of the interface:

The list of units respects the format described in the technical documentation.

Read a unit

click on the query "Read a unit"
click on the URL address of the webservice and add the code of the unit to fetch

click on the "Headers" tab

enter the value of the X-Token header with the token previously retrieved.
click on the "Send" button: the requested unit appears in the lower part of the interface:

The response follows the format described in the technical documentation.

Create/update a unit

click on the query "Create a unit"
click on the "Headers" tab

enter the value of the X-Token header with the token previously retrieved.
click on the "Body" tab

enter in the input field the attributes of the new data, or the attributes to be modified of an existing data
click on the "Send" button: the unit created (or modified) appears in the lower part of the interface:

The response follows the format described in the technical documentation.

Delete a unit

click on the query "Delete a unit"
click on the URL address of the webservice and add the code of the unit to be deleted

click on the "Headers" tab

enter the value of the X-Token header with the token previously retrieved.
click on the "Send" button: the indicated unit is then deleted (or moved to a trash). The return code of this request must be 204.

import a list of units

click on the query "Import a list of units"
click on the "Headers" tab

enter the value of the X-Token header with the token previously retrieved.
click on the "Body" tab

enter in the input field the attributes of new data, or the attributes to modify existing data
click on the "Send" button: The response is immediately returned with code 202. the import process starts in the background.