Sessions API

Μια Session είναι μία επιθεώρηση. Δημιουργήστε μία, εκδώστε πρόσκληση χρήστη πεδίου, καταγράψτε τεκμήρια, τερματίστε την. Όλα τα υπόλοιπα εξαρτώνται από αυτόν τον πόρο.

Το αντικείμενο Session

{
  "id": "0c8f4d2e-1a3b-4c5d-9e7f-1234567890ab",
  "status": "open",
  "operator_email": "ops@yourco.com",
  "scheduled_for": "2026-05-23T10:00:00Z",
  "started_at": "2026-05-23T10:00:14Z",
  "ended_at": null,
  "notes": "Vehicle damage — claim CL-2026-0042",
  "locale": "fr",
  "consent_state": { "camera": "granted", "gps": "granted" },
  "campaign": null,
  "created_at": "2026-05-21T14:21:00Z",
  "updated_at": "2026-05-23T10:00:14Z"
}

Δημιουργία συνεδρίας

POST /api/v1/public/sessions — εύρος sessions:write

curl -X POST https://app.nexbasira.com/api/v1/public/sessions \
  -H "Authorization: Bearer nb_sec_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "notes": "Vehicle damage — claim CL-2026-0042",
    "scheduled_for": "2026-05-23T10:00:00Z",
    "locale": "fr"
  }'

Επιστρέφει το νεοδημιουργημένο αντικείμενο Session (HTTP 201).

Πεδία σώματος

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

GET /api/v1/public/sessions — εύρος sessions:read

curl https://app.nexbasira.com/api/v1/public/sessions?limit=25 \
  -H "Authorization: Bearer nb_sec_..."

Με σελιδοποίηση cursor. Περάστε το cursor από το πεδίο της προηγούμενης απόκρισης next_cursor για την επόμενη σελίδα.

{
  "data": [{ /* Session, Session, ... */ }],
  "has_more": true,
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAy..."
}

Ανάκτηση συνεδρίας

GET /api/v1/public/sessions/{session_id} — εύρος sessions:read

Τερματισμός συνεδρίας

POST /api/v1/public/sessions/{session_id}/end — εύρος sessions:write

Κλείνει τη συνεδρία, ενεργοποιεί την αγκύρωση της κεφαλής αλυσίδας σε όλες τις διαμορφωμένες TSA και ξεκινά την μετεπεξεργασία της εγγραφής αν εκτελούνταν εγγραφή. Idempotent — η κλήση σε ήδη κλειστή συνεδρία επιστρέφει το κλειστό αντικείμενο Session χωρίς εκ νέου αγκύρωση.

Έκδοση πρόσκλησης χρήστη πεδίου

POST /api/v1/public/sessions/{session_id}/participants — εύρος participants:write

curl -X POST https://app.nexbasira.com/api/v1/public/sessions/0c8f.../participants \
  -H "Authorization: Bearer nb_sec_..." \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_first_name": "Alex",
    "recipient_last_name": "Garcia",
    "recipient_email": "alex@policyholder.com",
    "send_email": true,
    "ttl_minutes": 1440
  }'

{
  "id": "i-1",
  "session": "0c8f...",
  "role": "field",
  "expires_at": "2026-05-24T10:00:00Z",
  "recipient_first_name": "Alex",
  "recipient_last_name": "Garcia",
  "recipient_email": "alex@policyholder.com",
  "recipient_phone": "",
  "join_url": "https://app.nexbasira.com/join/0c8f.../?t=tok_PLAINTEXT_ONCE",
  "otp_code": "487192",
  "otp_required": true,
  "otp_expires_at": "2026-05-23T10:10:00Z",
  "created_at": "2026-05-23T10:00:00Z"
}

Το join_url και otp_code εμφανίζονται ακριβώς μία φορά στην απόκριση. Τα tokens είναι κλειδωμένα σε IP/UA, μίας χρήσης και χρονικά περιορισμένα.

Σύνδεση δύο παραγόντων (OTP)

Όταν παρέχετε τουλάχιστον ένα από τα recipient_email ή recipient_phone, η πλατφόρμα εκδίδει αυτόματα ένα 6ψήφιο αριθμητικό OTP και το στέλνει στο αντίστοιχο κανάλι/κανάλια σε ξεχωριστό μήνυμα από το URL σύνδεσης — άμυνα σε βάθος ώστε ένα προωθημένο email ή SMS να μη διαρρέει και τους δύο παράγοντες μαζί. Ο απλός κωδικός επιστρέφεται επίσης στην απόκριση ( otp_code) ώστε να μπορείτε να τον ξαναμοιραστείτε χειροκίνητα αν η παράδοση αποτύχει.

Στην πλευρά πεδίου, το SPA εμφανίζει την προτροπή OTP στην πρώτη εξαργύρωση. Υποβάλετε τον κωδικό μέσω της κεφαλίδας X-Join-OTP σε επανάληψη του GET /v1/sessions/{id}/join/{token} — η κεφαλίδα (όχι το URL) κρατά τον κωδικό εκτός του ιστορικού του προγράμματος περιήγησης και των access logs.

Κανόνες OTP:

• 6ψήφιο αριθμητικό, κατακερματισμένο με SHA-256 + pepper κατά την αποθήκευση.
• TTL 10 λεπτών από την έκδοση.
• 5 λανθασμένες προσπάθειες κλειδώνουν την πρόσκληση (HTTP 423) — ο χειριστής πρέπει να την επανεκδώσει.
• Επαληθεύεται μία φορά στην πρώτη εξαργύρωση· η εκ νέου εξαργύρωση από το ίδιο ζεύγος IP / UA παρακάμπτει τον έλεγχο (το token είναι ήδη κλειδωμένο).
• Η αυτοπρόσωπη παράδοση του URL (χωρίς recipient_email + χωρίς recipient_phone) παρακάμπτει την έκδοση OTP — το URL από μόνο του είναι ο παράγοντας ελέγχου ταυτότητας. Χρησιμοποιήστε το μόνο για αυτοπρόσωπες παραδόσεις.

Κωδικοί απόκρισης σε GET /v1/sessions/{id}/join/{token}:

Συνήθη σφάλματα

Δείτε Σφάλματα + όρια ρυθμού για την πλήρη μορφή του φακέλου σφάλματος και οδηγίες επανάληψης.