{"id":1714,"date":"2022-09-13T11:23:10","date_gmt":"2022-09-13T09:23:10","guid":{"rendered":"https:\/\/help.ino.cx\/?post_type=ht_kb&#038;p=1714"},"modified":"2025-03-14T17:01:51","modified_gmt":"2025-03-14T16:01:51","slug":"web-services-how-to-use-them","status":"publish","type":"ht_kb","link":"https:\/\/help.ino.cx\/index.php\/help-center\/web-services-how-to-use-them\/","title":{"rendered":"Web services &#8211; set them up"},"content":{"rendered":"\n<figure class=\"wp-block-image alignright is-resized\"><img loading=\"lazy\" decoding=\"async\" width=\"1080\" height=\"400\" src=\"https:\/\/help.ino.cx\/wp-content\/uploads\/2024\/09\/Smart-licence-needed-2.png\" alt=\"\" class=\"wp-image-3984\" style=\"width:250px\"\/><\/figure>\n\n\n\n<p>[<em>Reading time: 5 minutes<\/em>]<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"overview\">Overview<\/h2>\n\n\n\n<p>A web service is an API that operates over the web, using standardized protocols (e.g., HTTP).<\/p>\n\n\n\n<figure class=\"wp-block-image aligncenter size-full is-resized\"><img loading=\"lazy\" decoding=\"async\" width=\"1137\" height=\"956\" src=\"https:\/\/help.ino.cx\/wp-content\/uploads\/2025\/03\/undraw_just-browsing_0rpb.png\" alt=\"\" class=\"wp-image-4795\" style=\"width:250px\"\/><\/figure>\n\n\n\n<p>Web services allow for making requests to external services in order to integrate data or interact with third-party APIs. They are configurable in the Maker and can be called in different contexts within the platform.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Types of web services<\/h2>\n\n\n\n<p>There are two types of web services in INO cx:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Standard<\/strong>: Web services directly configurable by the user via the Maker.<\/li>\n\n\n\n<li><strong>Customized<\/strong>: Developed specifically for custom needs and not directly modifiable through the interface.<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">Configuring a web service<\/h2>\n\n\n\n<h3 class=\"wp-block-heading\">1. <strong>Creating a Web Service<\/strong><\/h3>\n\n\n\n<p>In the Maker, go to the Data module, then the web services submodule. You will arrive at the list of previously created web services.<br>Click <strong>Create<\/strong>. A configuration window will appear, where several parameters must be defined:<\/p>\n\n\n\n<figure class=\"wp-block-image aligncenter size-full\"><img loading=\"lazy\" decoding=\"async\" width=\"534\" height=\"833\" src=\"https:\/\/help.ino.cx\/wp-content\/uploads\/2025\/03\/Capture-de\u0301cran-2025-03-11-a\u0300-17.40.03.png\" alt=\"\" class=\"wp-image-4792\"\/><\/figure>\n\n\n\n<h3 class=\"wp-block-heading\">2. <strong>Required parameters<\/strong><\/h3>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Type<\/strong>:\n<ul class=\"wp-block-list\">\n<li><strong>Standard<\/strong>: Manual configuration.<\/li>\n\n\n\n<li><strong>Customized<\/strong>: Services developed specifically for advanced needs.<\/li>\n<\/ul>\n<\/li>\n\n\n\n<li><strong>Name<\/strong>: The identifier for the web service.<\/li>\n\n\n\n<li><strong>Reference<\/strong>: Must be unique and can contain special characters (_ . + @ -).<\/li>\n\n\n\n<li><strong>HTTP method<\/strong>: The type of request that determines the interaction with the external API:\n<ul class=\"wp-block-list\">\n<li><strong>POST<\/strong> (sending new data)<\/li>\n\n\n\n<li><strong>GET<\/strong> (retrieving information)<\/li>\n\n\n\n<li><strong>PUT<\/strong> (updating an existing resource)<\/li>\n\n\n\n<li><strong>PATCH<\/strong> (partially modifying a resource)<\/li>\n\n\n\n<li><strong>DELETE<\/strong> (deleting a resource)<\/li>\n\n\n\n<li><strong>INVOKE<\/strong> (executing a specific action defined by the external API)<\/li>\n<\/ul>\n<\/li>\n\n\n\n<li><strong>URL<\/strong>: The target URL of the web service, which can include dynamic variables (e.g., https:\/\/api.example.com\/$$user$$). These variables are replaced by values during the request execution.<\/li>\n\n\n\n<li><strong>Authentication<\/strong>:\n<ul class=\"wp-block-list\">\n<li>None<\/li>\n\n\n\n<li>Basic (username and password)<\/li>\n\n\n\n<li>Bearer (authentication token)<\/li>\n<\/ul>\n<\/li>\n\n\n\n<li><strong>Password<\/strong>: Must contain between 0 and 128 characters.<\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">3. <strong>Environments<\/strong><\/h3>\n\n\n\n<p>Customized web services can be associated with specific environments (Development, Production). This allows testing integrations before deploying them to production.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Managing web services<\/h2>\n\n\n\n<p>Once created, web services appear in a list containing the following information:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Type<\/strong> (Standard or Customized)<\/li>\n\n\n\n<li><strong>Name<\/strong><\/li>\n\n\n\n<li><strong>HTTP method used<\/strong><\/li>\n\n\n\n<li><strong>Authentication type<\/strong><\/li>\n\n\n\n<li><strong>Target URL<\/strong><\/li>\n\n\n\n<li><strong>Customized web service<\/strong> (if applicable)<\/li>\n\n\n\n<li><strong>Associated environment<\/strong> (if applicable)<\/li>\n<\/ul>\n\n\n\n<p><br>The limit on web service creation is set at 50. See the article on <a href=\"https:\/\/help.ino.cx\/index.php\/help-center\/limits-client-account-settings\/\" data-type=\"link\" data-id=\"https:\/\/help.ino.cx\/index.php\/help-center\/limits-client-account-settings\/\" target=\"_blank\" rel=\"noreferrer noopener\">limits <\/a>for more details.&nbsp;<\/p>\n\n\n\n<p>You can then access the web service to add information under two tabs: <strong>settings<\/strong> and <strong>history<\/strong>. <\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Settings<\/h2>\n\n\n\n<h3 class=\"wp-block-heading\">1. <strong>Request headers<\/strong><\/h3>\n\n\n\n<p><br>HTTP headers allow for transmitting additional information with the request (optional). Each header is a key\/value pair, for example:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Content-Type: application\/json to indicate that the request body is in JSON format.<\/li>\n\n\n\n<li>Accept-Language: fr to specify the language in which the response should be returned by the API (useful for multilingual APIs).<\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">2. <strong>Request body<\/strong><\/h3>\n\n\n\n<p><br>The request body contains the data sent to the target API, usually in JSON format.<br>The body can also contain dynamic variables that will be replaced during request execution.<\/p>\n\n\n\n<p><br>When the value is a variable, it means that the value associated with the key can change or be dynamically calculated, rather than being a fixed value.<\/p>\n\n\n\n<p><br>For example, with a variable as a value:<br>Let\u2019s assume we are keeping a record of users in an application, and we want to associate a key (e.g., the username) with a value representing the age of that user. If the age changes over time, we can use a variable to keep that information updated.<br>Example:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Key:<\/strong> &#8220;Alice&#8221;<\/li>\n\n\n\n<li><strong>Value<\/strong> (variable): age (where age could be, for instance, 25 initially, and then become 26 the following year).<\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">3. <strong>Response Data Collection<\/strong><\/h3>\n\n\n\n<p><br>Once the request is made, INO cx allows you to extract certain data returned by the API for reuse.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Key<\/strong>: The field in which to store the retrieved value.<\/li>\n\n\n\n<li><strong>Value<\/strong>: A JSON expression that allows access to a specific element in the API response.<\/li>\n<\/ul>\n\n\n\n<p>Example of an API response:<\/p>\n\n\n\n<p><code>{<br>  \"data\": {<br>    \"id\": 1001,<br>    \"name\": \"Product A\",<br>    \"price\": 25.50<br>  }<br>}<\/code><\/p>\n\n\n\n<p>To retrieve the product name and price in INO cx:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Key<\/strong>: <code>product_name<\/code> \u27a1\ufe0f <strong>Value<\/strong>: <code>$$.data.name$$<\/code><\/li>\n\n\n\n<li><strong>Key<\/strong>: <code>product_price<\/code> \u27a1\ufe0f <strong>Value<\/strong>: <code>$$.data.price$$<\/code><\/li>\n<\/ul>\n\n\n\n<p>The <code>$$<\/code> notation is used to dynamically reference elements in the API response. These values can then be displayed in the interface or used in other automated actions.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">History<\/h2>\n\n\n\n<p>The <strong>history<\/strong> tab allows you to track all the requests sent and their results. Each request is recorded with the following information:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Date and time of execution<\/strong>: Allows you to identify when the request was sent.<\/li>\n\n\n\n<li><strong>Type<\/strong>: \n<ul class=\"wp-block-list\">\n<li><strong>Synchronous<\/strong>: The request is sent, and INO cx waits for the response before proceeding with the next actions. This means the result is available immediately after the request is sent.<\/li>\n\n\n\n<li><strong>Asynchronous<\/strong>: The request is sent, but INO cx does not pause execution while waiting for the response. The API may respond later, and the results will be processed once received.<\/li>\n<\/ul>\n<\/li>\n\n\n\n<li><strong>HTTP method used<\/strong>: GET, POST, etc.<\/li>\n\n\n\n<li><strong>Called URL<\/strong>: Indicates the address the request was sent to.<\/li>\n\n\n\n<li><strong>HTTP response code<\/strong>: Allows you to know if the request was successful (200 OK) or encountered an error (400 Bad Request, 500 Internal Server Error, etc.).<\/li>\n\n\n\n<li><strong>Response details<\/strong> (blue double arrow): Shows the data returned by the API.<\/li>\n<\/ul>\n\n\n\n<p>The history is particularly useful for understanding the behavior of web services and adjusting their configuration if needed.<\/p>\n\n\n\n<p><em>Note: <\/em>when a web service fails, an HTTP response code is returned. Here are some common errors and how to manage them:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>400 bad request<\/strong>: The sent request is malformed. Check the syntax of the request and ensure that all required parameters are present.<\/li>\n\n\n\n<li><strong>401 unauthorized<\/strong>: Authentication failed. Check your credentials or authentication token.<\/li>\n\n\n\n<li><strong>404 not found<\/strong>: The API URL is incorrect. Check the target URL and make sure it\u2019s valid.<\/li>\n\n\n\n<li><strong>500 internal server error<\/strong>: The external API encountered an internal error. Check the error history for more details and contact the API provider if necessary.<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">Execution and usage<\/h2>\n\n\n\n<p>Once configured, a web service can be tested using the gear icon inside the web service.<\/p>\n\n\n\n<p>It can then be used across several modules in INO cx on the <strong>Banner<\/strong> (smart routings, workflows, custom buttons).<\/p>\n\n\n\n<p><\/p>\n","protected":false},"excerpt":{"rendered":"<p>With INO, a Web service is used for client recognition: for example, a caller can be recognized and sent to an agent instead of going through the queue. It is a way to use a client database to gain time and efficiency.<\/p>\n","protected":false},"author":3,"comment_status":"closed","ping_status":"closed","template":"","format":"standard","meta":{"footnotes":""},"ht-kb-category":[107],"ht-kb-tag":[147,131],"class_list":["post-1714","ht_kb","type-ht_kb","status-publish","format-standard","hentry","ht_kb_category-configuring","ht_kb_tag-admin","ht_kb_tag-maker"],"_links":{"self":[{"href":"https:\/\/help.ino.cx\/index.php\/wp-json\/wp\/v2\/ht-kb\/1714","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/help.ino.cx\/index.php\/wp-json\/wp\/v2\/ht-kb"}],"about":[{"href":"https:\/\/help.ino.cx\/index.php\/wp-json\/wp\/v2\/types\/ht_kb"}],"author":[{"embeddable":true,"href":"https:\/\/help.ino.cx\/index.php\/wp-json\/wp\/v2\/users\/3"}],"replies":[{"embeddable":true,"href":"https:\/\/help.ino.cx\/index.php\/wp-json\/wp\/v2\/comments?post=1714"}],"version-history":[{"count":13,"href":"https:\/\/help.ino.cx\/index.php\/wp-json\/wp\/v2\/ht-kb\/1714\/revisions"}],"predecessor-version":[{"id":4802,"href":"https:\/\/help.ino.cx\/index.php\/wp-json\/wp\/v2\/ht-kb\/1714\/revisions\/4802"}],"wp:attachment":[{"href":"https:\/\/help.ino.cx\/index.php\/wp-json\/wp\/v2\/media?parent=1714"}],"wp:term":[{"taxonomy":"ht_kb_category","embeddable":true,"href":"https:\/\/help.ino.cx\/index.php\/wp-json\/wp\/v2\/ht-kb-category?post=1714"},{"taxonomy":"ht_kb_tag","embeddable":true,"href":"https:\/\/help.ino.cx\/index.php\/wp-json\/wp\/v2\/ht-kb-tag?post=1714"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}