Proovik
Certificar
REST · JSON · sem host à parte

API da Proovik

Prove que o seu documento já existia numa data e hora concretas, a partir do seu próprio código. É a mesma API que este site usa: todos os endpoints desta página existem hoje e respondem em produção.

URL base https://proovik.com/api

Autenticação · Cabeçalho Authorization: Bearer SUA_API_KEY nos endpoints marcados com «chave». Os marcados «público» não precisam de chave.

Como obter a chave de API hoje

Ainda não é autosserviço. A Proovik ativa a chave manualmente para a sua conta e, uma vez ativa, aparece no seu painel, na secção API. Uma única chave serve para certificação e rastreabilidade.

  1. Crie uma conta (grátis).
  2. Peça a ativação da API através do formulário de contacto, assunto «API», indicando o e-mail da sua conta e para que a vai usar.
  3. Quando estiver ativa, copie a chave a partir do painel. Se ainda não aparecer, o pedido não foi processado: não há outra via.
Solicitar ativação Ver o meu painel

Certificação de documentos

Ancoragem do SHA-256 de um ficheiro na cadeia de Kaspa

O documento nunca é enviado: calcula o SHA-256 no seu sistema e envia apenas o hash (64 caracteres hexadecimais).

POST/api/certifychaveCertificar um hash

Regista o hash na cadeia. Consome um crédito da sua conta. Se o mesmo hash já estava certificado, devolve o registo existente (already_exists: true) sem consumir nada.

Pedido
curl -X POST https://proovik.com/api/certify \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "description": "Contrato v2.1"
  }'
Resposta · 200 · confirmada
{
  "success": true,
  "status": "success",
  "confirmed": true,
  "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "txid": "b173e1ff…802889",
  "explorer_url": "https://explorer.kaspa.org/txs/b173e1ff…802889",
  "timestamp": "2026-01-12 20:48:30",
  "credit_consumed": true,
  "certificate_url": "/api/certificate?hash=e3b0c442…&t=…"
}
202 · enviada e pendente. A transação já foi emitida mas ainda não está visível: reenvie o mesmo hash passados alguns segundos para obter o estado final (não há webhook que o avise).

Erros: 400 invalid_hash · 401 invalid_api_key · 401 identification_required (sem chave, o endpoint fica reservado ao formulário web) · 429 no_credits · 502 notary_failed (nada é cobrado).

GET/api/verify?hash={sha256}públicoConsultar se um hash está certificado

Qualquer pessoa pode consultá-lo, sem chave. Só devolve certificações confirmadas na cadeia.

Pedido
curl "https://proovik.com/api/verify?hash=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
Resposta
{
  "success": true,
  "exists": true,
  "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "txid": "b173e1ff…802889",
  "explorer_url": "https://explorer.kaspa.org/txs/b173e1ff…802889",
  "timestamp": "2026-01-12 20:48:30",
  "has_merkle_proof": true
}
// {"success": true, "exists": false}  si no está certificado
GET/api/certificate?hash={sha256}&t={token}públicoDescarregar o certificado PDF

A resposta de /api/certify inclui certificate_url: uma ligação assinada (parâmetro t) que mostra também os seus metadados privados. Sem t, o mesmo endpoint serve a versão pública do certificado a qualquer pessoa. O PDF leva anexado o pacote de prova PVK-PROOF/1, que pode ser verificado sem a Proovik.

Pedido
curl -o certificado.pdf \
  "https://proovik.com/api/certificate?hash=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

Erros: 404 not_found · 409 certification_pending (JSON, não PDF: ainda não há certificado) · 429 rate_limited (60 descargas por hora e IP).

GET/api/certify/proof?hash={sha256}chaveProva Merkle de uma certificação

Devolve o caminho Merkle e a raiz ancorada de uma certificação feita com a sua chave. As de outras contas respondem 404.

Pedido
curl "https://proovik.com/api/certify/proof?hash=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
  -H "Authorization: Bearer SUA_API_KEY"
Resposta
{
  "success": true,
  "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "status": "success",
  "txid": "b173e1ff…802889",
  "anchored": true,
  "merkle_root": "d4735e3a…13ab35",
  "merkle_proof": [ { "hash": "…", "position": "left" }, … ]
}

Rastreabilidade de lotes

Lotes e eventos encadeados por hash e ancorados em lotes Merkle

Cada evento liga ao hash do anterior; o primeiro liga ao hash do lote. Os registos são ancorados na cadeia de Kaspa em ciclos de alguns minutos: o estado passa de pending a confirmed sem que tenha de fazer nada. Identificadores GS1 (GTIN, SGTIN, GLN) validados com dígito de controlo.

POST/api/trace/batchchaveCriar um lote

Obrigatório: product_name. Opcionais: batch_id (se não, é gerado), gtin, sgtin (único em todo o sistema; repetido responde 409), origin, origin_gln, origin_lat/origin_lng, quantity, quantity_unit, metadata. Aceita o cabeçalho Idempotency-Key.

Pedido
curl -X POST https://proovik.com/api/trace/batch \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_name": "Aceite de oliva virgen extra 500 ml",
    "gtin": "8412345678905",
    "origin": "Jaén",
    "quantity": 5000,
    "quantity_unit": "bottles",
    "metadata": { "variety": "Picual", "harvest_year": 2025 }
  }'
Resposta · 201
{
  "success": true,
  "batch_id": "BATCH-20260905-A1B2C3D4",
  "payload_hash": "7f83b165…6d9069",
  "created_at": "2026-09-05T10:00:00+00:00"
}
POST/api/trace/eventchaveAdicionar um evento

Obrigatórios: batch_id e event_type, um de COMMISSION, OBSERVE, TRANSFORM, SHIP, RECEIVE, AGGREGATE, DISAGGREGATE, CUSTOM. Opcionais: location {name, gln, lat, lng}, actor {name, id, role}, data, evidence_hash, gs1_bizstep.

Pedido
curl -X POST https://proovik.com/api/trace/event \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_id": "BATCH-20260905-A1B2C3D4",
    "event_type": "SHIP",
    "location": { "name": "Almacén central", "gln": "8412345000010" },
    "data": { "carrier": "Transportes Sur", "pallets": 12 }
  }'
Resposta · 201
{
  "success": true,
  "event_id": 17,
  "sequence": 3,
  "event_hash": "e3b0c442…52b855",
  "prev_event_hash": "9f86d081…00a08",
  "status": "pending"
}
GET/api/trace/batch/{batch_id}chave opcionalLer um lote com os seus eventos

Sem chave devolve a vista pública do lote; com a sua chave, os dados completos dos seus próprios lotes.

Pedido
curl "https://proovik.com/api/trace/batch/BATCH-20260905-A1B2C3D4" \
  -H "Authorization: Bearer SUA_API_KEY"
GET/api/trace/verify/{batch_id}chave opcionalVerificar a integridade de um lote

Recalcula o hash do lote, a cadeia de eventos e as provas Merkle contra o que está ancorado. overall_valid só é true se tudo bater certo; fully_verified exige além disso que todos os eventos estejam confirmados.

Pedido
curl "https://proovik.com/api/trace/verify/BATCH-20260905-A1B2C3D4"
Resposta
{
  "success": true,
  "batch_id": "BATCH-20260905-A1B2C3D4",
  "verification": {
    "overall_valid": true,
    "batch_integrity": { "valid": true, … },
    "chain_integrity": { "valid": true, … },
    "fully_verified": true
  }
}

Também existem, com chave: GET /api/trace/search?gtin=|sgtin=|lot=|product=, GET /api/trace/event/{event_id}, GET /api/trace/event/{event_id}/proof, GET /api/trace/batch/{batch_id}/proof e GET /api/trace/batch/{batch_id}/qr. Detalhe na referência completa.

Limites por chave: 60 escritas e 300 leituras por minuto. Ao ultrapassá-los responde 429 com Retry-After.

Verificação independente (PVK-PROOF/1)

Comprovar uma prova sem confiar na Proovik

O verificador recalcula os quatro elos da prova: o hash do documento está na transação, a transação está na árvore Merkle do bloco, o cabeçalho reproduz o hash do bloco e esse cabeçalho tem uma prova de trabalho válida. O hash do documento é sempre você que o fornece: nunca é lido do pacote. Três veredictos: VALIDO, INCOMPLETO (não foi possível determinar; nunca conta como válido) e INVALIDO.

POST/api/verify/proofpúblicoVerificar um pacote de prova

Envie o ficheiro .pvkproof.json (o que vai anexado ao PDF) ou o pacote em JSON, juntamente com o SHA-256 da sua cópia do documento. Não consulta a rede: verifica o que lhe der. Sem chave.

Pedido
curl -X POST https://proovik.com/api/verify/proof \
  -F "hash=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
  -F "[email protected]"
Resposta
{
  "spec": "PVK-PROOF/1",
  "modo": "paquete",
  "documento_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "txid": "b173e1ff…802889",
  "resultado": "VALIDO",
  "valido": true,
  "completo": true,
  "eslabones": [
    { "n": 1, "estado": "OK", … },
    { "n": 2, "estado": "OK", … },
    { "n": 3, "estado": "OK", … },
    { "n": 4, "estado": "OK", … }
  ],
  "algoritmo": { … }
}
GET/api/verify/proof/{txid}?hash={sha256}públicoReconstruir e verificar a partir da cadeia

Apenas com o txid e o hash, reconstrói o pacote consultando a rede de Kaspa. O cabeçalho completo do bloco só está disponível cerca de 40 horas: passado esse prazo, os elos 3 e 4 ficam INCOMPLETO. Sem chave; com CORS aberto; 30 pedidos por hora e IP.

Pedido
curl "https://proovik.com/api/verify/proof/b173e1ff9d73e09b51db78b9050a4be578f232f3d5e106a214950a8265802889?hash=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

Especificação e verificador online

O que esta API não tem (ainda)

  • Webhooks de saída. Nada o avisa quando uma transação é confirmada. Para certificações, reenvie o mesmo hash para POST /api/certify ou consulte GET /api/verify?hash=; para rastreabilidade, consulte GET /api/trace/verify/{batch_id}.
  • SDKs. Não há bibliotecas oficiais em nenhuma linguagem. É HTTP e JSON: qualquer cliente HTTP serve.
  • Ficheiro OpenAPI. A referência de campos e respostas está na documentação técnica ligada abaixo.
  • Chaves em autosserviço, várias chaves ou âmbitos. Uma chave por conta, ativada à mão.
  • Ambiente de testes. Cada certificação real consome um crédito. Para testar sem gastar, use os endpoints públicos de consulta e verificação.
PVK-PROOF/1

Referência completa e verificador

A documentação técnica descreve todos os campos e respostas (por agora só em espanhol). O verificador online comprova qualquer certificado sem conta.

Documentação técnica Verificador online Solicitar chave de API