Conceitos

O que são realmente uma Sessão, uma linha de Evidence e uma Cadeia de auditoria, no menor número de palavras possível. Leia isto uma vez e a referência da API fará sentido.

Organização

O tenant de topo. Uma organização corresponde a uma conta de cliente. Todos os outros recursos (sessões, provas, eventos de auditoria, utilizadores) têm âmbito de uma organização via segurança ao nível da linha nas tabelas Postgres subjacentes. Um bug no código aplicacional não consegue cruzar tenants — a base de dados recusa a query.

Uma organização tem: membros (utilizadores com acesso baseado em papéis), branding (logótipo / cores / rodapé de PDF), uma subscrição de faturação, dados opcionais de entidade legal KYB, configuração opcional de SSO e uma política de retenção.

Membro, Papel, Permissão

Um A adesão é a ligação entre um utilizador e uma organização. Um utilizador pode ter adesões em várias organizações e alternar entre elas (a organização ativa viaja como claim do JWT).

Cada organização semeia quatro papéis de sistema na criação:

• org_admin — controlo total. Faturação, membros, branding, retenção.
• inspector — pode realizar inspeções, capturar provas, assinar relatórios.
• observer — acesso só de leitura a sessões + dados de auditoria.
• auditor — acesso só de leitura mais permissão de verificação da cadeia.

Os administradores da organização podem criar papéis personalizados compondo o catálogo de permissões. As permissões são verificadas por slug na camada de vista + cruzadas pelo RLS na camada da BD.

Sessão

Uma inspeção. A unidade de faturação (paga por sessão fechada) e a unidade de prova (uma cadeia de auditoria é por sessão, não por organização).

Uma sessão tem: um operador (o membro da sua equipa que a iniciou), um ou mais participantes (o utilizador de campo, mais observadores opcionais), estado de consentimento, posição de GPS opcional, notas opcionais, uma cadeia de auditoria e — uma vez fechada — tokens de selo temporal ancorados na TSA.

Participante

Uma pessoa numa sessão. Há um operador por sessão e pelo menos um utilizador de campo; observadores adicionais opcionais são suportados. Os utilizadores de campo entram via um URL assinado de uso único (sem conta necessária); operadores + observadores são membros da organização.

Provas

Uma peça de prova capturada durante uma sessão. Tipos:

• snapshot — fotografia fixa da câmara do utilizador de campo.
• annotation — desenho sobreposto a uma captura ou quadro branco.
• whiteboard — tela Excalidraw em sessão exportada como PNG + estado.
• clip — segmento de vídeo curto.
• document — ficheiro carregado (usado pela camada de chat para PDF-para-assinatura).

Cada linha de Evidence tem um SHA-256 do seu conteúdo binário, guardado na cadeia de auditoria. Adulterar o ficheiro a posteriori faz falhar a verificação.

Cadeia de auditoria

A espinha dorsal criptográfica. Cada evento de uma sessão — criação da sessão, concessão de consentimento, registo de GPS, captura de provas, anotação, gravação do quadro branco, assinatura, fim da sessão — emite uma linha AuditEvent com:

{
  "session": "<uuid>",
  "sequence": N,
  "occurred_at": "<iso8601>",
  "kind": "evidence.snapshot_added",
  "actor": { "user": <id|null>, "participant": <id|null> },
  "payload": { /* event-specific */ },
  "prev_hash": "<sha256 of previous event>",
  "hash": "<sha256 of canonical_json of this event>"
}

O primeiro evento usa prev_hash = "0" * 64 (génese). Cada evento subsequente usa o hash do evento anterior como prev_hash e incrementa sequence em 1. Um advisory lock do Postgres serializa as escritas por sessão; um trigger append-only bloqueia UPDATE + DELETE na tabela.

TimestampToken (âncora TSA)

No fim da sessão (e na «carimbar agora» acionada pelo operador), a cabeça da cadeia atual é submetida a três autoridades de selo temporal independentes:

• YodaLedger — Âncora na blockchain Tezos. Finalidade em ~15-20 minutos. Assíncrona; recebemos um callback quando o bloco é confirmado.
• FreeTSA — Selo temporal RFC 3161. Síncrono; token devolvido de imediato. Substituível por um QTSP pago (DataSure) para conformidade com o Art. 42 do eIDAS.
• OpenTimestamps — Âncora em Bitcoin via o protocolo de calendário OpenTimestamps. Assíncrona; o caminho de upgrade corre numa varredura Celery.

Três é por conceção — se qualquer uma das TSAs desaparecer, as outras duas continuam a ancorar a cadeia. Um auditor pode verificar contra qualquer uma delas de forma independente usando exploradores de blocos públicos / endpoints de verificação.

Assinatura (SES / AES / QES)

Três níveis eIDAS, todos sobre o mesmo PDF de relatório de auditoria:

• SES (Simple Electronic Signature) — apoiada pela cadeia de auditoria, sem certificado de assinatura. Adequada para registos internos.
• AES (Advanced Electronic Signature) — certificado de assinatura ligado à identidade, ancorado em PAdES B-T. Adequada para a maioria dos contratos B2B.
• QES (Qualified Electronic Signature) — o nível eIDAS mais elevado, equivalente legal de uma assinatura manuscrita em toda a UE. Condicionada à verificação KYB da organização emissora.

Campanha (opcional)

Um agrupamento lógico de sessões para relatórios em lote — «Sinistros automóvel do 2.º trimestre de 2026» ou «Defeitos de entrega do Local A». As sessões não requerem uma campanha; é uma comodidade de relatório.

Webhook

Um URL registado pelo cliente que recebe POSTs de eventos assinados com HMAC. Tipos de evento: session.created, session.completed, participant.joined, participant.left, evidence.added, recording.ready, audit.anchored, signature.completed, mais um webhook.test para verificação de entrega.

Assinatura: estilo Stripe t=...,v1=... cabeçalho com HMAC-SHA256 sobre <timestamp>.<body>. O helper constructEvent() do SDK verifica em tempo constante com uma tolerância de desvio de relógio de 5 minutos.