Συνεδρίες Device User

Ενημερώστε το Nomid για το ποιος χρησιμοποιεί ποια συσκευή όταν η δική σας εφαρμογή συνδέει τους χρήστες της και διαβάστε κάθε συνεδρία Device User.

Πώς λειτουργεί

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

Η πρώτη σύνδεση ενός externalUserId δημιουργεί έναν Device User με auth EXTERNAL για αυτόν. Μεταγενέστερες συνδέσεις του ίδιου externalUserId επαναχρησιμοποιούν αυτόν τον χρήστη, και ένα userName που διαφέρει από το τρέχον όνομά του τον μετονομάζει. Μπορείτε επίσης να αναφέρετε τη σύνδεση ενός υπάρχοντος Device User οποιουδήποτε auth μέσω του deviceUserId του.

Το GET /device-user-logins επιστρέφει τις συνεδρίες Device User της εταιρείας, με τις νεότερες πρώτα: εκείνες που αναφέρει το σύστημά σας και τις συνδέσεις με PIN και SSO που αναφέρει ο Nomid agent από τη συσκευή. Τα loginSource και logoutSource δηλώνουν ποιος ανέφερε κάθε μισό μιας συνεδρίας.

Μια συνεδρία που αναφέρεται μέσω του API δεν έχει λήξη στο Nomid: παραμένει ανοιχτή μέχρι να αναφέρετε την αποσύνδεσή της. Κάθε κλήση σύνδεσης καταγράφει μια νέα συνεδρία, ακόμη και όταν ο ίδιος χρήστης είναι ήδη συνδεδεμένος σε αυτήν τη συσκευή.

Το API κλείνει μόνο συνεδρίες που αναφέρθηκαν μέσω του API. Μια σύνδεση με PIN ή SSO στον Nomid agent κλείνει από τη συσκευή.

Απαιτήσεις

Το GET /device-user-logins απαιτεί το DEVICES_READ, όπως και οι υπόλοιπες αναγνώσεις συσκευών.
Η αναφορά συνδέσεων και αποσυνδέσεων Device User (POST /device-user-logins και POST /device-user-logins/logout) απαιτεί το DEVICES_COMMAND, το δικαίωμα που στέλνει εντολές σε συσκευές· ένα κλειδί το αποκτά μόνο μαζί με το DEVICES_READ. Οι συνεδρίες Device User δεν έχουν δικό τους δικαίωμα.
Για να αναφέρετε μια σύνδεση, το asset πρέπει να διαθέτει μια διαχειριζόμενη συσκευή, δηλαδή μια συσκευή εγγεγραμμένη στο Nomid αυτήν τη στιγμή.
Το επικυρωμένο κλειδί επιλέγει την εταιρεία· τα αιτήματα δεν έχουν παράμετρο tenant ή εταιρείας. Τα τελικά σημεία σύνδεσης και αποσύνδεσης μπορούν να απευθυνθούν σε κάθε asset της εταιρείας.

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

Οι διαδρομές είναι σχετικές με τη βασική διεύθυνση URL του API και απαιτούν την κεφαλίδα X-API-Key.

https://api.nomid.tech/emm/api/v1

Μέθοδος	Endpoint	Δικαίωμα	Περιγραφή
GET	/device-user-logins	DEVICES_READ	Προβολή λίστας συνεδριών Device User, με τις νεότερες πρώτα, με προαιρετικά φίλτρα
POST	/device-user-logins	DEVICES_COMMAND	Αναφορά ότι ένας χρήστης του οποίου την ταυτότητα επαλήθευσε το σύστημά σας συνδέθηκε σε μια συσκευή· επιστρέφει 201 με τη συνεδρία
POST	/device-user-logins/logout	DEVICES_COMMAND	Αναφορά αποσύνδεσης, βάσει loginId ή βάσει συσκευής και χρήστη· επιστρέφει τις σχετικές συνεδρίες

Λίστα συνεδριών

Κάθε παράμετρος ερωτήματος είναι προαιρετική. Χωρίς φίλτρα, το τελικό σημείο επιστρέφει τις πιο πρόσφατες συνεδρίες της εταιρείας.

Παράμετρος	Περιγραφή
assetId	Μόνο συνεδρίες σε αυτό το στοιχείο εξοπλισμού. Όχι μαζί με το serialNumber.
serialNumber	Μόνο συνεδρίες στο στοιχείο εξοπλισμού με αυτόν τον σειριακό αριθμό. Όχι μαζί με το assetId.
deviceUserId	Μόνο συνεδρίες του Device User με αυτό το αναγνωριστικό Nomid, deviceUser.id σε μια συνεδρία.
externalUserId	Μόνο συνεδρίες του EXTERNAL Device User με αυτό το αναγνωριστικό από το σύστημά σας.
open	Το true επιστρέφει μόνο τις συνεδρίες που είναι ακόμα ανοιχτές: δεν έχουν αποσυνδεθεί και δεν έχουν λήξει. Η προεπιλογή είναι false, το οποίο επιστρέφει ανοιχτές και κλειστές συνεδρίες.
from	Μόνο συνεδρίες που ξεκίνησαν σε αυτήν ή μετά από αυτήν τη χρονική στιγμή ISO-8601, όπως 2026-10-01T00:00:00Z.
to	Μόνο συνεδρίες που ξεκίνησαν πριν από αυτήν τη χρονική στιγμή ISO-8601. Το from πρέπει να είναι προγενέστερο του to, και τα δύο πρέπει να βρίσκονται μεταξύ του 1970 και του 9999.
limit	Μέγιστος αριθμός συνεδριών προς επιστροφή. Προεπιλογή σε 50· μια τιμή πάνω από 200 επιστρέφει 200.

Οι συνεδρίες ενός στοιχείου εξοπλισμού περιλαμβάνουν εκείνες που καταγράφηκαν σε προηγούμενες εγγραφές του ίδιου υλικού, με τον ίδιο σειριακό αριθμό, ώστε μια επανεγγεγραμμένη συσκευή να διατηρεί το ιστορικό της. Ένα άγνωστο στοιχείο εξοπλισμού επιστρέφει 404 με κωδικό asset_not_found· ένα άγνωστο deviceUserId ή externalUserId δεν αντιστοιχεί σε καμία συνεδρία και επιστρέφει μια κενή λίστα.

Στείλτε ένα πεδίο συσκευής και ένα πεδίο χρήστη. Η αποστολή και των δύο ή κανενός από ένα ζεύγος επιστρέφει 400.

Πεδίο	Μέγιστο μήκος	Περιγραφή
serialNumber	255	Ο σειριακός αριθμός της συσκευής. Είτε αυτό είτε το assetId.
assetId	255	Το αναγνωριστικό του στοιχείου εξοπλισμού. Είτε αυτό είτε το serialNumber.
externalUserId	100	Το δικό σας αναγνωριστικό για τον χρήστη. Η πρώτη του σύνδεση δημιουργεί έναν Device User με έλεγχο ταυτότητας EXTERNAL· οι μεταγενέστερες συνδέσεις το επαναχρησιμοποιούν. Τα αρχικά και τελικά κενά διαστήματα αφαιρούνται και οι χαρακτήρες ελέγχου απορρίπτονται. Είτε αυτό είτε το deviceUserId.
deviceUserId	36	Το αναγνωριστικό ενός υπάρχοντος Nomid Device User. Είτε αυτό είτε το externalUserId.
userName	50	Προαιρετικό όνομα εμφάνισης, χρησιμοποιείται μόνο με το externalUserId. Ένας νέος χρήστης EXTERNAL το λαμβάνει, ή το externalUserId του περικομμένο σε 50 χαρακτήρες όταν απουσιάζει. Μια μεταγενέστερη σύνδεση με διαφορετικό userName μετονομάζει τον χρήστη.

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

Αναφορά αποσύνδεσης

Στείλτε είτε το loginId είτε ένα πεδίο συσκευής και ένα πεδίο χρήστη για να κλείσετε κάθε ανοιχτή συνεδρία που άνοιξε το API για αυτόν τον χρήστη σε αυτήν τη συσκευή, συμπεριλαμβανομένων των προηγούμενων εγγραφών του ίδιου υλικού.

Πεδίο	Μέγιστο μήκος	Περιγραφή
loginId	36	Η απόδειξη που επέστρεψε η σύνδεση. Ένα πεδίο συσκευής ή χρήστη που αποστέλλεται μαζί της πρέπει να ανήκει στην ίδια τη συνεδρία, διαφορετικά το αίτημα επιστρέφει 409.
serialNumber	255	Ο σειριακός αριθμός της συσκευής. Όχι μαζί με το assetId.
assetId	255	Το id του asset. Όχι μαζί με το serialNumber.
externalUserId	100	Το δικό σας id για τον χρήστη. Όχι μαζί με το deviceUserId.
deviceUserId	36	Το Nomid id του Device User. Όχι μαζί με το externalUserId.

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

Πεδία συνεδρίας

Κάθε τελικό σημείο επιστρέφει συνεδρίες με αυτά τα πεδία. Ένα πεδίο χωρίς τιμή παραλείπεται· το open είναι πάντα παρόν. Οι ώρες είναι χρονικές στιγμές κατά ISO-8601 σε UTC.

Πεδίο	Περιγραφή
loginId	Το id της συνεδρίας, η απόδειξη που την αποσυνδέει.
deviceUser	Ποιος συνδέθηκε: id (το Nomid id), name, auth (PIN, SSO ή EXTERNAL) και, για έναν χρήστη EXTERNAL, externalUserId.
asset	Πού: assetId, serialNumber και name. Παραλείπεται μόνο όταν η συσκευή δεν ανήκει πλέον σε κανένα asset.
loginAt	Πότε συνδέθηκε ο χρήστης. Παραλείπεται μόνο για αποσύνδεση που ανέφερε η συσκευή χωρίς σύνδεση.
logoutAt	Πότε έληξε η συνεδρία. Παραλείπεται ενόσω είναι ανοιχτή.
expiresAt	Πότε λήγει η συνεδρία από μόνη της, εάν η πολιτική ορίζει λήξη. Οι συνεδρίες που αναφέρονται μέσω του API δεν έχουν καμία.
open	true ενόσω κανείς δεν έχει αποσυνδέσει τη συνεδρία και αυτή δεν έχει λήξει.
loginSource	Ποιος ανέφερε τη σύνδεση: DEVICE (ο πράκτορας Nomid στη συσκευή, σύνδεση με PIN ή SSO) ή API (το σύστημά σας, μέσω αυτού του API).
logoutSource	Ποιος ανέφερε την αποσύνδεση: DEVICE, API ή EXPIRY όταν η συνεδρία έληξε. Παραλείπεται ενόσω η συνεδρία είναι ανοιχτή.

Παραδείγματα

Αναφέρετε μια σύνδεση βάσει σειριακού αριθμού για έναν χρήστη του δικού σας συστήματος.

curl -X POST "https://api.nomid.tech/emm/api/v1/device-user-logins" \
  -H "X-API-Key: $NOMID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"serialNumber": "R58N123ABCD", "externalUserId": "emp-1042", "userName": "Ana Souza"}'

HTTP/1.1 201 Created

{
  "loginId": "5f0c2a8e-3b1d-4e7a-9c64-2d8f1b7e0a93",
  "deviceUser": {
    "id": "b2e47c19-8a3f-4d65-a0e1-6c9d2f5b8e74",
    "name": "Ana Souza",
    "auth": "EXTERNAL",
    "externalUserId": "emp-1042"
  },
  "asset": {
    "assetId": "k3x9m2pa",
    "serialNumber": "R58N123ABCD",
    "name": "Warehouse scanner 12"
  },
  "loginAt": "2026-10-29T11:02:41.518204Z",
  "open": true,
  "loginSource": "API"
}

Αποσυνδέστε αυτήν τη συνεδρία με το loginId της.

curl -X POST "https://api.nomid.tech/emm/api/v1/device-user-logins/logout" \
  -H "X-API-Key: $NOMID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"loginId": "5f0c2a8e-3b1d-4e7a-9c64-2d8f1b7e0a93"}'

HTTP/1.1 200 OK

[
  {
    "loginId": "5f0c2a8e-3b1d-4e7a-9c64-2d8f1b7e0a93",
    "deviceUser": {
      "id": "b2e47c19-8a3f-4d65-a0e1-6c9d2f5b8e74",
      "name": "Ana Souza",
      "auth": "EXTERNAL",
      "externalUserId": "emp-1042"
    },
    "asset": {
      "assetId": "k3x9m2pa",
      "serialNumber": "R58N123ABCD",
      "name": "Warehouse scanner 12"
    },
    "loginAt": "2026-10-29T11:02:41.518204Z",
    "logoutAt": "2026-10-29T19:30:05.204117Z",
    "open": false,
    "loginSource": "API",
    "logoutSource": "API"
  }
]

Ή κλείστε κάθε ανοιχτή συνεδρία API του χρήστη σε αυτήν τη συσκευή.

curl -X POST "https://api.nomid.tech/emm/api/v1/device-user-logins/logout" \
  -H "X-API-Key: $NOMID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"serialNumber": "R58N123ABCD", "externalUserId": "emp-1042"}'

Διαβάστε τις συνεδρίες μίας συσκευής από την 1η Οκτωβρίου. Αυτή είναι μια σύνδεση με PIN στη συσκευή η οποία έληξε.

curl "https://api.nomid.tech/emm/api/v1/device-user-logins?serialNumber=R58N123ABCD&from=2026-10-01T00:00:00Z&limit=20" \
  -H "X-API-Key: $NOMID_API_KEY"

HTTP/1.1 200 OK

[
  {
    "loginId": "e91d4b7a-0c2f-4a58-8b13-7f6e5d4c3b2a",
    "deviceUser": {
      "id": "4c8a1e2f-6b3d-4f70-9e15-0a2b3c4d5e6f",
      "name": "Shift 2 operator",
      "auth": "PIN"
    },
    "asset": {
      "assetId": "k3x9m2pa",
      "serialNumber": "R58N123ABCD",
      "name": "Warehouse scanner 12"
    },
    "loginAt": "2026-10-28T14:00:09.731552Z",
    "logoutAt": "2026-10-28T22:00:09.731552Z",
    "expiresAt": "2026-10-28T22:00:09.731552Z",
    "open": false,
    "loginSource": "DEVICE",
    "logoutSource": "EXPIRY"
  }
]

Σφάλμα: μια συνεδρία που ανέφερε η συσκευή

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "detail": "The login was reported by the device, not through the API",
  "instance": "/emm/api/v1/device-user-logins/logout",
  "code": "login_not_reported_by_api"
}

Σφάλματα

Τα τελικά σημεία συνεδρίας Device User απαντούν με 400, 404 και 409 με application/problem+json και ένα μέλος code για διακλάδωση· δεν στέλνουν μέλος retryable. Δύο εξαιρέσεις δεν έχουν code: το 401 και το 403, καθώς και ένα 400 για μη έγκυρη παράμετρο ερωτήματος του GET /device-user-logins.

Κατάσταση	Κωδικός	Σημασία
400	invalid_argument	Σύνδεση ή αποσύνδεση: το σώμα λείπει ή δεν είναι έγκυρο JSON της τεκμηριωμένης μορφής, απεστάλησαν και τα δύο ή κανένα από το ζεύγος συσκευής ή χρήστη, μια αποσύνδεση χωρίς loginId δεν περιέχει τη συσκευή ή τον χρήστη, ή το externalUserId (πάνω από 100 χαρακτήρες) ή το userName (πάνω από 50 χαρακτήρες) είναι πολύ μεγάλο ή περιέχει χαρακτήρες ελέγχου. Η λεπτομέρεια αναφέρει ποιο.
400	-	Μόνο λίστα: assetId και serialNumber μαζί, το from δεν είναι προγενέστερο του to, το from ή το to δεν είναι χρονική στιγμή ISO-8601 ή βρίσκεται εκτός του 1970 έως 9999, όριο κάτω του 1, ή το open δεν είναι true ή false.
401	-	Το κλειδί API λείπει, δεν είναι έγκυρο, έχει λήξει ή έχει ανακληθεί.
403	-	Από το κλειδί λείπει το DEVICES_READ (λίστα) ή το DEVICES_COMMAND (σύνδεση και αποσύνδεση).
404	asset_not_found	Δεν υπάρχει πάγιο με αυτό το assetId ή serialNumber στην εταιρεία του κλειδιού.
404	device_user_not_found	Δεν υπάρχει Device User με αυτό το deviceUserId στην εταιρεία του κλειδιού ή, σε περίπτωση αποσύνδεσης, κανένας με αυτό το externalUserId επειδή δεν συνδέθηκε ποτέ μέσω του API.
404	login_not_found	Δεν υπάρχει περίοδος σύνδεσης με αυτό το loginId στην εταιρεία του κλειδιού.
409	no_managed_device	Το πάγιο δεν διαθέτει διαχειριζόμενη συσκευή, επομένως δεν μπορεί να καταγραφεί σύνδεση σε αυτό.
409	device_user_disabled	Ο Device User είναι απενεργοποιημένος.
409	device_user_not_external	Ο Device User με αυτό το externalUserId δεν έχει πλέον έλεγχο ταυτότητας EXTERNAL.
409	login_device_mismatch	Η περίοδος σύνδεσης με αυτό το loginId δεν πραγματοποιήθηκε στη συσκευή που απεστάλη μαζί του.
409	login_user_mismatch	Η περίοδος σύνδεσης με αυτό το loginId δεν ανήκει στον απεσταλμένο χρήστη.
409	login_not_reported_by_api	Η περίοδος σύνδεσης αναφέρθηκε από τη συσκευή, μια σύνδεση με PIN ή SSO στον Nomid agent. Την κλείνει η συσκευή, όχι το API.

Όρια ρυθμού

Αυτά τα τελικά σημεία δεν αποτελούν μέρος του ορίου εγγραφής των 10 αιτημάτων ανά λεπτό ανά κλειδί που μοιράζονται οι εντολές συσκευών, οι αλλαγές πολιτικών και οι κωδικοί QR παροχής. Διαμορφώστε το client σας ώστε να εφαρμόζει backoff σε σφάλματα 429 ούτως ή άλλως.

Εργαλείο MCP

Το εργαλείο MCP μόνο για ανάγνωση list_device_user_logins λαμβάνει τα ίδια φίλτρα ως ορίσματα και απαιτεί DEVICES_READ. Με το Sign in with Nomid, ένας χρήστης που βλέπει μόνο ορισμένες πολιτικές λαμβάνει μόνο τις περιόδους σύνδεσης σε πάγια αυτών των πολιτικών. Η αναφορά συνδέσεων και αποσυνδέσεων γίνεται μόνο μέσω REST: κανένα εργαλείο MCP δεν την εκτελεί.

list_device_user_logins	DEVICES_READ	Περίοδοι σύνδεσης Device User, πρώτα οι νεότερες, με τα φίλτρα του GET /device-user-logins: ποιος συνδέθηκε σε ποιο πάγιο, πότε, και ποιος ανέφερε τη σύνδεση και την αποσύνδεση. Ακολουθεί το εύρος πολιτικής του καλούντος. Σφάλμα εργαλείου εάν το πάγιο δεν βρεθεί.

Διακομιστής MCP