API Sesiuni

O Sesiune este o inspecție. Creați una, generați o invitație pentru utilizatorul de teren, capturați probe, încheiați-o. Tot restul se sprijină pe această resursă.

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

Creați o sesiune

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

Returnează obiectul Session nou creat (HTTP 201).

Câmpuri ale corpului

Listați sesiunile

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

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

Paginat prin cursor. Transmiteți cursor cu next_cursor din răspunsul anterior pentru a naviga între pagini.

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

Obțineți o sesiune

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

Încheiați o sesiune

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

Închide sesiunea, declanșează ancorarea capului de lanț la toate TSA-urile configurate și pornește postprocesarea înregistrării dacă rula o înregistrare. Idempotent — apelarea pe o sesiune deja închisă returnează obiectul Session închis fără a reancora.

Generați o invitație pentru utilizatorul de teren

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

Atât join_url cât și otp_code sunt afișate exact o dată în răspuns. Token-urile sunt legate de IP/UA, de unică folosință și limitate în timp.

Alăturare cu doi factori (OTP)

Când furnizați cel puțin unul dintre recipient_email sau recipient_phone, platforma generează automat un OTP numeric din 6 cifre și îl trimite pe canalul (canalele) corespunzător(oare) într-un mesaj separat de URL-ul de alăturare — apărare în profunzime, astfel încât un e-mail sau SMS redirecționat să nu dezvăluie ambii factori deodată. Codul în clar este de asemenea returnat în răspuns ( otp_code) ca să îl puteți re-partaja manual dacă livrarea eșuează.

Pe partea de teren, SPA afișează solicitarea OTP la prima utilizare. Trimiteți codul prin antetul X-Join-OTP la o reîncercare a GET /v1/sessions/{id}/join/{token} — antetul (nu URL-ul) ține codul departe de istoricul browserului și de jurnalele de acces.

Reguli OTP:

• Numeric din 6 cifre, hash-uit cu SHA-256 + pepper în repaus.
• TTL de 10 minute de la emitere.
• 5 încercări greșite blochează invitația (HTTP 423) — operatorul trebuie să reemită.
• Verificat o dată la prima utilizare; reutilizarea de la aceeași pereche IP / UA sare peste verificare (token-ul este deja legat).
• Predarea URL-ului față în față (fără recipient_email + fără recipient_phone) sare peste generarea OTP — doar URL-ul este factorul de autentificare. Folosiți asta doar pentru predări în persoană.

Coduri de răspuns pentru GET /v1/sessions/{id}/join/{token}:

Erori frecvente

Vedeți Erori + limite de rată pentru forma completă a plicului de eroare și ghidul de reîncercare.