Verificação Blockchain

Verificando um Registro

Usuários autenticados podem verificar qualquer registro ancorado na blockchain dentro da plataforma, e contrapartes podem verificar os mesmos registros na página de verificação pública sem precisar fazer login. A verificação confirma que o documento não foi alterado desde que foi ancorado: a plataforma recalcula o hash SHA-256 do documento atual e o compara ao hash registrado na blockchain. Uma correspondência significa que o documento está inalterado; uma discrepância indica que ele foi modificado desde a ancoragem.

O que você vai aprender

Como verificar um registro ancorado a partir de um caso
O que é necessário para realizar a verificação (no aplicativo vs. verificação pública)
O que significa uma verificação bem-sucedida ou com falha
Como pesquisar um registro por hash de transação ou ID de entidade
Como funciona o sistema de novas tentativas e transações pendentes

Requisito de autenticação

Vilulia oferece dois caminhos de verificação. Contrapartes que recebem um registro ancorado podem verificá-lo na página pública em /verify sem conta ou login, pelo hash de transação, ID de acordo, ID de decisão ou enviando um hash para comparação. A API de verificação no aplicativo é separada: requer autenticação, acesso ao caso ou entidade e o recurso blockchain_verification no seu plano.

Verificando a partir de um registro de caso

Para decisões arbitrais, o status de verificação blockchain é exibido diretamente na aba Decisões do caso. Depois que uma decisão é emitida e ancorada, o painel exibe o hash da transação (tx_hash), número do bloco, data e hora de confirmação, nome da rede e um link para visualizar a transação no PolygonScan. Se uma decisão ainda não foi ancorada, um botão Verificar na Blockchain é exibido para iniciar a ancoragem. Não há uma aba de Verificação separada no registro do caso.

A verificação é suportada para acordos, decisões, documentos (apenas finais/executados) e certificados de treinamento. Uploads de evidências, rascunhos e documentos de trabalho não são registrados na cadeia.

Códigos QR de certificados de treinamento

Certificados de treinamento em PDF incluem um código QR que codifica uma URL de verificação no formato https://vilulia.com/verify/{verification_code}. Ao escanear o código QR, abre-se uma consulta de verificação pública para esse certificado, retornando o nome do titular, título do curso e data de emissão. Nenhum login é necessário.

Verificação por hash de transação ou ID de entidade

Qualquer registro ancorado pode ser verificado por hash de transação (GET /api/v1/blockchain/tx/{tx_hash}) ou por tipo e ID de entidade (por exemplo, GET /api/v1/blockchain/settlement/{id}, GET /api/v1/blockchain/award/{id}, GET /api/v1/blockchain/document/{id} ou GET /api/v1/blockchain/certificate/{id}). A página de verificação pública cobre um subconjunto desses sem login: GET /verify/tx/{tx_hash}, GET /verify/settlement/{id} e GET /verify/award/{id}. Administradores também podem navegar pela página Histórico de Verificação Blockchain no painel administrativo, que lista todos os registros ancorados em uma tabela filtrável e paginada com suporte a exportação CSV.

Transações pendentes

Quando uma transação é enviada à rede Polygon mas o tempo de confirmação expira, o sistema a salva como pendente e uma tarefa em segundo plano continua monitorando-a. O status de ancoragem pode ser consultado via GET /api/v1/blockchain/anchor-status/{log_id} ou por entidade usando GET /api/v1/blockchain/anchor-status/by-entity/{type}/{id}. Os valores de status são: pending, processing, submitted, confirmed e failed.

Lógica de novas tentativas

O sistema de ancoragem repete automaticamente falhas transitórias (erros de rede, tempos esgotados, limites de taxa, respostas 5xx) usando backoff exponencial com jitter completo, até três tentativas por padrão. Falhas permanentes, como fundos insuficientes, assinatura inválida ou execução revertida, não são repetidas. Se todas as tentativas forem esgotadas, o registro é marcado como com falha e pode ser reenviado manualmente.

Resultados da verificação

Um resultado verificado significa que o hash SHA-256 do documento atual corresponde ao hash registrado na blockchain Polygon no momento da ancoragem, confirmando que o documento não foi modificado. Uma verificação com falha significa que os hashes não correspondem, indicando que o conteúdo do documento difere do que foi ancorado. Uma verificação com falha deve ser investigada imediatamente.

Se o serviço blockchain estiver indisponível no momento da verificação, a plataforma recorre à comparação do hash esperado com o hash armazenado localmente no banco de dados e registra isso na resposta.