# Call API

L'action **Call API** permet d'envoyer une requête HTTP à une API et de récupérer les données retournées.

### ⚙️ Paramétrer l'action

Pour utiliser cette action, vous devez :

1️⃣ Sélectionner une méthode de requête HTTP parmi (GET / POST / PATCH / PUT / DELETE)

<figure><img src="https://2063331370-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQBQ-Fk5qKATOA2R2_R%2Fuploads%2FmpH3NBHXNXsdHIvIFs69%2FCapture%20d%E2%80%99e%CC%81cran%202023-03-16%20a%CC%80%2011.23.57.png?alt=media&#x26;token=bb06d968-132f-4382-bf5a-3ed9a7a6a8f4" alt="" width="375"><figcaption><p>Paramétrage de l'action call API</p></figcaption></figure>

2️⃣ Écrire l'URL de l'API à laquelle vous souhaitez envoyer la requête. Vous pouvez utiliser des variables dans cet URL.

3️⃣ Paramétrer les **Headers** de votre requête, notamment pour transmettre des informations supplémentaires au serveur ou pour authentifier votre requête.

4️⃣ Paramétrer les [**Query String**](https://en.wikipedia.org/wiki/Query_string), pour ajouter des données à la requête. Souvent utile pour transmettre des données dans des requêtes de type GET.

5️⃣ Paramétrer les **Fields**, pour ajouter des données à la requêt&#x65;**.** Les Fields représentent le **body** d'une requête HTTP et sont disponibles pour les requêtes GET, POST, PATCH et PUT. Le Body est transmis au format JSON. Pour paramétrer les **Fields**, vous devez choisir le type de données utilisées parmi String, Number et JSON. 👉🏼 [Choisir le type de donnée des Fields](#choisir-le-type-de-donnee-des-fields).

6️⃣ Tester la requête, vous pouvez alors utiliser le schéma fourni par votre test. Le schéma nous permet de déterminer le type de données renvoyé par le Call API ainsi que les variables qui pourront être utilisées par la suite. Par exemple si vous voulez afficher le résultat de votre requête dans un texte avec variable. Le schéma reste modifiable après le test.&#x20;

### Zoom sur le test de requête

Voici la liste des types de données du Call API :&#x20;

* Les types de retour classique : **Text**, **Number** et **Booléen.**
* **Fichier :** retourne un fichier dont le nom et l'extension ont été paramétrés soit par le test de requête soit manuellement. Il est possible de variabiliser le nom du fichier.
  * Vous pouvez choisir le mode de conversion du fichier, base 64 ou binaire
* **\[ ] Array :** retourne une liste d'éléments. Le type des éléments peut être : Text, Number, Booléen, Array ou Collection.
* **{ } Collection :** retourne une collection d'élément avec une clé et un type. Le type des éléments peut être : Text, Number, Booléen, Fichier, Array ou Collection.

Lors du test de la requête, il faut remplacer les variables Ksaar par des valeurs de test afin que le call API renvoie le bon format de données. Ce format pourra ensuite être réutilisé dans Ksaar. De plus, les données de test associée à une clé du corps sont gardées en mémoire tant que le nom de la clé n'est pas changé.

Lors du test de la requête avec un fichier de source "valeur personnalisée", le champ est auto-rempli par le ficher choisi. Pour tester la requête avec un autre fichier, il suffit de le changer directement dans le paramétrage de la requête.

<figure><img src="https://2063331370-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQBQ-Fk5qKATOA2R2_R%2Fuploads%2FERPQGrzm77ZZkul1vZn8%2Fezgif-773d5ea3b5188d.gif?alt=media&#x26;token=8c128804-370a-418c-806b-12b2eb6ee7f5" alt="" width="563"><figcaption><p>Exemple de test fonctionnel d'une API</p></figcaption></figure>

{% hint style="info" %}
Les données d'une requête test sont conservées afin de ne pas les saisir à chaque fois. Il est aussi possible de les réinitialiser vers les valeurs par défaut si besoin
{% endhint %}

## 🤔 Choix du mode de saisie du corps de la requête

Il est possible de choisir la façon dont vous renseignez les données dans le corps d'une requête :&#x20;

* par Clé / Valeurs
* par JSON brut

### 🔤 Éditeur Clé / Valeurs

Dans ce mode d'édition, Ksaar construit le JSON transmis dans la requête. Ainsi, il suffit de rentrer les clés et leurs valeurs correspondantes (du type adéquat) et la requête sera correctement formatée par Ksaar lors du call API.

Les **Fields** permettent d'ajouter des données à la requête HTTP. Ils représentent le **body** d'une requête et sont disponibles pour les requêtes GET, POST, PATCH et PUT.\
Pour paramétrer les **Fields**, vous devez choisir le type de données utilisées parmi String, Number et JSON.

#### Données de type String

Pour les données de type **string**, vous pouvez inclure la valeur sous forme de chaîne de caractères. Par exemple, si vous avez un champ "Nom" de type string, vous pouvez inclure la valeur du nom en tant que chaîne de caractères dans les Fields de la requête.

#### Données de type Number

Pour les données de type **number**, vous pouvez inclure la valeur en tant que nombre. Assurez-vous que la valeur que vous fournissez est numérique. Si la valeur fournie n'est pas un nombre, elle sera interprétée comme nulle (null) dans la requête.

#### Données de type JSON

Pour les données de type **JSON**, vous pouvez associer des objets JSON dans les valeurs à des clés classiques. Assurez-vous néanmoins de respecter un syntaxe JSON valide. Cela inclut l'utilisation de guillemets autour des noms de clés et des valeurs, ainsi que la séparation des paires clé-valeur par des virgules.

Vous pouvez inclure des variables en remplaçant les valeurs attendues par les variables correspondantes, en les plaçant entre des guillemets. Cela vous permet de dynamiquement utiliser des valeurs provenant de Ksaar dans vos requêtes.

<figure><img src="https://2063331370-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQBQ-Fk5qKATOA2R2_R%2Fuploads%2FwhWeKewVlwqm4gZw14Ne%2FEnregistrement%20de%20l%E2%80%99e%CC%81cran%202025-05-28%20a%CC%80%2010.42.29.gif?alt=media&#x26;token=615ad1fe-900c-4bb0-adb4-62ef73e8d262" alt=""><figcaption><p>Ajouter des variables à de la donnée JSON</p></figcaption></figure>

{% hint style="danger" %}
L'option JSON clé / valeurs est différente de l'éditeur JSON pur :&#x20;

* Le field clés / valeurs JSON permet de renseigner du JSON dans la valeur associée à une clé.&#x20;
* L'éditeur JSON sert à renseigner le JSON incluant directement les clés et les valeurs en un.
{% endhint %}

#### Données de type fichier

Vous pouvez inclure des données de type **fichier** dans un call API, le fichier sera envoyé au **format base 64**. La conversion se fait directement dans l'action donc aucune autre action n'est requise.

Il est possible d'inclure un fichier depuis trois sources différentes :&#x20;

* Un champ
* Un document rempli
* Une valeur personnalisée

La limite est de 7 Mo pour la taille totale des fichiers dans l’action, il n’y a pas de limite sur leur quantité.

<details>

<summary>Paramétrage d'un call API POST avec un fichier</summary>

<figure><img src="https://2063331370-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQBQ-Fk5qKATOA2R2_R%2Fuploads%2F4Ac9gAD95Tdz4C7KFHUj%2FCapture%20d%E2%80%99e%CC%81cran%202025-07-10%20a%CC%80%2016.23.50.png?alt=media&#x26;token=fdf38502-d983-4dea-b3e6-f8563cc9baa3" alt="" width="311"><figcaption><p>Illustration du paramétrage d'un GET avec un fichier</p></figcaption></figure>

{% code title="Représentation du schéma utilisé pour envoyer le fichier" %}
```json
{
  "mon_texte": "test",
  "mon_fichier": "le string du fichier en base 64"
}
```
{% endcode %}

</details>

<details>

<summary>Paramétrage d'un call API POST avec plusieurs fichiers</summary>

<figure><img src="https://2063331370-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQBQ-Fk5qKATOA2R2_R%2Fuploads%2F6NGg8ImrggJMtFnoHbEK%2FCapture%20d%E2%80%99e%CC%81cran%202025-07-10%20a%CC%80%2016.30.27.png?alt=media&#x26;token=dea21886-5d48-4eda-ad1b-aafebdc75bd8" alt="" width="467"><figcaption><p>Illustration du paramétrage d'un GET avec plusieurs fichiers</p></figcaption></figure>

{% code title="Représentation du schéma utilisé pour envoyer le fichier" %}
```json
{
  "mon_texte": "test",
  "mon_fichier": ["le string du fichier 1 en base 64", "le string du fichier 2 en base 64"]
}
```
{% endcode %}

</details>

{% hint style="info" %}
Il est aussi possible de récupérer des fichiers via la méthode GET : [#exemple-get-recuperer-un-fichier-base-64-ou-binaire-depuis-une-api-externe](#exemple-get-recuperer-un-fichier-base-64-ou-binaire-depuis-une-api-externe "mention")
{% endhint %}

### 💾 Éditeur JSON pur

Le type de donnée JSON permet de transmettre des formats de données plus complexes comme des array par exemple. Il permet donc d'avoir le contrôle total sur ce qui est envoyé, tout en ayant la possibilité d'intégrer des variables Ksaar.

Le contenu renseigné dans l'éditeur JSON sera transmis tel quel dans la requête API. Ainsi, vous devez vous assurer de l'exactitude du format de la donnée.

Comme mentionné précédemment, il faut utiliser ce mode de saisie lorsque vous souhaitez construire vous-même le corps de la requête. Le cas d'usage typique est l'utilisation de composants plus complexes qu'il est impossible de faire avec le field clé / valeurs.&#x20;

<figure><img src="https://2063331370-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQBQ-Fk5qKATOA2R2_R%2Fuploads%2F098ACzWDn59W8zhqvLdl%2FEnregistrement%20de%20l%E2%80%99e%CC%81cran%202025-05-28%20a%CC%80%2010.57.32.gif?alt=media&#x26;token=0ea4f733-7b41-4fb2-8b21-a7cfe2168fc9" alt=""><figcaption><p>Saisie du corps de la requête via JSON</p></figcaption></figure>

## 📌 Exemples de call API

#### Exemple GET : récupérer des données depuis une API externe - Rechercher des communes par code postal :

{% embed url="https://www.youtube.com/watch?ab_channel=KSAAR&v=Fnhg86CKUnw" %}
Vidéo tutoriel sur YouTube : Action API call avec GET
{% endembed %}

#### Exemple GET : Paramétrer le schéma de retour d'une récupération de fichier (base 64 ou binaire) depuis une API externe

En réception, il est uniquement possible de recevoir un fichier seul. Ce fichier doit être fourni tel quel et non au sein d'une collection JSON.

<figure><img src="https://2063331370-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQBQ-Fk5qKATOA2R2_R%2Fuploads%2Fpm2FuSyey8k77SfGwkKq%2FEnregistrementdelecran2025-07-23a14.49.39-ezgif.com-video-to-gif-converter.gif?alt=media&#x26;token=d3bc670c-6f91-4d58-be95-1f4268e3f9ba" alt=""><figcaption></figcaption></figure>

{% hint style="success" %}
Un fichier encodé en base 64 est un chaîne de caractères, il est donc impossible pour Ksaar de discerner la différence entre un élément texte et un fichier encodé en base 64.

Lors de la détection automatique du format de retour du test de la requête, veillez donc à adapter le retour de fichier selon votre besoin.&#x20;
{% endhint %}

#### Exemple POST : Envoyer des données à une API ou un webhook - récupérer les réponses d'un formulaire sur un Google Sheet grâce à Make :&#x20;

{% embed url="https://www.youtube.com/watch?ab_channel=KSAAR&v=pOVG76Kvhxw" %}
Vidéo tutoriel sur YouTube : Action API call avec POST
{% endembed %}
