@4signer/signer-connector-sdk

SDK oficial JavaScript para orquestrar assinatura de documentos (PDF/XML) com a Signer API:

• fluxo local via Desktop Agent (A1/A3 instalados)
• fluxo nuvem via provider credential
• fallback automático (certificateMode: auto)

Instalação

npm install @4signer/signer-connector-sdk

Uso rápido

import { createSignerConnector } from '@4signer/signer-connector-sdk';

const connector = createSignerConnector({
  apiBaseUrl: 'https://seu-saas.com/api/v1',
  bearerToken: process.env.SIGNER_API_TOKEN, // token da account
  accountSlug: 'clinica-abc', // opcional se backend inferir pela conta do token
  localAgentBaseUrl: 'http://127.0.0.1:9876',
  telemetryEndpoint: 'https://seu-saas.com/api/v1/telemetry/logs',
  sdkVersion: '1.0.0',
});

const result = await connector.sign({
  documentId: 'prescricao-0001',
  documentType: 'pdf', // pdf | xml
  xmlProfile: 'fiscal', // fiscal | diploma (quando documentType=xml)
  xmlPolicy: 'nfe-4.00', // opcional para XML
  certificateMode: 'auto', // auto | local | cloud
  documentContentBase64: pdfBase64,
  providerHint: 'birdid', // usado quando cloud
  providerCredentialId: 10, // preferencial quando cloud
  metadata: { source: 'prontuario' },
  requestOptions: { certificateId: 'abc' }, // usado no fluxo local
});

console.log(result.status);

Eventos de fluxo

• flow:started
• flow:awaiting_approval
• flow:fallback_cloud
• flow:signed
• flow:failed
• agent:not_found

const unsub = connector.on('flow:failed', (event) => {
  console.error('Falha de assinatura', event);
});

Erros

Todos os erros de SDK/API são SignerConnectorError:

try {
  await connector.sign(payload);
} catch (error) {
  if (error.name === 'SignerConnectorError') {
    console.error(error.code, error.message, error.recoverable, error.details);
  }
}

Recomendações para produção

• Gere token Sanctum por account, com expiração curta.
• Se usar local, mantenha Desktop Agent em http://127.0.0.1:9876.
• Em cloud, trate estado pending_approval e faça polling com getStatus.
• Baixe o arquivo assinado apenas quando status === 'signed'.
• Envie metadata com document_id do parceiro para rastreabilidade.

Exemplos

• examples/node-cloud-sign.mjs
• examples/browser-cloud.html
• examples/browser-local-agent.html

Executar exemplo Node com XML

SIGNER_API_BASE_URL="http://127.0.0.1:8000/api/v1" \
SIGNER_API_TOKEN="seu_token" \
SIGNER_PROVIDER_HINT="serproid" \
SIGNER_PROVIDER_CREDENTIAL_ID="12" \
SIGNER_DOCUMENT_TYPE="xml" \
SIGNER_XML_PROFILE="diploma" \
SIGNER_XML_POLICY="diploma-icpbrasil-xades-1.0" \
SIGNER_XML_PATH="/caminho/para/documento.xml" \
node examples/node-cloud-sign.mjs

API pública

• createSignerConnector(options)
• createSignerConnectorTelemetry(options)
• SignerConnector
• SignerConnectorError