Introduction au développement de script d'alimentation de Carto-SI via API

Cette page liste succinctement les conventions et outils utilisés dans notre documentation.

Langage de programmation utilisé

Les exemples de code utilisent :

cURL, un outil permettant de faire des appels HTTP
python avec sa bibliothèque requests

Les fiches, types de fiche et champs

Les fiches représentent les unités de données principales avec lesquelles vous allez interagir. Chaque fiche appartient à un type spécifique, tel que application, task ou personal_account. Chaque type de fiche possède un ensemble défini de champs. Par exemple, les fiches de type application incluent généralement des champs comme label et icon.

Lorsque la documentation fait référence à une fiche, elle désigne le plus souvent une représentation JSON contenant les champs propres à une entité — qu’il s’agisse d’une application, d’une tâche, ou d’un compte utilisateur.

Exemple de fiche d'application :

Code

{
    "cartoVersion": "4.1.14",
    "icon": "far fa-credit-card",
    "id": "bccdaa31-a17e-6be7-0674-f3ff48b269ba",
    "it_departments": [
        "61bef09c-1066-8928-0f3e-d1bfa939d5ec"
    ],
    "label": "Application Banque de France",
    "maj_date": "2020-03-30T14:47:32+00:00",
    "meta_f27a58fb-79c1-28ba-1b68-6bb01cdd8332": [
        "Basse"
    ],
    "teamleader": "martin@carto-si.com"
}

Suivant la même logique, une liste de fiches sous-entend une liste JSON constituée de fiches comme la liste des applications ou la liste des tâches.

Documentation OpenAPI

Une documentation au format swagger est disponible sur https://app.carto-si.com/apidocs/.

Variables d'accès à Carto-SI

Vos scripts ont besoin de trois variables pour accéder aux API de Carto-SI :

HOST : contient l'URL d'accès à Carto-SI. Les exemples utilisent http://localhost:1080
TENANT : contient le nom de votre base de données.
TOKEN : contient la clé d'accès générée pour votre script.

La récupération de TENANT et TOKEN est expliquée dans Token d'accès à Carto-SI.

Tester un appel à Carto-SI

Le chemin /api/version qui donne le numéro de version est accessible de manière anonyme. C'est un bon point d'entrée pour vérifier que Carto-SI est bien lancée.

Test d'accès avec cURL :

Code

curl http://localhost:1080/api/version

La commande affiche :

Code

{
    "version": "4.8.26"
}

Test avec python :

Code

#! /usr/bin/env python3

# remplacez la valeur exemple ci-dessous par celle de votre host
HOST='http://localhost:1080'

#############################################################################
import requests
import sys

URLAPI=HOST+"/api/version"

rep = requests.get(URLAPI)
if rep.status_code != 200:
    print("Erreur %d : %s"%(rep.status_code, rep.text))
    sys.exit(1)

version = rep.json()["version"]
print("version: "+version)

Le script affiche :

Code

version: 4.8.26

Last modified on February 12, 2026