API d'analytique en lecture seule

L’API HTTP api.jonot.io/v1/* donne un accès en lecture seule aux données de tickets et de files de votre organisation. Authentifiez-vous avec un jeton porteur au lieu d’une connexion Admin. Utilisez l’API pour importer les données dans un entrepôt, un outil d’informatique décisionnelle ou un tableau de bord personnalisé.

Attention

L’API est disponible à partir de la formule Pro. L’onglet API tokens de la page Intégrations affiche une invite de mise à niveau sur Starter.

Obtenir un jeton

1. Ouvrez admin.jonot.io/settings/integrations.
2. Cliquez sur l’onglet API tokens.
3. Cliquez sur Create token, donnez-lui un nom (par ex. « Power BI »), et confirmez.
4. Copiez immédiatement le jeton. Il n’est affiché qu’une seule fois et ne peut pas être récupéré. Si vous le perdez, révoquez-le et créez-en un nouveau.

Les jetons ont le préfixe jot_ et n’expirent jamais d’eux-mêmes ; révoquez-les depuis le même onglet lorsqu’ils ne sont plus nécessaires.

Authentification

Danger

Envoyez le jeton uniquement dans l’en-tête Authorization. Ne le mettez jamais dans une chaîne de requête — les chaînes de requête finissent dans les journaux d’accès, les journaux de proxy, et l’historique du navigateur. Un jeton fourni via ?token=... est rejeté avec 401.

Authorization: Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Statut	Signification
401	Jeton manquant, malformé, inconnu, ou révoqué.
402	Jeton valide, mais l’organisation n’a pas la fonctionnalité API activée.
429	Limite de fréquence dépassée — voir Limites de fréquence ci-dessous.
400	Paramètres de requête invalides, ou plage de dates supérieure à 90 jours.

Points de terminaison

GET /v1/queues

Retourne les établissements et files d’attente de votre organisation, non filtrés et non paginés :

curl https://api.jonot.io/v1/queues \
  -H "Authorization: Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "locations": [
    {
      "id": "loc_…",
      "name": "Downtown",
      "slug": "downtown",
      "queues": [
        {
          "id": "q_…",
          "name": "Main Queue",
          "slug": "main-queue",
          "status": "ACTIVE"
        }
      ]
    }
  ]
}

Utilisez les valeurs id retournées pour filtrer /v1/tickets et l’export CSV par queueId / locationId.

GET /v1/tickets

Lecture paginée des tickets, limitée à votre organisation.

Paramètre	Requis	Répétable	Remarques
from	oui	non	ISO-8601, borne inférieure incluse sur createdAt.
to	oui	non	ISO-8601, borne supérieure exclue. Plage maximale de 90 jours.
queueId	non	oui	Répétez le paramètre pour filtrer plusieurs files d’attente.
locationId	non	oui	Répétez le paramètre pour filtrer plusieurs établissements.
status	non	oui	L’une de WAITING, CALLED, COMPLETED, CANCELED, SKIPPED, NO_SHOW.
cursor	non	non	Valeur opaque provenant du nextCursor de la page précédente.
limit	non	non	Par défaut 100, maximum 500.

curl "https://api.jonot.io/v1/tickets?from=2026-06-01T00:00:00Z&to=2026-06-08T00:00:00Z&status=COMPLETED" \
  -H "Authorization: Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "items": [
    {
      "id": "tkt_…",
      "number": 42,
      "queueId": "q_…",
      "locationId": "loc_…",
      "status": "COMPLETED",
      "createdAt": "2026-06-01T09:14:02.000Z",
      "calledAt": "2026-06-01T09:20:11.000Z",
      "completedAt": "2026-06-01T09:24:47.000Z",
      "cancelledAt": null,
      "skippedAt": null,
      "noShowAt": null,
      "calledByDeviceSessionId": "dev_…"
    }
  ],
  "nextCursor": "eyJjcmVhdGVkQXQi…"
}

Les lignes n’incluent jamais le hash porteur du ticket ni les données à caractère personnel saisies par le client, comme son nom, ses notes ou la taille du groupe. Elles contiennent uniquement les identifiants, le statut et les horodatages du cycle de vie.

Pagination : lorsque nextCursor n’est pas null, transmettez-le comme cursor dans la requête suivante. Conservez les mêmes valeurs from, to et les mêmes filtres. Un nextCursor égal à null indique que vous avez atteint la fin de la plage.

GET /v1/exports/tickets.csv

Ce point de terminaison accepte les mêmes filtres que /v1/tickets : from et to sont obligatoires, tandis que queueId, locationId et status peuvent être répétés. Il n’accepte ni cursor ni limit. Toute la plage correspondante est envoyée dans une seule réponse CSV : la limite de 500 lignes par page ne s’applique donc pas.

L’ordre des colonnes est stable, mais analysez les colonnes par nom d’en-tête plutôt que par position fixe. La ligne d’en-tête est toujours présente et correspond exactement à cette liste :

id,number,queueId,locationId,status,createdAt,calledAt,completedAt,cancelledAt,skippedAt,noShowAt,calledByDeviceSessionId

curl "https://api.jonot.io/v1/exports/tickets.csv?from=2026-06-01T00:00:00Z&to=2026-07-01T00:00:00Z" \
  -H "Authorization: Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -o tickets.csv

La réponse utilise Transfer-Encoding: chunked. Un export de 90 jours contenant 100 000 lignes ne doit donc pas être conservé en mémoire d’un côté ou de l’autre. Envoyez-le directement vers un fichier ou un analyseur.

Plafond de plage de 90 jours

Chaque point de terminaison qui accepte from et to rejette avec 400 une plage supérieure à 90 jours. Pour obtenir un historique plus long, demandez des plages plus courtes, par exemple une semaine par requête. Utilisez les horodatages comme calledAt et completedAt pour calculer les temps d’attente et de service sans demander deux fois les mêmes lignes.

Limites de fréquence

Chaque jeton autorise 60 requêtes par minute. La limite s’applique au jeton, pas à l’adresse IP. Chaque réponse comprend :

X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1751328000000

Un 429 porte en plus Retry-After (secondes). Patientez et réessayez après cette fenêtre ; une synchronisation planifiée toutes les quelques minutes reste confortablement sous la limite.

Organisations de démonstration

Une organisation de démonstration possède une limite supplémentaire de 50 requêtes par jour. La limite par minute s’applique aussi. Vous pouvez utiliser l’API de démonstration pour tester toute une intégration en répertoriant les files, en demandant des tickets et en créant un export CSV. La limite quotidienne ne suffit pas à une utilisation en production. Si vous la dépassez, l’API renvoie 429 avec un corps qui en précise la cause :

{
  "error": "demo_quota_exceeded",
  "limit": 50,
  "resetAt": "2026-01-02T09:00:00.000Z"
}

Les exports CSV de démonstration sont eux aussi marqués, afin qu’un fichier exporté ne puisse pas être confondu avec des données de production : le nom de fichier est préfixé par demo-, la réponse porte l’en-tête X-Jonot-Demo: 1, et une colonne demo supplémentaire est ajoutée en fin de CSV. Les exports payants restent inchangés — pas de colonne ni d’en-tête supplémentaire. Souscrire à une offre payante lève le quota quotidien et supprime ces marquages.

Python + pandas

import requests
import pandas as pd

TOKEN = "jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
BASE = "https://api.jonot.io/v1"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

def fetch_tickets(frm: str, to: str) -> pd.DataFrame:
    rows = []
    cursor = None
    while True:
        params = {"from": frm, "to": to, "limit": 500}
        if cursor:
            params["cursor"] = cursor
        res = requests.get(f"{BASE}/tickets", headers=HEADERS, params=params, timeout=30)
        res.raise_for_status()
        body = res.json()
        rows.extend(body["items"])
        cursor = body["nextCursor"]
        if not cursor:
            break
    return pd.DataFrame(rows)

df = fetch_tickets("2026-06-01T00:00:00Z", "2026-07-01T00:00:00Z")
df["waitSeconds"] = (
    pd.to_datetime(df["calledAt"]) - pd.to_datetime(df["createdAt"])
).dt.total_seconds()
print(df.groupby("queueId")["waitSeconds"].mean())

Ou lisez directement l’export CSV — pandas gère la réponse diffusée de manière transparente :

df = pd.read_csv(
    f"{BASE}/exports/tickets.csv?from=2026-06-01T00:00:00Z&to=2026-07-01T00:00:00Z",
    storage_options={"Authorization": f"Bearer {TOKEN}"},
)

Power BI (connecteur Web)

1. Dans Power BI Desktop : Get Data → Web.
2. Choisissez Advanced, et construisez l’URL avec votre plage de dates, par ex. https://api.jonot.io/v1/exports/tickets.csv?from=2026-06-01T00:00:00Z&to=2026-07-01T00:00:00Z.
3. Sous HTTP request header parameters, ajoutez un en-tête nommé Authorization avec la valeur Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.
4. Cliquez sur OK — Power BI détecte le CSV et ouvre l’aperçu du tableau.
5. Cliquez sur Load (ou Transform Data d’abord si vous voulez définir les types de colonnes — createdAt/calledAt/etc. s’importent en texte ; convertissez-les en Date/Time dans Power Query).
6. Configurez une actualisation planifiée dans le service Power BI si vous récupérez les données à intervalles réguliers ; gardez la plage confortablement sous 90 jours par actualisation.

Astuce

Le magasin d’identifiants de Power BI garde l’en-tête Authorization hors de la chaîne de requête et hors du code M visible du fichier .pbix enregistré, c’est donc la méthode recommandée pour s’authentifier depuis Power BI — n’intégrez jamais le jeton dans l’URL elle-même.