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χιλ. γραμμών να μη χρειάζεται buffering στη μνήμη σε καμία πλευρά — προωθήστε την απευθείας σε ένα αρχείο ή έναν αναλυτή.

Όριο εύρους 90 ημερών

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

Όρια ρυθμού

60 αιτήματα/λεπτό ανά token (όχι ανά IP — ο προϋπολογισμός ταξιδεύει με το token). Κάθε απόκριση φέρει:

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

Ένα 429 επιπρόσθετα φέρει Retry-After (δευτερόλεπτα). Κάντε πίσω και ξαναδοκιμάστε μετά από αυτό το παράθυρο· ένας προγραμματισμένος συγχρονισμός κάθε λίγα λεπτά παραμένει άνετα κάτω από το όριο.

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.