API Αναλυτικών Στοιχείων μόνο για ανάγνωση

Το HTTP API api.jonot.io/v1/* παρέχει πρόσβαση μόνο για ανάγνωση στα δεδομένα εισιτηρίων και ουρών του οργανισμού σας. Δεν χρειάζεται σύνδεση admin, αλλά μόνο bearer token. Χρησιμοποιήστε το για να αντλήσετε δεδομένα σε αποθήκη δεδομένων, εργαλείο BI ή προσαρμοσμένο πίνακα ελέγχου.

Προσοχή

Το API είναι διαθέσιμο στο πρόγραμμα Pro και πάνω. Η καρτέλα tokens API στη σελίδα Ενσωματώσεις εμφανίζει μια προτροπή αναβάθμισης στο Starter.

Λήψη ενός token

1. Ανοίξτε το admin.jonot.io/settings/integrations.
2. Κάντε κλικ στην καρτέλα Tokens API.
3. Κάντε κλικ στο Δημιουργία token, δώστε του ένα όνομα (π.χ. “Power BI”), και επιβεβαιώστε.
4. Αντιγράψτε το token αμέσως — εμφανίζεται μία φορά και δεν μπορεί να ανακτηθεί. Αν το χάσετε, ανακαλέστε το και δημιουργήστε ένα νέο.

Τα tokens έχουν πρόθεμα jot_ και δεν λήγουν ποτέ από μόνα τους· ανακαλέστε τα από την ίδια καρτέλα όταν δεν χρειάζονται πλέον.

Πιστοποίηση

Κίνδυνος

Στείλτε το token μόνο στην κεφαλίδα Authorization. Ποτέ μην το βάζετε σε συμβολοσειρά ερωτήματος — οι συμβολοσειρές ερωτήματος καταλήγουν σε αρχεία καταγραφής πρόσβασης, αρχεία καταγραφής διαμεσολαβητή, και ιστορικό browser. Ένα token που παρέχεται μέσω ?token=... απορρίπτεται με 401.

Authorization: Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Κατάσταση	Σημασία
401	Λείπει, κακοσχηματισμένο, άγνωστο, ή ανακληθέν token.
402	Έγκυρο token, αλλά ο οργανισμός δεν έχει ενεργοποιημένη τη δυνατότητα API.
429	Το όριο ρυθμού ξεπεράστηκε — δείτε Όρια ρυθμού παρακάτω.
400	Άκυρες παράμετροι ερωτήματος, ή εύρος ημερομηνιών πάνω από 90 ημέρες.

Τελικά σημεία

GET /v1/queues

Επιστρέφει τις τοποθεσίες και ουρές του οργανισμού σας, χωρίς φίλτρα και χωρίς σελιδοποίηση:

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"
        }
      ]
    }
  ]
}

Χρησιμοποιήστε τις επιστρεφόμενες τιμές id για να φιλτράρετε το /v1/tickets και την εξαγωγή CSV κατά queueId / locationId.

GET /v1/tickets

Επιστρέφει τα εισιτήρια του οργανισμού σας σε σελίδες.

Παράμετρος	Υποχρεωτική	Επαναλαμβανόμενη	Σημειώσεις
from	ναι	όχι	ISO-8601, κατώτατο συμπεριλαμβανόμενο όριο στο createdAt.
to	ναι	όχι	ISO-8601, αποκλειστικό άνω όριο. Μέγιστο εύρος 90 ημερών.
queueId	όχι	ναι	Επαναλάβετε την παράμετρο για να φιλτράρετε πολλαπλές ουρές.
locationId	όχι	ναι	Επαναλάβετε την παράμετρο για να φιλτράρετε πολλαπλές τοποθεσίες.
status	όχι	ναι	Μία από WAITING, CALLED, COMPLETED, CANCELED, SKIPPED, NO_SHOW.
cursor	όχι	όχι	Αδιαφανής τιμή από το nextCursor της προηγούμενης σελίδας.
limit	όχι	όχι	Προεπιλογή 100, μέγιστο 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…"
}

Οι γραμμές δεν περιλαμβάνουν ποτέ το bearer hash του εισιτηρίου ούτε προσωπικά δεδομένα που καταχώρισε ο πελάτης, όπως όνομα, σημειώσεις ή μέγεθος παρέας. Περιλαμβάνουν μόνο ids, κατάσταση και χρονοσφραγίδες του κύκλου ζωής.

Σελιδοποίηση: όταν το nextCursor δεν είναι null, περάστε το ως cursor στο επόμενο αίτημα με τα ίδια φίλτρα from/to. Ένα null nextCursor σημαίνει ότι φτάσατε στο τέλος του εύρους.

GET /v1/exports/tickets.csv

Χρησιμοποιεί τα ίδια φίλτρα με το /v1/tickets (from/to υποχρεωτικά, queueId/locationId/status επαναλαμβανόμενα), χωρίς cursor/limit. Μεταδίδει όλες τις εγγραφές που ταιριάζουν ως μία απόκριση CSV, χωρίς το όριο 500 γραμμών ανά σελίδα.

Η σειρά στηλών είναι σταθερή, αλλά αναλύστε τις στήλες με το όνομα κεφαλίδας και όχι τη σταθερή θέση. Η γραμμή κεφαλίδας είναι πάντα παρούσα και ταιριάζει ακριβώς με αυτή τη λίστα:

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

Η απόκριση μεταδίδεται (Transfer-Encoding: chunked), ώστε μια εξαγωγή 90 ημερών με 100.000 γραμμές να μην αποθηκεύεται ολόκληρη στη μνήμη. Γράψτε τη ροή απευθείας σε αρχείο ή αναλυτή.

Ανώτατο όριο εύρους 90 ημερών

Κάθε τελικό σημείο που δέχεται from/to απορρίπτει εύρος μεγαλύτερο από 90 ημέρες με 400. Αν χρειάζεστε μεγαλύτερο ιστορικό, αντλήστε τα δεδομένα σε μικρότερα διαστήματα, για παράδειγμα μία εβδομάδα ανά αίτημα. Οι χρονοσφραγίδες του εισιτηρίου (calledAt, completedAt, …) σάς επιτρέπουν να υπολογίσετε τους χρόνους αναμονής και εξυπηρέτησης χωρίς να ανακτήσετε τις ίδιες γραμμές δύο φορές.

Όρια ρυθμού

Το όριο είναι 60 αιτήματα ανά λεπτό και ανά token, όχι ανά διεύθυνση IP. Κάθε απόκριση περιλαμβάνει:

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

Μια απόκριση 429 περιλαμβάνει επίσης Retry-After σε δευτερόλεπτα. Περιμένετε αυτό το διάστημα πριν δοκιμάσετε ξανά. Ένας προγραμματισμένος συγχρονισμός κάθε λίγα λεπτά παραμένει κάτω από το όριο.

Οργανισμοί επίδειξης

Ένας οργανισμός επίδειξης έχει το ίδιο API, με επιπλέον 50 αιτήματα την ημέρα πάνω από το όριο ρυθμού ανά λεπτό. Αυτό αρκεί για να δοκιμάσετε μια ολοκλήρωση από άκρη σε άκρη — να παραθέσετε τις ουρές σας, να αντλήσετε μερικά εισιτήρια, να κάνετε μία εξαγωγή CSV — και σκόπιμα δεν αρκεί για να τη λειτουργήσετε σε παραγωγή. Η υπέρβασή του επιστρέφει ένα 429 του οποίου το σώμα προσδιορίζει την αιτία, αντί για τη συνήθη απλή απόκριση ορίου ρυθμού:

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

Οι εξαγωγές CSV από επιδείξεις επισημαίνονται επίσης, ώστε ένα εξαγόμενο αρχείο να μην μπορεί να μπερδευτεί με παραγωγικά δεδομένα: το όνομα αρχείου έχει πρόθεμα demo-, η απόκριση φέρει X-Jonot-Demo: 1, και μια τελική στήλη demo προστίθεται στο CSV. Οι πληρωμένες εξαγωγές παραμένουν αμετάβλητες — καμία επιπλέον στήλη, καμία επιπλέον κεφαλίδα. Η εγγραφή σε πρόγραμμα επί πληρωμή αίρει το ημερήσιο όριο και αφαιρεί τις επισημάνσεις.

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())

Ή διαβάστε απευθείας την εξαγωγή CSV — το pandas χειρίζεται την μεταδιδόμενη απόκριση διαφανώς:

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 (Web connector)

1. Στο Power BI Desktop: Get Data → Web.
2. Επιλέξτε Advanced, και δημιουργήστε τη διεύθυνση URL με το εύρος ημερομηνιών σας, π.χ. https://api.jonot.io/v1/exports/tickets.csv?from=2026-06-01T00:00:00Z&to=2026-07-01T00:00:00Z.
3. Στο HTTP request header parameters, προσθέστε μια κεφαλίδα με όνομα Authorization με τιμή Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.
4. Κάντε κλικ στο OK — το Power BI εντοπίζει το CSV και ανοίγει το Table Preview.
5. Κάντε κλικ στο Load (ή Transform Data πρώτα αν θέλετε να ορίσετε τύπους στηλών — τα createdAt/calledAt/κ.λπ. εισάγονται ως κείμενο· μετατρέψτε τα σε Date/Time στο Power Query).
6. Ορίστε προγραμματισμένη ανανέωση στην υπηρεσία Power BI αν αντλείτε σε τακτική βάση· διατηρήστε το εύρος άνετα κάτω από 90 ημέρες ανά ανανέωση.

Συμβουλή

Το αποθηκευτικό μέσο διαπιστευτηρίων του Power BI κρατά την κεφαλίδα Authorization έξω από τη συμβολοσειρά ερωτήματος και έξω από τον ορατό κώδικα M του αποθηκευμένου αρχείου .pbix, οπότε αυτός είναι ο συστημένος τρόπος πιστοποίησης από το Power BI — ποτέ μην ενσωματώνετε το token απευθείας στη διεύθυνση URL.