Evidence API

Μια εγγραφή Evidence είναι ένα τεκμήριο που καταγράφηκε κατά τη διάρκεια μιας συνεδρίας — ένα στιγμιότυπο, ένας πίνακας ζωγραφικής, ένα βίντεο κλιπ, μια εγγραφή ή ένα μεταφορτωμένο έγγραφο. Κάθε εγγραφή φέρει ένα sha256 + byte_size + mime ώστε η αλυσίδα επαλήθευσης ακεραιότητας να μπορεί να αποδείξει ότι τα bytes δεν παραποιήθηκαν μεταξύ της καταγραφής και του ελέγχου.

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

{
  "id": "ev-7f3a...",
  "session": "0c8f4d2e-1a3b-4c5d-9e7f-1234567890ab",
  "kind": "snapshot",
  "status": "ready",
  "mime": "image/jpeg",
  "byte_size": 184523,
  "sha256": "f9cc12fda76c30dcc9bee627baed6c9e8fe11b813313de70b1463f9f73e5e418",
  "captured_at": "2026-05-23T10:14:02.481Z",
  "created_at": "2026-05-23T10:14:02.917Z",
  "completed_at": "2026-05-23T10:14:03.211Z"
}

Είδη

Είδος	Καταγράφηκε από	Σημειώσεις
`snapshot`	Χειριστής ή πλευρά πεδίου	Μεμονωμένο ακίνητο καρέ (JPEG). Το πιο συνηθισμένο είδος.
`whiteboard`	Χειριστής	Εξαγωγή Excalidraw — PNG + κανονικοποιημένο JSON. Δείτε Πίνακες ζωγραφικής.
`clip`	Χειριστής	Σύντομο MP4 κομμένο από τη ζωντανή συνεδρία — χρησιμοποιείται για την καταγραφή κίνησης που επιδεικνύει ο χρήστης πεδίου.
`recording`	Σύστημα	Πλήρης εγγραφή συνεδρίας. Μετεπεξεργασία σε libx264 medium / crf20 μετά τον τερματισμό της συνεδρίας.
`document`	Χειριστής	Συνημμένο αρχείο από τη συνομιλία εντός συνεδρίας (PDF, φωτογραφίες κ.λπ.). Θεμέλιο για PDF προς υπογραφή.

Κατάσταση

Κατάσταση	Σημασία
`pending`	Η εγγραφή δημιουργήθηκε· τα bytes δεν είναι ακόμη στο object storage.
`uploading`	Μεταφόρτωση multipart σε εξέλιξη.
`ready`	Τα bytes είναι μόνιμα αποθηκευμένα· τα sha256 + byte_size οριστικοποιήθηκαν. Μόνο οι εγγραφές `ready` είναι διαθέσιμες για λήψη.
`failed`	Η καταγραφή ή η μεταφόρτωση ματαιώθηκε. `completed_at` είναι null.

Λίστα τεκμηρίων συνεδρίας

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

curl "https://app.nexbasira.com/api/v1/public/sessions/0c8f.../evidence?kind=snapshot&limit=50" \
  -H "Authorization: Bearer nb_sec_..."

Παράμετροι query

Παράμετρος	Τύπος	Σημειώσεις
`kind`	string	Φίλτρο — ένα από τα `snapshot`, `whiteboard`, `clip`, `recording`, `document`.
`limit`	int	Μέγιστο 100. Προεπιλογή 25.
`cursor`	opaque	Από το πεδίο της προηγούμενης απόκρισης `next_cursor`.

Λήψη υπογεγραμμένου URL λήψης

GET /api/v1/public/evidence/{evidence_id}/download — εύρος evidence:read

Επιστρέφει ένα βραχύβιο presigned URL από το οποίο ο πελάτης ανακτά τα ακατέργαστα bytes. Το URL δείχνει απευθείας στο backend object-storage ώστε οι λήψεις να παρακάμπτουν τους app servers μας — καμία χρέωση bandwidth-egress από τη δική σας πλευρά του δημόσιου API.

curl "https://app.nexbasira.com/api/v1/public/evidence/ev-7f3a.../download" \
  -H "Authorization: Bearer nb_sec_..."

{
  "url": "https://s3.eu-central-1.amazonaws.com/nb-prod-evidence/orgs/.../snapshot.jpg?X-Amz-Algorithm=...",
  "expires_in_seconds": 900,
  "sha256": "f9cc12fda76c30dcc9bee627baed6c9e8fe11b813313de70b1463f9f73e5e418",
  "byte_size": 184523,
  "mime": "image/jpeg",
  "kind": "snapshot"
}

Καλέστε ξανά όταν λήξει το URL — καμία ποινή περιορισμού ρυθμού για επαναλαμβανόμενες εκδόσεις. Μετά τη λήψη, κατακερματίστε τα bytes με SHA-256 και συγκρίνετε με το επιστρεφόμενο sha256 για να επαληθεύσετε ότι το αρχείο είναι ακέραιο από άκρο σε άκρο.

# integrity check — Python
import hashlib, requests
r = requests.get(presigned["url"]); r.raise_for_status()
assert hashlib.sha256(r.content).hexdigest() == presigned["sha256"]

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

Κατάσταση	Κωδικός	Πότε
403	`permission_denied`	Το διαπιστευτήριο δεν διαθέτει `evidence:read`.
404	`not_found`	Η εγγραφή Evidence δεν υπάρχει στον οργανισμό του διαπιστευτηρίου.
409	`evidence_not_ready`	Ζητήθηκε λήψη σε εγγραφή της οποίας το `status` δεν είναι `ready`.
410	`retention_expired`	Η πολιτική διατήρησης του οργανισμού έχει ξεπεράσει το όριο ηλικίας της εγγραφής· τα bytes έχουν εκκαθαριστεί από το object storage.

Σημειώσεις

Χωρίς POST/PATCH/DELETE. Τα τεκμήρια καταγράφονται στην πλευρά του πελάτη (χειριστής + SPA πεδίου) κατά τη διάρκεια της συνεδρίας. Το δημόσιο API είναι μόνο για ανάγνωση σε αυτόν τον πόρο.
Διατήρηση. Κάθε οργανισμός διαμορφώνει ένα παράθυρο διατήρησης (προεπιλογή 7 έτη για αναπτύξεις συμβατές με eIDAS). Μετά το παράθυρο, οι κανόνες κύκλου ζωής του object-storage εκκαθαρίζουν τα bytes· η εγγραφή παραμένει ώστε να μη σπάει η αλυσίδα ελέγχου, αλλά το /download επιστρέφει 410.
Αγκυρωμένο στην αλυσίδα ελέγχου. Κάθε εγγραφή ready συνεισφέρει το sha256 της στην αλυσίδα κατακερματισμού ανά συνεδρία, η οποία αγκυρώνεται στην TSA κατά τον τερματισμό της συνεδρίας. Η κεφαλή αλυσίδας + η απόδειξη TSA είναι προσβάσιμες μέσω του endpoint audit-verify στην πλευρά SPA.