API do RegistrarObra

Authorization: Bearer ro_live_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

const BASE = "https://auth.registrarobra.com.br/functions/v1";

export async function api<T>(caminho: string, init: RequestInit = {}): Promise<T> {
  const resposta = await fetch(`${BASE}/${caminho}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.REGISTRAROBRA_TOKEN}`,
      "Content-Type": "application/json",
      ...init.headers,
    },
  });
  const corpo = await resposta.json();
  if (!resposta.ok) throw Object.assign(new Error(corpo.error), { status: resposta.status, corpo });
  return corpo as T;
}

curl -s https://auth.registrarobra.com.br/functions/v1/api-health-check \
  -H "Authorization: Bearer $REGISTRAROBRA_TOKEN"

const saude = await api<{ credits: { available: number } }>("api-health-check");
console.log(`Créditos disponíveis: ${saude.credits.available}`);

{
  "ok": true,
  "safe_test": true,
  "side_effects": false,
  "server_time": "2026-09-19T12:00:00.000Z",
  "integration": {
    "id": "5b0c2f4e-3a1d-4c7b-9e8f-1a2b3c4d5e6f",
    "name": "Editora Exemplo",
    "status": "active",
    "key_prefix": "ro_live_01234567",
    "scopes": ["health:read", "bulk:create", "bulk:read", "registration:read", "artifact:read"],
    "rate_limit_per_minute": 30,
    "webhook_configured": true,
    "last_used_at": "2026-09-19T11:58:00.000Z"
  },
  "credits": { "available": 42 },
  "checks": { "authentication": "ok", "scope": "health:read", "webhook": "configured" },
  "next_recommended_calls": ["POST /api-submit-bulk-registration-job", "GET /api-get-bulk-job", "GET /api-get-registration"]
}

curl -s -X POST https://auth.registrarobra.com.br/functions/v1/api-submit-bulk-registration-job \
  -H "Authorization: Bearer $REGISTRAROBRA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "external_job_id": "pedido-2026-0042",
    "name": "Álbum Cerrado",
    "work_type": "musica",
    "description": "Faixas do álbum Cerrado.",
    "consent": {
      "accepted_terms": true,
      "accepted_privacy": true,
      "acknowledged_original_file_responsibility": true,
      "acknowledged_immediate_execution_and_irreversibility": true
    },
    "authors": [{
      "full_name": "Maria da Silva",
      "cpf": "529.982.247-25",
      "email": "maria@exemplo.com.br",
      "nationality": "Brasileira",
      "cep": "70610-420",
      "state": "DF",
      "city": "Brasília",
      "neighborhood": "Asa Sul",
      "street": "SQS 308 Bloco A",
      "number": "101"
    }],
    "items": [{
      "title": "Chuva de Outubro",
      "file_name": "chuva-de-outubro.wav",
      "file_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "file_size": 48213996
    }]
  }'

import { stat } from "node:fs/promises";
import { basename } from "node:path";

const caminho = "/obras/chuva-de-outubro.wav";
const impressaoDigitalDoArquivo: string = obterImpressaoDigital(caminho); // do seu sistema
const lote = await api<{ job_id: string; idempotent?: boolean }>("api-submit-bulk-registration-job", {
  method: "POST",
  body: JSON.stringify({
    external_job_id: "pedido-2026-0042",
    work_type: "musica",
    consent: {
      accepted_terms: true,
      accepted_privacy: true,
      acknowledged_original_file_responsibility: true,
      acknowledged_immediate_execution_and_irreversibility: true,
    },
    authors: [{
      full_name: "Maria da Silva",
      cpf: "529.982.247-25",
      nationality: "Brasileira",
      cep: "70610-420",
      state: "DF",
      city: "Brasília",
      neighborhood: "Asa Sul",
      street: "SQS 308 Bloco A",
      number: "101",
    }],
    items: [{
      title: "Chuva de Outubro",
      file_name: basename(caminho),
      file_hash: impressaoDigitalDoArquivo,
      file_size: (await stat(caminho)).size,
    }],
  }),
});
console.log(lote.job_id);

{
  "success": true,
  "queued": true,
  "job_id": "0f8e7d6c-5b4a-4938-8271-605f4e3d2c1b",
  "external_job_id": "pedido-2026-0042",
  "total_items": 1,
  "status": "queued"
}

curl -s "https://auth.registrarobra.com.br/functions/v1/api-get-bulk-job?external_job_id=pedido-2026-0042" \
  -H "Authorization: Bearer $REGISTRAROBRA_TOKEN"

const { job, items } = await api<{ job: { status: string }; items: Array<{ title: string; status: string; registration_id: string | null }> }>(
  `api-get-bulk-job?job_id=${lote.job_id}`,
);
for (const item of items) console.log(item.title, item.status, item.registration_id);

{
  "integration_id": "5b0c2f4e-3a1d-4c7b-9e8f-1a2b3c4d5e6f",
  "job": {
    "id": "0f8e7d6c-5b4a-4938-8271-605f4e3d2c1b",
    "name": "Álbum Cerrado",
    "status": "completed",
    "total_items": 1,
    "completed_items": 1,
    "failed_items": 0,
    "created_registrations": 1,
    "external_job_id": "pedido-2026-0042",
    "callback_attempts": 1,
    "callback_last_status": 200
  },
  "items": [{
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "position": 0,
    "title": "Chuva de Outubro",
    "file_name": "chuva-de-outubro.wav",
    "file_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "file_size": 48213996,
    "status": "completed",
    "error_message": null,
    "registration_id": "3c9d8e7f-6a5b-4c4d-9e3f-2a1b0c9d8e7f"
  }]
}

curl -s "https://auth.registrarobra.com.br/functions/v1/api-get-registration?registration_id=3c9d8e7f-6a5b-4c4d-9e3f-2a1b0c9d8e7f" \
  -H "Authorization: Bearer $REGISTRAROBRA_TOKEN"

const { registration, artifacts } = await api<{
  registration: { status: string; blockchain_tx_id: string | null };
  artifacts: { certificate: { available: boolean } };
}>(`api-get-registration?registration_id=${registrationId}`);

const bloco = registration.blockchain_tx_id?.match(/^bitcoin-h:(\d+)/)?.[1];
console.log(registration.status, artifacts.certificate.available, bloco ? `bloco ${bloco}` : "âncora aguardando");

{
  "integration_id": "5b0c2f4e-3a1d-4c7b-9e8f-1a2b3c4d5e6f",
  "registration": {
    "id": "3c9d8e7f-6a5b-4c4d-9e3f-2a1b0c9d8e7f",
    "title": "Chuva de Outubro",
    "description": "Faixas do álbum Cerrado.",
    "authors": "Maria da Silva",
    "work_type": "musica",
    "status": "concluido",
    "payment_status": "paid",
    "product_type": "registro",
    "processing_step": "done",
    "file_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "blockchain_tx_id": "bitcoin-h:915000",
    "ficha_hash": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
    "ficha_blockchain_tx_id": "bitcoin-h:915000",
    "created_at": "2026-09-19T12:00:05.000Z",
    "paid_at": "2026-09-19T12:00:06.000Z",
    "completed_at": "2026-09-19T12:07:41.000Z",
    "bulk_job_id": "0f8e7d6c-5b4a-4938-8271-605f4e3d2c1b"
  },
  "artifacts": {
    "certificate": { "available": true, "endpoint": "https://…/functions/v1/api-get-registration-artifact?registration_id=…&artifact=certificate" },
    "ficha": { "available": true, "endpoint": "https://…/functions/v1/api-get-registration-artifact?registration_id=…&artifact=ficha" }
  }
}

curl -s "https://auth.registrarobra.com.br/functions/v1/api-list-registrations?limit=20" \
  -H "Authorization: Bearer $REGISTRAROBRA_TOKEN"

let before: string | null = null;
do {
  const pagina = await api<{ registrations: Array<{ id: string; title: string; status: string }>; next_before: string | null }>(
    `api-list-registrations?limit=50${before ? `&before=${encodeURIComponent(before)}` : ""}`,
  );
  for (const registro of pagina.registrations) console.log(registro.id, registro.status, registro.title);
  before = pagina.next_before;
} while (before);

{
  "integration_id": "5b0c2f4e-3a1d-4c7b-9e8f-1a2b3c4d5e6f",
  "registrations": [{
    "id": "3c9d8e7f-6a5b-4c4d-9e3f-2a1b0c9d8e7f",
    "title": "Chuva de Outubro",
    "work_type": "musica",
    "status": "concluido",
    "payment_status": "paid",
    "product_type": "registro",
    "file_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "created_at": "2026-09-19T12:00:05.000Z",
    "paid_at": "2026-09-19T12:00:06.000Z",
    "completed_at": "2026-09-19T12:07:41.000Z",
    "bulk_job_id": "0f8e7d6c-5b4a-4938-8271-605f4e3d2c1b"
  }],
  "next_before": null
}

curl -sL "https://auth.registrarobra.com.br/functions/v1/api-get-registration-artifact?registration_id=3c9d8e7f-6a5b-4c4d-9e3f-2a1b0c9d8e7f&artifact=certificate&return=redirect" \
  -H "Authorization: Bearer $REGISTRAROBRA_TOKEN" \
  -o certificado.pdf

import { writeFile } from "node:fs/promises";

const documento = await api<{ url: string; file_name: string }>(
  `api-get-registration-artifact?registration_id=${registrationId}&artifact=certificate`,
);
const pdf = await fetch(documento.url);
await writeFile(documento.file_name, Buffer.from(await pdf.arrayBuffer()));

{
  "integration_id": "5b0c2f4e-3a1d-4c7b-9e8f-1a2b3c4d5e6f",
  "registration_id": "3c9d8e7f-6a5b-4c4d-9e3f-2a1b0c9d8e7f",
  "artifact": "certificate",
  "file_name": "certificado-3C9D8E7F.pdf",
  "content_type": "application/pdf",
  "url": "https://…/storage/v1/object/sign/…",
  "expires_in_seconds": 120
}

curl -s "https://auth.registrarobra.com.br/functions/v1/api-verify-hash?file_hash=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" \
  -H "Authorization: Bearer $REGISTRAROBRA_TOKEN"

const verificacao = await api<{ found: boolean; registered_at?: string; anchor?: { confirmed: boolean } }>(
  `api-verify-hash?file_hash=${impressaoDigitalDoArquivo}`,
);
console.log(verificacao.found ? `registrado em ${verificacao.registered_at}` : "sem registro concluído");

{
  "integration_id": "5b0c2f4e-3a1d-4c7b-9e8f-1a2b3c4d5e6f",
  "found": true,
  "matched": "file",
  "registered_at": "2026-09-19T12:00:05.000Z",
  "title": "Chuva de Outubro",
  "authors_declared": "Maria da Silva",
  "work_type": "musica",
  "anchor": {
    "confirmed": true,
    "bitcoin_block_height": 915000,
    "bitcoin_block_hash": "00000000000000000001a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f7",
    "bitcoin_block_time": "2026-09-19T14:31:02.000Z"
  },
  "verification_url": "https://registrarobra.com.br/verificar?hash=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
}

{
  "event": "bulk_job.completed",
  "integration_id": "5b0c2f4e-3a1d-4c7b-9e8f-1a2b3c4d5e6f",
  "external_job_id": "pedido-2026-0042",
  "job": {
    "id": "0f8e7d6c-5b4a-4938-8271-605f4e3d2c1b",
    "name": "Álbum Cerrado",
    "status": "completed",
    "total_items": 1,
    "completed_items": 1,
    "failed_items": 0,
    "created_registrations": 1
  },
  "items": [{
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "position": 0,
    "title": "Chuva de Outubro",
    "status": "completed",
    "error_message": null,
    "registration_id": "3c9d8e7f-6a5b-4c4d-9e3f-2a1b0c9d8e7f",
    "file_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "completed_at": "2026-09-19T12:00:06.000Z"
  }],
  "delivered_at": "2026-09-19T12:00:07.000Z",
  "delivery_id": "c0ffee00-1234-4abc-9def-001122334455"
}

import { createHmac, timingSafeEqual } from "node:crypto";

export function assinaturaValida(corpoCru: string, cabecalho: string | undefined, segredo: string, agora = Date.now()) {
  const partes = Object.fromEntries((cabecalho ?? "").split(",").map((parte) => {
    const [chave, ...resto] = parte.split("=");
    return [chave.trim(), resto.join("=").trim()];
  }));
  const t = Number(partes.t);
  if (!Number.isSafeInteger(t) || !/^[0-9a-f]{64}$/.test(partes.v1 ?? "")) return false;
  if (Math.abs(agora / 1000 - t) > 300) return false;
  const esperado = createHmac("sha256", segredo).update(`${t}.${corpoCru}`).digest("hex");
  return timingSafeEqual(Buffer.from(esperado), Buffer.from(partes.v1));
}

import express from "express";

const app = express();
app.post("/webhooks/registrarobra", express.text({ type: "application/json" }), (req, res) => {
  if (!assinaturaValida(req.body, req.header("x-registrarobra-signature"), process.env.REGISTRAROBRA_WEBHOOK_SECRET!)) {
    return res.sendStatus(401);
  }
  const evento = JSON.parse(req.body);
  res.sendStatus(200); // responda rápido; processe depois
  void processarLote(evento.job.id, evento.items);
});

{
  "error": "Lote invalido",
  "details": {
    "issues": [
      { "field": "items[0].file_hash", "message": "SHA-256 em hexadecimal minúsculo (64 caracteres)" },
      { "field": "authors[1].email", "message": "obrigatório para coautores" }
    ]
  }
}

Você vai me ajudar a integrar meu sistema com a API do RegistrarObra.
Leia a documentação completa em https://registrarobra.com.br/llms-full.txt
e a especificação OpenAPI em https://registrarobra.com.br/openapi.yaml.
Regras que não podem ser quebradas:
- O arquivo da obra nunca é enviado à API; siga a documentação para o formato de cada campo.
- O token da API fica só no servidor, em variável de ambiente; nunca no código do navegador nem em logs.
- Todo lote leva external_job_id, para não gastar crédito duas vezes num reenvio.
- Verifique a assinatura de todo webhook antes de usar o corpo.
- Não prometa ao usuário final confirmação na blockchain Bitcoin em minutos: o certificado costuma sair em até 15 minutos; a âncora confirma em algumas horas.
- O RegistrarObra comprova anterioridade; não é registro público e a autoria é declarada, não verificada.
- Não há endpoint que apague registro, e crédito não se compra pela API.