Documentation de l'API

Contexte de l'utilisation de l'API

Pour utiliser l'API, vous devez d'abord vous connecter ou créer un compte, et créer un schéma en configurant ses mappings. Après cela, vous pouvez alors partager votre schéma en fournissant un lien unique à vos contacts. Vous pouvez ajouter un paramètre d'URL à ce lien nommé redirect_uri égal à l'URL vers lequel l'utilisateur sera redirigé à la fin du processus.

Ils vont ainsi utiliser votre lien pour téléverser leur fichier Excel en associant les colonnes avec vos mappings prédéfinis. Si des erreurs de validation apparaissent dans leur fichier, ils devront les corriger. Après cela, ils pourront enregistrer leur modification, ce qui les redirigera vers l'URL que vous avez fournie dans le paramètre d'URL redirect_uri, avec un paramètre d'URL inséré nommé file_uuid, égal à l'identifiant du fichier importé.

Sur l'interface, vous aurez alors le résultat de chaque import dans la page de votre schéma. Pour chaque import, si le fichier ne contient plus d'erreur, vous pouvez accéder à son contenu en téléchargeant le fichier par exemple, ou en accédant aux mappings que l'utilisateur aura associé via un endpoint de l'API REST.

Clé API

Pour utiliser les différents endpoints de l'API, vous devez créer une clé d'API, et la fournir en tant que header X-API-Key à chaque requête. Sinon, vous aurez une erreur de type 404 ou 403.

Endpoint pour récupérer les mappings d'un fichier

L'endpoint de l'API REST pour récupérer des mappings est à la localisation GET /api/v1/file/<file_uuid>/mappings, avec <file_uuid> correspondant à l'identifiant du fichier dont vous voulez récupérer les mappings. Sur la page des mappings du fichier (voir le paragraphe précédent), pour plus de commodité, vous pouvez copier l'URL de cet endpoint avec l'ID du fichier.

Pour exécuter cette requête, vous devez fournir un header nommé X-API-Key correspondant à votre clé d'API. Vous recevrez alors un objet de type JSON qui aura cette forme :

{
    "uploader_username": "Nom d'utilisateur du propriétaire du fichier",
    "uploader_email": "Adresse mail de la personne qui a téléversé le fichier. Peut valoir null",
    "uploaded_at": "Date du téléchargement au format ISO-8601",
    // Statut de validation du fichier. Vaut true si vous l'avez validé, false sinon.
    "is_validated": false,
    "mappings": [
        // La feuille "Feuille 1" du fichier Excel
        "Feuille 1": {
            // La première colonne de la feuille "Feuille 1" du fichier Excel
            0: {
                "mapping_name": "Nom de votre mapping, ou du mapping par défaut utilisé",
                "mapping_type": "Nom du type de mapping utilisé",
                // Si le mapping associé est un mapping par défaut, ce flag vaut true.
                // Sinon, s'il s'agit d'un mapping que vous avez défini, ce flag vaut false.
                "is_default": false,
                // Les différentes valeurs associées à ce mapping dans le fichier à cette colonne
                "values": [...]
            }
        },
        "Feuille 2": { ... }
    ]
}

Endpoint pour télécharger un fichier

L'endpoint de l'API REST pour télécharger un fichier Excel est disponible à la localisation GET /api/v1/file/<file_uuid>/download. Comme pour les autres requêtes, vous devez fournir la clé API dans le header X-API-Key.