ONRCPN Signature SDK

SDK TypeScript para integrar com a API de assinatura do ONRCPN/IdRC.

Requisitos

• Node.js 18+
• npm 9+

Instalação e build

npm install
npm run build

Releases (npm)

Os scripts abaixo fazem 3 etapas automaticamente: build, atualização de versão semântica e publicação no npm.

npm run release:patch
npm run release:minor
npm run release:major

Quando usar cada comando:

• npm run release:patch: para correções e ajustes internos sem adicionar nova funcionalidade (ex.: bugfix).
• npm run release:minor: para novas funcionalidades compatíveis com versões anteriores (sem quebrar integrações existentes).
• npm run release:major: para mudanças que quebram compatibilidade (breaking changes) e exigem ajustes de quem consome o SDK.

Uso básico

import { OnrcpnSignatureClient } from "@onrcpn/signature-sdk";

const client = new OnrcpnSignatureClient({
  environment: "hmlg",
  apiVersion: "1",
});

const result = await client.signPdf({
  accessToken: "token",
  pdf: pdfBuffer,
  fileName: "documento.pdf",
  options: {
    stamp_enable: true,
    stamp_QR_code_enable: false,
    stamp_message: "Documento assinado digitalmente",
    pades_allow_further_sign: true,
  },
});

console.log(result.signedPdfBuffer);
console.log(result.verificationUrl);

Tabela de options (SignPdfOptions)

Campos gerais da assinatura

| Option | Valor (tipo) | Objetivo | | ------------------------ | ------------------------------ | ---------------------------------------------------------- | | field_name | string | Nome do campo de assinatura no PDF. | | sign_reason | string | Motivo da assinatura. | | sign_contact_info | string | Informação de contato vinculada à assinatura. | | sign_user_auth_time | number | Timestamp do instante de autenticação do usuário. | | send_email | boolean \| "True" \| "False" | Indica se deve enviar e-mail no fluxo de assinatura. | | attach_signed_document | boolean \| "True" \| "False" | Indica se o documento assinado deve ser anexado ao e-mail. | | extra_information | string | Informação adicional para contexto/auditoria. |

Campos de carimbo visual

| Option | Valor (tipo) | Objetivo | | --------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------- | | stamp_enable | boolean \| "True" \| "False" | Habilita o carimbo visual no PDF assinado. | | stamp_QR_code_enable | boolean \| "True" \| "False" | Habilita QR Code no carimbo. | | stamp_font_family | "Noto Sans" | Define a família de fonte do carimbo (conforme doc atual). | | stamp_font_size | number \| \${number}` | Define o tamanho da fonte do carimbo. | |stamp_border_width |number | `${number}` | Define a espessura da borda do carimbo. | |stamp_inner_scaling |"none" | "stretch-fill" | "stretch-to-fit" | "shrink-to-fit"| Controla o ajuste interno do conteúdo no carimbo. | |stamp_box_margins |string | Define margens da caixa do carimbo. | |stamp_text_box_margins |string | Define margens da área de texto do carimbo. | |stamp_text_box_vertical_align |"bottom" | "mid" | "top" | Define alinhamento vertical do texto no carimbo. | |stamp_text_box_horizontal_align|"left" | "mid" | "right" | Define alinhamento horizontal do texto no carimbo. | |stamp_box_size |string | Define o tamanho da caixa do carimbo. | |stamp_qr_code_position |"right" | "left" | "top" | "bottom" | Define a posição do QR Code no carimbo. | |stamp_timestamp_format |string | Define formato textual de data/hora exibido no carimbo. | |stamp_align_by |"center" | "left" | Define a referência de alinhamento do carimbo na página. | |stamp_align_x |number | `${number}` | Define deslocamento horizontal do carimbo. | |stamp_align_y |number | `${number}` | Define deslocamento vertical do carimbo. | |stamp_background_rgba |string | Define cor de fundo do carimbo em formato RGBA. | |stamp_page |number | `${number}` | Define a página do PDF onde o carimbo será aplicado. | |stamp_message |string | Define a mensagem principal exibida no carimbo. | |stamp_url |string | Define URL exibida no carimbo. | |pades_allow_further_sign |boolean | "True" | "False" | Indica se permite assinaturas PAdES adicionais após esta assinatura. | |stamp_vertical_text_enable |boolean | "True" | "False"` | Habilita texto vertical no carimbo. |

Imagem do carimbo

| Option | Valor (tipo) | Objetivo | | -------------------------- | -------------------------------------------- | -------------------------------------------------------------- | | stamp_image | string \| Buffer \| ReadStream \| Readable | Define a imagem do carimbo (caminho, buffer ou stream). | | stamp_image_filename | string | Define nome de arquivo enviado para a imagem do carimbo. | | stamp_image_content_type | string | Define Content-Type da imagem do carimbo (ex.: image/png). |

Observação: os tipos e valores permitidos acima seguem exatamente o contrato tipado do SDK. Regras de formato/intervalo específicas da API (ex.: padrão de margens, tamanho e timestamp) devem seguir a documentação oficial do ONRCPN.

Endpoints cobertos

• POST /api/signer/pdf/{version?}/sign
• POST /api/signer/pdf/{version?}/sign/hash/sha256/{hash}
• POST /api/signer/pdf/{version?}/sign/hash/sha512/{hash}
• POST /api/logs/search
• GET /api/logs/summary

1) Assinar PDF completo

Endpoint: POST /api/signer/pdf/{version?}/sign

Use quando você já tem o arquivo PDF e quer receber o PDF assinado.

const signed = await client.signPdf({
  accessToken: "token",
  pdf: pdfBuffer,
  fileName: "contrato.pdf",
});

console.log(signed.signedPdfBuffer); // Buffer do PDF assinado
console.log(signed.verificationUrl); // URL de verificação (se disponível)

2) Assinar hash SHA-256

Endpoint: POST /api/signer/pdf/{version?}/sign/hash/sha256/{hash}

Use quando seu fluxo trabalha com hash e você precisa da assinatura PKCS#7.

const hash256 = await client.signHashSha256({
  accessToken: "token",
  hashValue: "abc123...",
});

console.log(hash256.pkcs7); // Assinatura em PKCS#7

3) Assinar hash SHA-512

Endpoint: POST /api/signer/pdf/{version?}/sign/hash/sha512/{hash}

Mesmo caso do SHA-256, mas com algoritmo SHA-512.

const hash512 = await client.signHashSha512({
  accessToken: "token",
  hashValue: "def456...",
});

console.log(hash512.pkcs7); // Assinatura em PKCS#7

4) Buscar logs com filtros

Endpoint: POST /api/logs/search

Use para consultar logs com paginação, ordenação e filtros.

const logs = await client.searchLogs({
  accessToken: "token",
  page: 1,
  page_size: 10,
  sort_by: "id",
  sort_order: "desc",
});

console.log(logs.total_count_in_db);
console.log(logs.logs);

5) Resumo de logs

Endpoint: GET /api/logs/summary

Use para obter um resumo simplificado dos logs.

const summary = await client.getLogsSummary({
  accessToken: "token",
});

console.log(summary); // Ex.: [{ id, hmac }]