Συνηθισμένες Ροές Εργασίας

Ελάχιστες, βήμα-προς-βήμα συνταγές για τις πιο συνηθισμένες λειτουργίες του B2C API — προσθήκη κλειδιού σε κλειδαριά, εμφάνιση κλειδαριάς στην εφαρμογή, αποστολή wallet pass και προσθήκη ενοίκου σε κουδούνι.

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

Για το πλήρες σχήμα request/response οποιουδήποτε endpoint, δείτε την καρτέλα API Reference.

Πριν ξεκινήσετε

Base URL. Τα παρακάτω παραδείγματα χρησιμοποιούν το περιβάλλον Development. Αλλάξτε τον host για το περιβάλλον σας:

Περιβάλλον	Base URL
Production	`https://api.spkey.co`
Staging	`https://b2c-api.spk-stage.workers.dev`
Development	`https://b2c-api.spk-dev.workers.dev`

Έλεγχος ταυτότητας (Authentication). Οι ενσωματώσεις B2B κάνουν authenticate με ένα API key στην κεφαλίδα X-API-Key (που χρησιμοποιείται στα παρακάτω παραδείγματα). Οι clients B2C χρησιμοποιούν ένα JWT μέσω Authorization: Bearer <token>. Στείλτε το ένα ή το άλλο — μην ορίζετε ποτέ εσωτερικές κεφαλίδες όπως X-Org-Id ή X-User-Id μόνοι σας· απορρίπτονται.

export API_KEY="your-api-key"
export BASE="https://b2c-api.spk-dev.workers.dev"

IDs — διαβάστε το μία φορά. Δύο διαφορετικοί τύποι αναγνωριστικών εμφανίζονται σε αυτές τις συνταγές:

Τα Lock endpoints (/locks/{id}/...) δέχονται το αριθμητικό lock id (π.χ. 123).
Τα User endpoints (/users/{id}/...) δέχονται το user UUID (π.χ. 550e8400-e29b-41d4-a716-446655440000).

Το να τα μπερδέψετε είναι το πιο συνηθισμένο λάθος ενσωμάτωσης.

Εξουσιοδότηση (Authorization). Για κλήσεις B2B, ο οργανισμός του API key σας πρέπει να είναι ιδιοκτήτης της κλειδαριάς-στόχου (ή να είναι super key). Για κλήσεις B2C, το JWT πρέπει να ανήκει στον ιδιοκτήτη της κλειδαριάς (ή σε χρήστη που ήδη κατέχει κλειδί), και ένας χρήστης μπορεί να τροποποιήσει μόνο τη δική του εγγραφή.

Προσθήκη κλειδιού σε κλειδαριά

Με μια ματιά: μία κλήση — POST /locks/{id}/AddKey με ένα keyUuid. Αυτό το μοναδικό αίτημα καταχωρεί το κλειδί στην κατάσταση της κλειδαριάς και το στέλνει στη συσκευή.

Προαπαιτούμενα

Η κλειδαριά υπάρχει ήδη. Οι κλειδαριές κανονικά δημιουργούνται κατά το provisioning του hardware μέσω POST /locks/{id}/CreateLock· αν δεν υπάρχει ακόμη, δημιουργήστε την πρώτα.
Έχετε κάνει authenticate και είστε εξουσιοδοτημένοι για αυτή την κλειδαριά (δείτε Πριν ξεκινήσετε).
Προαιρετικό: αν το κλειδί πρέπει επίσης να ζει στο Apple/Google Wallet του χρήστη, δημιουργήστε πρώτα ένα wallet key (Βήμα 1) και επαναχρησιμοποιήστε το id του ως keyUuid. Αν χρειάζεστε απλώς ένα λειτουργικό κλειδί, παραλείψτε το Βήμα 1 και περάστε οποιοδήποτε UUID δημιουργήσετε.

Βήμα 1 — (Προαιρετικό) Provisioning ενός wallet key για να λάβετε ένα key id

curl -X POST "$BASE/users/550e8400-e29b-41d4-a716-446655440000/AddWalletKey" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "walletType": "APPLE",
    "keyIndex": 2
  }'

Απόκριση:

{
  "success": true,
  "aggregateId": "550e8400-e29b-41d4-a716-446655440000",
  "version": 2,
  "keyId": "9b2e8f4a-1c3d-4e5f-8a9b-0c1d2e3f4a5b",
  "walletType": "APPLE"
}

Ο server δημιουργεί το keyId — μην το στείλετε στο αίτημα. Επαναχρησιμοποιήστε το keyId που επιστρέφεται ως keyUuid στο Βήμα 2, ώστε το wallet pass και η κλειδαριά να αναφέρονται στο ίδιο κλειδί.

Βήμα 2 — Προσθήκη του κλειδιού στην κλειδαριά

curl -X POST "$BASE/locks/123/AddKey" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyUuid": "9b2e8f4a-1c3d-4e5f-8a9b-0c1d2e3f4a5b",
    "keyIndexNumber": 2,
    "userId": "550e8400-e29b-41d4-a716-446655440000"
  }'

Απόκριση:

{
  "success": true,
  "aggregateId": "123",
  "version": 7,
  "event": {
    "type": "KeyAdded",
    "data": {
      "lockId": 123,
      "uuid": "lock-uuid",
      "keyUuid": "9b2e8f4a-1c3d-4e5f-8a9b-0c1d2e3f4a5b",
      "keyIndexNumber": 2,
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "timestamp": "2026-05-29T12:00:00.000Z"
    }
  }
}

Σημειώσεις:

Μόνο το keyUuid απαιτείται. Τα keyIndexNumber και userId είναι προαιρετικά metadata. Ο ορισμός του userId συνιστάται: επιτρέπει σε αυτόν τον χρήστη να διαχειρίζεται την κλειδαριά αργότερα, ακόμη κι αν δεν είναι ο ιδιοκτήτης.
Το {id} εδώ είναι το αριθμητικό lock id.
Δεν χρειάζεστε WriteKey. Το AddKey στέλνει ήδη την εντολή στη συσκευή. Το POST /locks/{id}/WriteKey είναι μια ξεχωριστή εντολή για την εγγραφή ενός κλειδιού σε μια φυσική κάρτα NFC — όχι συνέχεια του AddKey.
Η κλήση είναι fail-fast: αν η συσκευή δεν είναι προσβάσιμη, το αίτημα αποτυγχάνει με 502 και δεν καταγράφεται κλειδί — βεβαιωθείτε ότι η κλειδαριά είναι online.
Για να προσθέσετε πολλά κλειδιά σε μία κλειδαριά, χρησιμοποιήστε POST /locks/{id}/BulkAddKeys με έναν πίνακα keys. Εκτελεί τις προσθήκες διαδοχικά στο παρασκήνιο και επιστρέφει ένα instanceId αμέσως (δεν περιμένει να ολοκληρωθούν).
Επαληθεύστε με GET /locks/{id}/details — το νέο keyUuid εμφανίζεται στον πίνακα keys.

Εμφάνιση κλειδαριάς στην εφαρμογή του χρήστη

Με μια ματιά: μία κλήση — POST /users/{id}/AddAccessibleLock. Η λίστα κλειδαριών της εφαρμογής διαβάζεται από το GET /users/{id}/accessible-locks, οπότε αυτό είναι που κάνει μια κλειδαριά να εμφανίζεται στην εφαρμογή.

Η ορατότητα στην εφαρμογή και ένα λειτουργικό κλειδί είναι ανεξάρτητα. Το AddAccessibleLock προσθέτει απλώς την κλειδαριά στη λίστα του χρήστη — δεν κάνει provisioning ενός κλειδιού στη συσκευή. Για να μπορεί ο χρήστης να ανοίξει πραγματικά την κλειδαριά, χρειάζεστε επίσης να προσθέσετε ένα κλειδί ή να στείλετε ένα wallet pass.

Προαπαιτούμενα

Ο χρήστης υπάρχει ήδη. Αν όχι, δημιουργήστε τον πρώτα (Βήμα 1).
Το {id} είναι το user UUID.

Βήμα 1 — (Αν ο χρήστης είναι νέος) Δημιουργία του χρήστη

curl -X POST "$BASE/users/550e8400-e29b-41d4-a716-446655440000/CreateUser" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "email": "jane@example.com",
    "firstName": "Jane",
    "lastName": "Doe"
  }'

Το path {id} και το userId στο σώμα είναι το ίδιο UUID. Απαιτούμενα πεδία: userId, email.

Βήμα 2 — Παραχώρηση της κλειδαριάς στον χρήστη

curl -X POST "$BASE/users/550e8400-e29b-41d4-a716-446655440000/AddAccessibleLock" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lockId": "123",
    "lockName": "Front Door",
    "accessLevel": "USER",
    "grantedBy": "550e8400-e29b-41d4-a716-446655440000"
  }'

Απόκριση:

{
  "success": true,
  "aggregateId": "550e8400-e29b-41d4-a716-446655440000",
  "version": 2,
  "event": {
    "type": "AccessibleLockAdded",
    "data": {
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "lockId": "123",
      "lockName": "Front Door",
      "accessLevel": "USER",
      "grantedBy": "550e8400-e29b-41d4-a716-446655440000"
    }
  },
  "lockId": "123",
  "accessLevel": "USER"
}

Βήμα 3 — (Επαλήθευση) Διαβάστε αυτό που διαβάζει η εφαρμογή

curl "$BASE/users/550e8400-e29b-41d4-a716-446655440000/accessible-locks" \
  -H "X-API-Key: $API_KEY"

Απόκριση:

{
  "locks": [
    {
      "lockId": "123",
      "lockName": "Front Door",
      "accessLevel": "USER",
      "grantedBy": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "totalCount": 1
}

Σημειώσεις:

Απαιτούμενα πεδία: lockId, lockName, accessLevel, grantedBy.
Το accessLevel είναι ένα από OWNER, ADMIN, USER, GUEST. Είναι μια ετικέτα που εμφανίζεται στην εφαρμογή — δεν παραχωρεί από μόνη της τη δυνατότητα ανοίγματος της συσκευής.
Τα validFrom / validUntil γίνονται δεκτά από το αίτημα αλλά δεν εφαρμόζονται προς το παρόν — δεν υπάρχει χρονικά περιορισμένη πρόσβαση μέσω αυτού του endpoint.
Επιστρέφει 400 αν η κλειδαριά βρίσκεται ήδη στη λίστα του χρήστη.
Με ένα token χρήστη B2C μπορείτε να τροποποιήσετε μόνο τη δική σας λίστα. Για να παραχωρήσετε μια κλειδαριά σε διαφορετικό χρήστη, χρησιμοποιήστε ένα B2B API key.

Αποστολή wallet pass σε χρήστη

Με μια ματιά: δύο κλήσεις — POST /users/{id}/AddWalletKey, μετά GET /users/{id}/wallet/link. Η δεύτερη κλήση επιστρέφει το install URL που στέλνετε στον χρήστη· ανοίγοντάς το προστίθεται το pass στο Apple Wallet ή το Google Wallet.

Προαπαιτούμενα

Ο χρήστης υπάρχει ήδη (δημιουργήστε τον με POST /users/{id}/CreateUser αν όχι — ίδιο με το Βήμα 1 της προηγούμενης συνταγής).
Για το Apple Wallet, ο χρήστης πρέπει να έχει ένα email στο προφίλ του (ορισμένο κατά τη δημιουργία). Το Google Wallet δεν απαιτεί κάποιο.

Βήμα 1 — Provisioning του wallet key

curl -X POST "$BASE/users/550e8400-e29b-41d4-a716-446655440000/AddWalletKey" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "walletType": "APPLE",
    "keyIndex": 0
  }'

Απόκριση:

{
  "success": true,
  "aggregateId": "550e8400-e29b-41d4-a716-446655440000",
  "version": 2,
  "keyId": "9b2e8f4a-1c3d-4e5f-8a9b-0c1d2e3f4a5b",
  "walletType": "APPLE"
}

Απαιτούμενα πεδία: walletType (APPLE ή GOOGLE) και keyIndex. Ο server δημιουργεί το keyId — μην το στείλετε.

Βήμα 2 — Λήψη του install URL

curl "$BASE/users/550e8400-e29b-41d4-a716-446655440000/wallet/link" \
  -H "X-API-Key: $API_KEY"

Απόκριση:

{
  "url": "https://a.wallet.spkey.co/?email=jane%40example.com&uuid=9b2e8f4a-1c3d-4e5f-8a9b-0c1d2e3f4a5b&brand=spkey",
  "walletType": "APPLE"
}

Στείλτε το url στον χρήστη ακριβώς όπως επιστρέφεται (π.χ. με email ή SMS). Ανοίγοντάς το στο τηλέφωνό του εγκαθίσταται το pass.

Σημειώσεις:

Το URL χτίζεται από την πλευρά του server και είναι ασφαλές να σταλεί ως έχει. Τα links Apple φέρουν το email και το key id του χρήστη· τα links Google φέρουν το key id. Ο host διαφέρει ανά περιβάλλον.
Το 404 σημαίνει ότι ο χρήστης δεν έχει ακόμη wallet key — εκτελέστε πρώτα το Βήμα 1. Το 400 σημαίνει ότι το wallet είναι Apple αλλά ο χρήστης δεν έχει email καταχωρημένο.
Το εκ νέου provisioning του ίδιου walletType επιστρέφει 400. Το provisioning ενός διαφορετικού walletType αντικαθιστά το υπάρχον wallet key.
Το GET /users/{id}/wallet εκθέτει πεδία passUrl / serialNumber που μπορεί να είναι κενά — χρησιμοποιήστε το url από το wallet/link ως την πηγή αλήθειας για το install link.
Για να μπορεί το pass να ανοίξει πραγματικά μια κλειδαριά, προσθέστε επίσης το κλειδί σε αυτή την κλειδαριά, επαναχρησιμοποιώντας αυτό το keyId ως keyUuid.

Προσθήκη ενοίκου σε κουδούνι

Με μια ματιά: δύο κλήσεις — GET /users/by-email (που δημιουργεί αυτόματα τον χρήστη αν χρειάζεται), μετά POST /locks/{id}/AddResident με { email, name }. Οι ένοικοι ειδοποιούνται όταν πατιέται το κουδούνι.

Προαπαιτούμενα

Το κουδούνι/κλειδαριά υπάρχει ήδη, και είστε εξουσιοδοτημένοι για αυτό.
Το {id} είναι το αριθμητικό lock id.

Βήμα 1 — Βεβαιωθείτε ότι ο χρήστης του ενοίκου υπάρχει

curl "$BASE/users/by-email?email=resident@example.com" \
  -H "X-API-Key: $API_KEY"

Απόκριση:

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "email": "resident@example.com",
  "created_at": "2026-05-29T10:30:00.000Z"
}

Αυτό το endpoint είναι find-or-create: αν δεν υπάρχει χρήστης για το email, δημιουργεί έναν και τον επιστρέφει. Είναι idempotent, οπότε είναι ασφαλές να το καλείτε κάθε φορά πριν προσθέσετε έναν ένοικο. Για να αναθέσετε ένα συγκεκριμένο UUID κατά τη δημιουργία ενός ολοκαίνουργιου χρήστη, περάστε &uuid=<your-uuid> (επιστρέφει 409 αν αυτό το UUID είναι ήδη κατειλημμένο).

Βήμα 2 — Προσθήκη του ενοίκου στο κουδούνι

curl -X POST "$BASE/locks/123/AddResident" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "resident@example.com",
    "name": "Jane Doe"
  }'

Απόκριση:

{
  "success": true,
  "aggregateId": "123",
  "version": 5,
  "event": {
    "type": "ResidentAdded",
    "data": {
      "lockId": 123,
      "uuid": "lock-uuid",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Jane Doe",
      "email": "resident@example.com",
      "timestamp": "2026-05-29T12:00:00.000Z"
    }
  },
  "email": "resident@example.com"
}

Σημειώσεις:

Και τα δύο email και name απαιτούνται. Ο server αντιστοιχίζει το email σε έναν χρήστη στο παρασκήνιο.
Αν παραλείψετε το Βήμα 1 και δεν υπάρχει χρήστης για αυτό το email, το AddResident επιστρέφει 404 ζητώντας σας να καλέσετε πρώτα το GET /users/by-email — που είναι ακριβώς αυτό που κάνει το Βήμα 1.
Η προσθήκη του ίδιου ενοίκου δύο φορές επιστρέφει 400.
Η τρέχουσα λίστα ενοίκων είναι αναγνώσιμη στο GET /locks/{id}/residents. Αφαιρέστε έναν ένοικο με POST /locks/{id}/RemoveResident (σώμα: { "email": "..." }).

Βάζοντάς τα όλα μαζί

Μια συνηθισμένη end-to-end ροή για το onboarding ενός ενοίκου με ένα wallet key:

Δημιουργήστε τον χρήστη — POST /users/{userId}/CreateUser.
Provisioning ενός wallet key — POST /users/{userId}/AddWalletKey → επιστρέφει keyId.
Προσθέστε το κλειδί στην κλειδαριά τους — POST /locks/{lockId}/AddKey με keyUuid = αυτό το keyId.
Κάντε την κλειδαριά ορατή στην εφαρμογή τους — POST /users/{userId}/AddAccessibleLock.
Στείλτε το wallet pass — GET /users/{userId}/wallet/link → στείλτε το url στον χρήστη.
(Κουδούνι) προσθέστε τους στις ειδοποιήσεις — POST /locks/{lockId}/AddResident.

Επόμενα βήματα

Καρτέλα API Reference — πλήρες σχήμα για κάθε endpoint που χρησιμοποιείται εδώ.
Επισκόπηση Events — πώς η SmartphoneKey δημοσιεύει events (π.χ. KeyAdded, ResidentAdded) στα webhooks σας.
Onboarding Εταίρων — λάβετε το API key σας και ρυθμίστε webhooks.

Was this page helpful?