Sessions API

Session on yksi tarkastus. Luo yksi, muodosta kenttäkäyttäjäkutsu, tallenna todisteita, päätä se. Kaikki muu ripustuu tähän resurssiin.

Session-objekti

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

Luo istunto

POST /api/v1/public/sessions — laajuus 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"
  }'

Palauttaa juuri luodun Session-objektin (HTTP 201).

Runkokentät

Listaa istunnot

GET /api/v1/public/sessions — laajuus sessions:read

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

Kursorisivutettu. Välitä cursor edellisen vastauksen next_cursor -kentästä sivuttaaksesi.

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

Hae istunto

GET /api/v1/public/sessions/{session_id} — laajuus sessions:read

Päätä istunto

POST /api/v1/public/sessions/{session_id}/end — laajuus sessions:write

Sulkee istunnon, laukaisee ketjun pään ankkuroinnin kaikkiin määritettyihin TSA:ihin ja käynnistää tallenteen jälkikäsittelyn, jos tallennus oli käynnissä. Idempotentti — jo suljetussa istunnossa kutsuminen palauttaa suljetun Session-objektin ankkuroimatta uudelleen.

Muodosta kenttäkäyttäjäkutsu

POST /api/v1/public/sessions/{session_id}/participants — laajuus 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"
}

Arvot join_url ja otp_code näytetään täsmälleen kerran vastauksessa. Tokenit ovat IP/UA-sidottuja, kertakäyttöisiä ja aikarajattuja.

Kaksivaiheinen liittyminen (OTP)

Kun toimitat vähintään yhden näistä: recipient_email tai recipient_phone, alusta muodostaa automaattisesti 6-numeroisen numeerisen OTP:n ja lähettää sen täsmäävällä kanavalla/kanavilla erillisessä viestissä liittymis-URL:stä — syvyyspuolustusta, jotta välitetty sähköposti tai SMS ei vuoda molempia tekijöitä kerralla. Selkokoodi palautetaan myös vastauksessa ( otp_code), jotta voit jakaa sen uudelleen manuaalisesti, jos toimitus epäonnistuu.

Kenttäpuolella SPA näyttää OTP-kehotteen ensimmäisellä lunastuksella. Lähetä koodi X-Join-OTP -otsakkeessa uudelleenyrityksessä GET /v1/sessions/{id}/join/{token} — otsake (ei URL) pitää koodin poissa selainhistoriasta ja pääsylokeista.

OTP-säännöt:

• 6-numeroinen numeerinen, tiivistetty SHA-256:lla + pepperillä levossa.
• 10 minuutin TTL myöntämisestä.
• 5 väärää yritystä lukitsee kutsun (HTTP 423) — operaattorin on myönnettävä uudelleen.
• Varmennettu kerran ensimmäisellä lunastuksella; uudelleenlunastus samasta IP- / UA-parista ohittaa portin (token on jo sidottu).
• Kasvokkain tapahtuva URL-luovutus (ei recipient_email + ei recipient_phone) ohittaa OTP:n muodostamisen — URL yksin on tunnistautumistekijä. Käytä tätä vain henkilökohtaisiin luovutuksiin.

Vastauskoodit kohteessa GET /v1/sessions/{id}/join/{token}:

Yleiset virheet

Katso Virheet + nopeusrajat täyden virhekuoren muodon ja uudelleenyritysohjeen osalta.