Programadores · API REST

Automatize a certificação de conteúdos digitais através da API

Capture · Sele · Verifique

A API REST da InstantProof permite certificar qualquer URL público de forma programática. Autentique-se com uma chave de API Bearer, envie um URL por POST e receba um certificado PDF assinado com o pacote de prova completo — o mesmo selo temporal RFC 3161 e a mesma assinatura Ed25519 da interface web.

Experimente já, sem precisar de conta.A sua primeira prova é gratuita · 10 € de crédito de boas-vindas ao confirmar o seu e-mail · Sem cartãoOferta de lançamento. O crédito também pode ser utilizado em capturas de páginas web ou na certificação de ficheiros.
RESTJSON sobre HTTPS
BearerAutenticação por chave de API
RFC 3161Selos temporais qualificados
Ilustração da certificação via API
  1. 01

    Capture

    Guarde uma página web, grave uma sessão de navegador ou certifique um ficheiro.

  2. 02

    Sele

    Um selo criptográfico e um selo temporal permitem detetar alterações posteriores.

  3. 03

    Verifique

    Qualquer pessoa pode verificar o pacote de prova de forma independente.

Prova digital. Simples.

Capture o que importa. Antes que mude.

Comece com 10 € de crédito de boas-vindas. Guarde um pacote de prova selado criptograficamente que pode descarregar e verificar.

Capture a sua primeira prova →

Pré-requisitos

1
Plano Pro ou superiorA API exige a subscrição Pro (funcionalidade api_access). Subscreva aqui.
2
Uma chave de APICrie uma em Definições → Chaves de API. Copie a chave de imediato — só é mostrada uma vez.
3
Um URL https:// para certificarA API certifica páginas web acessíveis publicamente. O URL tem de ser um endereço https:// válido.

Início rápido

Três passos para passar do zero a um certificado PDF assinado.

Passo 1 — Crie uma chave de API

Inicie sessão, aceda a Programador → Chaves de API e clique em Criar chave de API. Copie a chave — só é mostrada uma vez.

Passo 2 — Crie um certificado

Envie um pedido POST com o seu URL:

curl -X POST https://secure.instantproof.legal/api/v1/certificates \
  -H "Authorization: Bearer ip_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/page-to-certify"}'

Resposta 201 Created:

{
  "certificateId": "abc123…",
  "recordingId":   "def456…",
  "url":           "https://example.com/page-to-certify",
  "finalUrl":      "https://example.com/page-to-certify",
  "status":        "ready",
  "links": {
    "self":        "/api/v1/certificates/def456…",
    "certificate": "/api/v1/certificates/def456…/download"
  }
}

Passo 3 — Descarregue o certificado PDF

Siga o URL links.certificate com a sua chave de API. O servidor devolve um redirecionamento 302 para um URL de descarga pré-assinado:

curl -L \
  -H "Authorization: Bearer ip_live_xxxxxxxxxxxxxxxx" \
  "https://secure.instantproof.legal/api/v1/certificates/def456…/download" \
  -o certificate.pdf

O PDF descarregado é o mesmo certificado PDF assinado que a interface web produz, verificável em /certificate.html.

Referência da API

URL base: https://secure.instantproof.legal
Todos os endpoints devolvem JSON. Autenticação: Authorization: Bearer <key>.

POST /api/v1/certificates

Cria um novo certificado de site. A plataforma captura o URL num navegador headless, produz um registo de rede HAR e uma captura de ecrã, assina o manifesto com Ed25519 e ancora-o num selo temporal qualificado RFC 3161. A operação demora 10–60 segundos.

Corpo do pedido (JSON)

CampoTipoDescrição
urlstringobrigatórioUm URL https:// válido a certificar. Tem de ser acessível publicamente.

Resposta 201 Created

CampoTipoDescrição
certificateIdstringID do certificado legível (apresentado no PDF).
recordingIdstringUUID interno da gravação. Utilize-o nas chamadas seguintes à API.
urlstringO URL que enviou.
finalUrlstringO URL após eventuais redirecionamentos, tal como visto pelo navegador.
statusstring"ready" — o certificado fica imediatamente disponível.
links.selfstringCaminho para obter os metadados deste certificado.
links.certificatestringCaminho para descarregar o PDF. Requer autenticação.

Respostas de erro

EstadoerrorSignificado
400invalid_urlO campo url está em falta ou não é um endereço https:// válido.
400invalid_jsonO corpo do pedido não é JSON válido.
401invalid_api_keyCabeçalho Authorization em falta ou inválido.
402api_access_requiredA sua conta não tem o plano Pro. Subscrever.
403subscription_requiredOs certificados web exigem uma subscrição de tarifa fixa.
403insufficient_scopeA chave de API não tem o âmbito certificates:write.
413payload_too_largeO corpo do pedido excede 64 KB.
429quota_exceededQuota diária de capturas pela API atingida. É reposta todos os dias.
429rate_limitedDemasiados pedidos. Consulte o cabeçalho Retry-After.
429service_busyServiço de captura no limite da capacidade. Tente novamente após ~30 segundos.
502capture_failedO navegador não conseguiu carregar o URL.
502certification_failedA captura não produziu prova utilizável (p. ex., HAR vazio).

GET /api/v1/certificates/:recordingId

Obtém os metadados de um certificado criado anteriormente.

Parâmetros de caminho

ParâmetroDescrição
recordingIdobrigatórioO recordingId devolvido por POST /api/v1/certificates.

Resposta 200 OK

CampoTipoDescrição
certificateIdstringID do certificado legível.
recordingIdstringUUID interno da gravação.
typestringTipo de gravação (p. ex., "webcapture").
statusstring"ready" quando o certificado estiver disponível.
urlstringO URL que foi certificado.
createdAtstringData e hora de criação em ISO 8601.
linksobjectCaminhos self e certificate.

GET /api/v1/certificates/:recordingId/download

Descarrega o certificado PDF assinado. Devolve 302 Found — siga o redirecionamento para receber o ficheiro. Utilize curl -L ou requests.get(..., allow_redirects=True).

Autenticação

Todos os pedidos à API devem incluir:

Authorization: Bearer ip_live_xxxxxxxxxxxxxxxx

As chaves são criadas em Definições → Programador → Chaves de API. Uma chave autentica-se como a sua conta — trate-a como uma palavra-passe. Revogue-a de imediato em caso de fuga.

As chaves das contas em produção têm o prefixo ip_live_. O prefixo ajuda a identificá-las no código ou em ficheiros de ambiente.

Limites de pedidos e quotas

~30

Pedidos por minuto

30 pedidos/minuto de forma sustentada (pico: 30). Se exceder, recebe 429 rate_limited com um cabeçalho Retry-After.

Diária

Quota diária de capturas

O plano Pro concede um número fixo de criações de certificados por dia. A quota é reposta todos os dias. Se a exceder, recebe 429 quota_exceeded.

64 KB

Limite do corpo do pedido

O corpo JSON do pedido não pode exceder 64 KB. Na prática, um URL fica muito abaixo deste limite.

Exemplos de código

Python

import requests

API_KEY = "ip_live_xxxxxxxxxxxxxxxx"
BASE    = "https://secure.instantproof.legal"

# Criar um certificado
resp = requests.post(
    f"{BASE}/api/v1/certificates",
    json={"url": "https://example.com"},
    headers={"Authorization": f"Bearer {API_KEY}"},
)
resp.raise_for_status()
data = resp.json()
recording_id = data["recordingId"]

# Descarregar o PDF
pdf = requests.get(
    f"{BASE}/api/v1/certificates/{recording_id}/download",
    headers={"Authorization": f"Bearer {API_KEY}"},
    allow_redirects=True,
)
pdf.raise_for_status()
with open("certificate.pdf", "wb") as f:
    f.write(pdf.content)
print(f"Certificate saved ({len(pdf.content)} bytes)")

Node.js (fetch)

const API_KEY = process.env.INSTANTPROOF_API_KEY;
const BASE    = "https://secure.instantproof.legal";

// Criar um certificado
const res = await fetch(`${BASE}/api/v1/certificates`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://example.com" }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const { recordingId, links } = await res.json();

// Descarregar o PDF
const pdf = await fetch(`${BASE}${links.certificate}`, {
  headers: { "Authorization": `Bearer ${API_KEY}` },
  redirect: "follow",
});
const buffer = Buffer.from(await pdf.arrayBuffer());
require("fs").writeFileSync("certificate.pdf", buffer);

Shell (curl)

# Defina a sua chave
export INSTANTPROOF_API_KEY="ip_live_xxxxxxxxxxxxxxxx"

# Criar
CERT=$(curl -sf -X POST https://secure.instantproof.legal/api/v1/certificates \
  -H "Authorization: Bearer $INSTANTPROOF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}')

echo "$CERT" | python3 -m json.tool

RECORDING_ID=$(echo "$CERT" | python3 -c "import sys,json; print(json.load(sys.stdin)['recordingId'])")

# Descarregar
curl -sfL \
  -H "Authorization: Bearer $INSTANTPROOF_API_KEY" \
  "https://secure.instantproof.legal/api/v1/certificates/$RECORDING_ID/download" \
  -o certificate.pdf

ls -lh certificate.pdf

Perguntas frequentes

Quanto tempo demora a criação de um certificado?

Normalmente 10–60 segundos, consoante o tempo de carregamento da página. O pedido POST fica bloqueado até o certificado estar pronto — não é necessário fazer polling.

A API suporta certificados de ficheiros (carregamento de PDF, imagens)?

A API atual suporta apenas a certificação de sites (URL). O carregamento de ficheiros está disponível na interface web em secure.instantproof.legal/certificates/new.

Posso verificar um certificado criado através da API?

Sim. O PDF produzido pela API é idêntico ao criado através da interface web. Arraste-o para instantproof.legal/certificate.html para verificar a assinatura Ed25519 e a cadeia do selo temporal RFC 3161.

O que acontece se o URL estiver inacessível?

O serviço de captura devolve um erro 502 capture_failed. A sua quota diária não é consumida.

Os certificados criados pela API aparecem no painel web?

Sim. Todos os certificados criados através da API aparecem no seu painel Certificados, em Os meus certificados de sites, juntamente com os certificados criados na interface web.