PROXAE

API REFERENCE

API Reference

Integre a certificação de marca temporal do Proxae nas suas aplicações através da nossa API REST.

01

Autenticação

Todas as requisições API devem incluir a sua chave API no header X-API-Key. Crie as suas chaves nas configurações da conta.

Header
X-API-Key: pxe_your_api_key_here

Mantenha as suas chaves API em segredo. Nunca as exponha no lado do cliente.

02

Base URL

https://proxae.com/api/v1
03

Criar um proof

POST /proofs

Envia um hash SHA-256 para registo temporal na blockchain do Bitcoin. O conteúdo nunca é enviado — apenas o hash é transmitido.

Corpo da requisição
{
  "content_hash": "e3b0c44298fc1c149afbf4c8996fb924...",
  "title": "My document"           // opcional
}
Campo Type Descrição
content_hash string Hash SHA-256 do conteúdo (64 caracteres hex). Obrigatório.
title string Título opcional para o proof.
Resposta — 201
{
  "proof_id": "550e8400-e29b-41d4-a716-446655440000"
}
04

Obter um proof

GET /proofs/{id}

Retorna os detalhes completos de um proof pelo seu UUID.

Resposta — 200
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "content_hash": "e3b0c44298fc1c14...",
  "status": "CONFIRMED",
  "bitcoin_block": 850123,
  "bitcoin_block_time": "2026-09-22T14:30:00Z",
  "created_at": "2026-09-22T12:00:00Z"
}
05

Verificar estado

GET /proofs/{id}/status

Endpoint leve para verificar se um proof foi confirmado na blockchain. Ideal para polling.

Resposta — 200
{
  "id": "550e8400-...",
  "status": "PENDING",
  "has_ots": true,
  "bitcoin_block": null,
  "bitcoin_block_time": null
}
06

Listar proofs

GET /proofs

Retorna a lista paginada de todos os proofs associados à sua conta (25 por página).

07

Webhooks

Configure webhooks nas suas configurações para receber notificações HTTP quando os seus proofs mudarem de estado. O Proxae assina cada requisição com HMAC-SHA256.

proof.confirmed

Enviado quando um proof é confirmado na blockchain do Bitcoin (tipicamente 1-3h após a criação).

Payload do webhook
{
  "event": "proof.confirmed",
  "data": {
    "proof_id": "550e8400-...",
    "content_hash": "e3b0c44298fc1c14...",
    "status": "CONFIRMED",
    "bitcoin_block": 850123,
    "bitcoin_block_time": "2026-09-22T14:30:00Z"
  },
  "timestamp": "2026-09-22T15:00:00+00:00"
}

Verificação da assinatura

Cada requisição webhook inclui um header X-Proxae-Signature contendo o HMAC-SHA256 do corpo da requisição, assinado com o seu segredo webhook.

Headers
X-Proxae-Signature: <HMAC-SHA256 hex digest>
X-Proxae-Event: proof.confirmed
Content-Type: application/json
Exemplo de verificação (PHP)
$payload   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_PROXAE_SIGNATURE'];
$secret    = 'your_webhook_secret';

$expected = hash_hmac('sha256', $payload, $secret);

if (! hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}
08

Histórico de webhooks

Cada tentativa de entrega de webhook é registada. Consulte o histórico para diagnosticar falhas ou reenviar um webhook perdido.

GET /webhook-deliveries

Retorna a lista paginada de todas as entregas de webhooks da sua conta, as mais recentes primeiro.

Resposta — 200
{
  "data": [{
    "id": "a1b2c3d4-...",
    "webhook_endpoint_id": "...",
    "event": "proof.confirmed",
    "payload": { "proof_id": "...", ... },
    "status_code": 200,
    "success": true,
    "attempt": 1,
    "created_at": "2026-09-22T15:00:00Z"
  }],
  ...
}
POST /webhook-deliveries/{id}/replay

Reenvia um webhook colocando-o novamente na fila para o seu endpoint. Útil se o seu servidor estava indisponível durante a entrega inicial.

09

Rate limiting

As requisições API são limitadas por chave. O limite padrão é de 120 requisições por minuto.

Padrão 120 req/min
Headers X-RateLimit-Limit, X-RateLimit-Remaining
10

Erros

Code Descrição
401 Chave API em falta ou inválida.
404 Proof não encontrado.
422 Dados de requisição inválidos.
429 Limite de requisições excedido. Tente novamente mais tarde.
11

Quick start

cURL
# Criar um proof
curl -X POST https://proxae.com/api/v1/proofs \
  -H "X-API-Key: pxe_your_key" \
  -H "Content-Type: application/json" \
  -d '{"content_hash": "e3b0c442...b855"}'

# Verificar estado
curl https://proxae.com/api/v1/proofs/{proof_id}/status \
  -H "X-API-Key: pxe_your_key"