4signer | Documentação API e Connector

Autenticação

Toda chamada da API exige token da conta no header Authorization no formato Bearer.

Onde obter o token da conta

Acesse o painel da 4signer com usuário administrador.
Abra Acesso de API.
Crie ou copie o token da conta.
Use no backend quando aplicável ou no Connector JS para fluxos de assinatura no cliente, sempre com escopo controlado por conta/ambiente.

Header	Obrigatório	Descrição
Authorization	Sim	`Bearer TOKEN_DA_ACCOUNT`
Accept	Sim	`application/json`
X-Account-Slug	Opcional	Use quando sua operação exigir contexto explícito de conta.

Authorization: Bearer TOKEN_DA_ACCOUNT
Accept: application/json
X-Account-Slug: conta-opcional

Segurança: trate o token como segredo, armazene em variável de ambiente e faça rotação imediata em caso de exposição.

Agent Desktop

O Agent Desktop e instalado na maquina da pessoa que assina. Ele conecta com certificados locais (A3 token/cartao e stores do sistema), executa a assinatura no proprio dispositivo e devolve para a API somente a prova criptografica para finalizar o PDF/XML.

Tela do Agent

4signer Agent Desktop

● ONLINE Local API: http://127.0.0.1:9876

certificates: A3 Token SafeNet (2 encontrados)

provider: pkcs11 / windows_store

last_action: assinatura XML diploma concluida

Download por sistema operacional

Instale conforme o sistema do assinante.

Windows .exe / .msi macOS .dmg / .app Linux AppImage / .deb

Frontend chama o Connector com certificateMode: 'local'.
Connector cria sessão na API e solicita bootstrap local.
Agent assina localmente e devolve prova para API.
API finaliza status e disponibiliza o arquivo assinado.

PDF

Endpoint base: POST /api/v1/signatures/pdf

Campo	Obrigatório	Descrição
signature_method	Sim	remote_provider \| local_pfx \| stored_a1
processing_mode	Sim	remote_provider=async, local_pfx/stored_a1=sync
pdf	Sim	Arquivo PDF
provider	Cloud	Provider para assinatura em nuvem
pfx + pfx_password	local_pfx	Certificado A1 em arquivo
request_options	Opcional	Opções adicionais de assinatura (array)

Para provider=vidaas, informe request_options[vidaas][login_hint] e escolha o modo em request_options[vidaas][auth_mode]: push (padrão) ou qrcode.

Para provider=birdid, escolha o modo com request_options[birdid][auth_mode]: authorization_code (padrão) ou push.

curl -X POST "https://4signer.com/api/v1/signatures/pdf" \
  -H "Authorization: Bearer TOKEN_DA_ACCOUNT" \
  -H "Accept: application/json" \
  -F "signature_method=remote_provider" \
  -F "provider=vidaas" \
  -F "processing_mode=async" \
  -F "pdf=@/tmp/documento.pdf" \
  -F "request_options[vidaas][auth_mode]=push" \
  -F "request_options[vidaas][login_hint]=12345678901"

curl -X POST "https://4signer.com/api/v1/signatures/pdf" \
  -H "Authorization: Bearer TOKEN_DA_ACCOUNT" \
  -H "Accept: application/json" \
  -F "signature_method=remote_provider" \
  -F "provider=vidaas" \
  -F "processing_mode=async" \
  -F "pdf=@/tmp/documento.pdf" \
  -F "request_options[vidaas][auth_mode]=qrcode" \
  -F "request_options[vidaas][login_hint]=12345678901"

curl -X POST "https://4signer.com/api/v1/signatures/pdf" \
  -H "Authorization: Bearer TOKEN_DA_ACCOUNT" \
  -H "Accept: application/json" \
  -F "signature_method=remote_provider" \
  -F "provider=birdid" \
  -F "processing_mode=async" \
  -F "pdf=@/tmp/documento.pdf" \
  -F "request_options[birdid][auth_mode]=authorization_code"

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

const connector = createSignerConnector({
  apiBaseUrl: 'https://4signer.com/api/v1',
  bearerToken: 'TOKEN_DA_ACCOUNT'
})

const result = await connector.sign({
  documentId: 'pdf-vidaas-001',
  documentType: 'pdf',
  certificateMode: 'cloud',
  providerHint: 'vidaas',
  documentContentBase64: pdfBase64,
  requestOptions: {
    vidaas: {
      auth_mode: 'qrcode', // ou 'push'
      login_hint: '12345678901'
    }
  }
})

console.log(result.status)

PDF simples

Assinatura básica sem customização visual.

curl -X POST "https://4signer.com/api/v1/signatures/pdf" \
  -H "Authorization: Bearer TOKEN_DA_ACCOUNT" \
  -H "Accept: application/json" \
  -F "signature_method=local_pfx" \
  -F "processing_mode=sync" \
  -F "pdf=@/tmp/documento.pdf" \
  -F "pfx=@/tmp/certificado.pfx" \
  -F "pfx_password=SENHA"

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

const connector = createSignerConnector({
  apiBaseUrl: 'https://4signer.com/api/v1',
  bearerToken: 'TOKEN_DA_ACCOUNT'
})

const result = await connector.sign({
  documentId: 'pdf-simple-001',
  documentType: 'pdf',
  certificateMode: 'local',
  documentContentBase64: pdfBase64
})

console.log(result.status)

PDF com aparência

Exemplo com request_options para assinatura visual, incluindo imagem e posicionamento no PDF.

curl -X POST "https://4signer.com/api/v1/signatures/pdf" \
  -H "Authorization: Bearer TOKEN_DA_ACCOUNT" \
  -F "signature_method=local_pfx" \
  -F "processing_mode=sync" \
  -F "pdf=@/tmp/documento.pdf" \
  -F "pfx=@/tmp/certificado.pfx" \
  -F "pfx_password=SENHA" \
  -F "request_options[appearance][enabled]=true" \
  -F "request_options[appearance][page]=1" \
  -F "request_options[appearance][x]=100" \
  -F "request_options[appearance][y]=120" \
  -F "request_options[appearance][width]=180" \
  -F "request_options[appearance][height]=60" \
  -F "request_options[appearance][image_base64]=iVBORw0KGgoAAA..."

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

const connector = createSignerConnector({
  apiBaseUrl: 'https://4signer.com/api/v1',
  bearerToken: 'TOKEN_DA_ACCOUNT'
})

const result = await connector.sign({
  documentId: 'pdf-visible-001',
  documentType: 'pdf',
  certificateMode: 'local',
  documentContentBase64: pdfBase64,
  requestOptions: {
    use_visible_signature: true,
    appearance: {
      enabled: true,
      page: 1,
      x: 100,
      y: 120,
      width: 180,
      height: 60,
      image_base64: signatureImageBase64
    }
  }
})

console.log(result.status)

x, y, width e height controlam a caixa da aparência na página. Troque image_base64 para usar outra imagem de assinatura.

PDF sem aparência

Assinatura invisível com validade criptográfica.

curl -X POST "https://4signer.com/api/v1/signatures/pdf" \
  -H "Authorization: Bearer TOKEN_DA_ACCOUNT" \
  -H "Accept: application/json" \
  -F "signature_method=local_pfx" \
  -F "processing_mode=sync" \
  -F "pdf=@/tmp/documento.pdf" \
  -F "pfx=@/tmp/certificado.pfx" \
  -F "pfx_password=SENHA" \
  -F "request_options[use_visible_signature]=0"

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

const connector = createSignerConnector({
  apiBaseUrl: 'https://4signer.com/api/v1',
  bearerToken: 'TOKEN_DA_ACCOUNT'
})

const result = await connector.sign({
  documentId: 'pdf-invisible-001',
  documentType: 'pdf',
  certificateMode: 'local',
  documentContentBase64: pdfBase64,
  requestOptions: {
    use_visible_signature: false
  }
})

console.log(result.status)

PDF com A1

local_pfx e envio de arquivo PFX (endpoint direto da API). Para fluxo em nuvem no Connector JS, use certificateMode: 'cloud' com providerHint.

A1 via arquivo PFX (local_pfx)

curl -X POST "https://4signer.com/api/v1/signatures/pdf" \
  -H "Authorization: Bearer TOKEN_DA_ACCOUNT" \
  -F "signature_method=local_pfx" \
  -F "processing_mode=sync" \
  -F "pdf=@/tmp/documento.pdf" \
  -F "pfx=@/tmp/certificado-a1.pfx" \
  -F "pfx_password=SENHA_CERTIFICADO"

// local_pfx via arquivo e direto no endpoint da API.
// No Connector JS nao ha upload de arquivo PFX.
// Para fluxo local no cliente, use certificateMode='local' (Agent Desktop):
const result = await connector.sign({
  documentId: 'pdf-a1-pfx-equivalente',
  documentType: 'pdf',
  certificateMode: 'local',
  documentContentBase64: pdfBase64
})

A1 credencial cadastrada (stored_a1)

curl -X POST "https://4signer.com/api/v1/signatures/pdf" \
  -H "Authorization: Bearer TOKEN_DA_ACCOUNT" \
  -F "signature_method=stored_a1" \
  -F "processing_mode=sync" \
  -F "pdf=@/tmp/documento.pdf"

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

const connector = createSignerConnector({
  apiBaseUrl: 'https://4signer.com/api/v1',
  bearerToken: 'TOKEN_DA_ACCOUNT'
})

// Equivalente do stored_a1 no Connector JS:
const result = await connector.sign({
  documentId: 'pdf-a1-stored-001',
  documentType: 'pdf',
  certificateMode: 'cloud',
  documentContentBase64: pdfBase64
})

console.log(result.status)

PDF com A3 Desktop (Connector)

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

const connector = createSignerConnector({
  apiBaseUrl: 'https://4signer.com/api/v1',
  bearerToken: 'TOKEN_DA_ACCOUNT'
})

const result = await connector.sign({
  documentId: 'pdf-001',
  documentType: 'pdf',
  certificateMode: 'local',
  documentContentBase64: pdfBase64
})

console.log(result.status)

PDF em nuvem

Requer provider e credencial. Operação assíncrona.

curl -X POST "https://4signer.com/api/v1/signatures/pdf" \
  -H "Authorization: Bearer TOKEN_DA_ACCOUNT" \
  -H "Accept: application/json" \
  -F "signature_method=remote_provider" \
  -F "processing_mode=async" \
  -F "provider=clicksign" \
  -F "pdf=@/tmp/documento.pdf"

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

const connector = createSignerConnector({
  apiBaseUrl: 'https://4signer.com/api/v1',
  bearerToken: 'TOKEN_DA_ACCOUNT'
})

const result = await connector.sign({
  documentId: 'pdf-cloud-001',
  documentType: 'pdf',
  certificateMode: 'cloud',
  documentContentBase64: pdfBase64
})

console.log(result.status)

Carimbo de tempo (RFC3161)

Use request_options[timestamp] para habilitar ACT/TSA em PDF e XML.

Campo	Descrição
request_options[timestamp][enabled]	Ativa o carimbo (1/true)
request_options[timestamp][url]	URL RFC3161 da TSA
request_options[timestamp][username/password]	Credenciais básicas (quando exigido)
request_options[timestamp][token]	Token Bearer opcional

curl -X POST "https://4signer.com/api/v1/signatures/pdf" \
  -H "Authorization: Bearer TOKEN_DA_ACCOUNT" \
  -F "signature_method=local_pfx" \
  -F "processing_mode=sync" \
  -F "pdf=@/tmp/documento.pdf" \
  -F "pfx=@/tmp/certificado.pfx" \
  -F "pfx_password=SENHA" \
  -F "request_options[timestamp][enabled]=1" \
  -F "request_options[timestamp][url]=https://tsa.exemplo.com/rfc3161" \
  -F "request_options[timestamp][username]=tsa_user" \
  -F "request_options[timestamp][password]=tsa_pass"

const result = await connector.sign({
  documentId: 'xml-diploma-001',
  documentType: 'xml',
  certificateMode: 'local',
  documentContentBase64: diplomaXmlBase64,
  xmlProfile: 'xml-xades-diploma',
  xmlPolicy: 'diploma-icpbrasil-xades-1.0',
  requestOptions: {
    timestamp: {
      enabled: true,
      url: 'https://tsa.exemplo.com/rfc3161',
      token: 'TOKEN_TSA'
    }
  }
})

XML

Endpoint base: POST /api/v1/signatures/xml

Campo	Obrigatório	Descrição
signature_profile	Opcional	fiscal \| xml-xades-diploma
signature_policy	Opcional	Ex.: nfe-4.00, cte-4.00, diploma-icpbrasil-xades-1.0
signature_policy_parameters	Opcional	Define tag alvo e parâmetros de policy

XML Fiscal (NFe/CTe/NFSe)

Escolha a tag com signature_policy_parameters[signed_element_local_name].

curl -X POST "https://4signer.com/api/v1/signatures/xml" \
  -H "Authorization: Bearer TOKEN_DA_ACCOUNT" \
  -F "signature_method=local_pfx" \
  -F "processing_mode=sync" \
  -F "xml=@/tmp/nfe.xml" \
  -F "pfx=@/tmp/certificado.pfx" \
  -F "pfx_password=SENHA" \
  -F "signature_profile=fiscal" \
  -F "signature_policy=nfe-4.00" \
  -F "signature_policy_parameters[signed_element_local_name]=infNFe" \
  -F "signature_policy_parameters[id_attribute]=Id"

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

const connector = createSignerConnector({
  apiBaseUrl: 'https://4signer.com/api/v1',
  bearerToken: 'TOKEN_DA_ACCOUNT'
})

const result = await connector.sign({
  documentId: 'nfe-001',
  documentType: 'xml',
  certificateMode: 'local',
  documentContentBase64: nfeXmlBase64,
  xmlProfile: 'fiscal',
  xmlPolicy: 'nfe-4.00',
  xmlPolicyParameters: {
    signed_element_local_name: 'infNFe',
    id_attribute: 'Id'
  }
})

console.log(result.status)

XML Diploma

A tag também é definida por policy parameters. Ex.: DadosDiploma e Diploma.

curl -X POST "https://4signer.com/api/v1/signatures/xml/diploma" \
  -H "Authorization: Bearer TOKEN_DA_ACCOUNT" \
  -F "signature_method=remote_provider" \
  -F "processing_mode=async" \
  -F "xml=@/tmp/diploma.xml" \
  -F "signature_policy=diploma-ra-icpbrasil-xades-1.0" \
  -F "signature_policy_parameters[signed_element_local_name]=Diploma" \
  -F "signature_policy_parameters[id_attribute]=id" \
  -F "request_options[timestamp][enabled]=1" \
  -F "request_options[timestamp][url]=https://tsa.exemplo.com/rfc3161"

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

const connector = createSignerConnector({
  apiBaseUrl: 'https://4signer.com/api/v1',
  bearerToken: 'TOKEN_DA_ACCOUNT'
})

const result = await connector.sign({
  documentId: 'diploma-001',
  documentType: 'xml',
  certificateMode: 'cloud',
  documentContentBase64: diplomaXmlBase64,
  xmlProfile: 'xml-xades-diploma',
  xmlPolicy: 'diploma-ra-icpbrasil-xades-1.0',
  xmlPolicyParameters: {
    signed_element_local_name: 'Diploma',
    id_attribute: 'id'
  },
  requestOptions: {
    timestamp: {
      enabled: true,
      url: 'https://tsa.exemplo.com/rfc3161'
    }
  }
})

console.log(result.status)

Connector JS

No Connector, a seleção da tag XML é feita por xmlPolicyParameters.signed_element_local_name.

Instalação do SDK

Você pode integrar por npm, script ESM direto ou script legado (sem bundler) usando o loader oficial.

npm (recomendado)

npm install @4signer/signer-connector-sdk

Script ESM (sem npm)

<script type="module">
  import { createSignerConnector } from 'https://cdn.jsdelivr.net/npm/@4signer/signer-connector-sdk@1.0.0/src/index.js'

  const connector = createSignerConnector({
    apiBaseUrl: 'https://4signer.com/api/v1',
    bearerToken: 'TOKEN_DA_ACCOUNT'
  })
</script>

Projeto legado com <script> clássico

Use o loader para expor window.createSignerConnector.

<script>
  window.__4signerConnectorSdk = {
    moduleUrl: 'https://cdn.jsdelivr.net/npm/@4signer/signer-connector-sdk@1.0.0/src/index.js'
  }
</script>
<script src="/sdk/signer-connector-legacy-loader.js" defer></script>
<script>
  window.addEventListener('4signer:connector-ready', async function () {
    const connector = window.createSignerConnector({
      apiBaseUrl: 'https://4signer.com/api/v1',
      bearerToken: 'TOKEN_DA_ACCOUNT'
    })

    const result = await connector.sign({
      documentId: 'legacy-001',
      documentType: 'pdf',
      certificateMode: 'cloud',
      documentContentBase64: pdfBase64
    })

    console.log(result.status)
  })
</script>

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

const connector = createSignerConnector({
  apiBaseUrl: 'https://4signer.com/api/v1',
  bearerToken: 'TOKEN_DA_ACCOUNT'
})

const result = await connector.sign({
  documentId: 'diploma-001',
  documentType: 'xml',
  certificateMode: 'local',
  documentContentBase64: diplomaXmlBase64,
  xmlProfile: 'xml-xades-diploma',
  xmlPolicy: 'diploma-icpbrasil-xades-1.0',
  xmlPolicyParameters: {
    signed_element_local_name: 'DadosDiploma',
    id_attribute: 'id'
  },
  requestOptions: {
    timestamp: {
      enabled: true,
      url: 'https://tsa.exemplo.com/rfc3161'
    }
  }
})

console.log(result.status)

Discovery de certificados em nuvem

Liste os certificados disponíveis do usuário para BirdID ou VIDaaS antes da assinatura.

curl

curl -X POST "https://4signer.com/api/v1/connector/v1/providers/birdid/certificates/discovery" \
  -H "Authorization: Bearer TOKEN_DA_ACCOUNT" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "12345678901",
    "identification_type": "CPF"
  }'

Connector JS

const discovery = await connector.discoverCertificates({
  provider: 'birdid', // birdid | vidaas
  username: '12345678901',
  identificationType: 'CPF'
})

console.log(discovery.certificates)

Depois da autenticação OAuth, use /certificates/list para obter os certificados efetivos do token.

curl (pós-auth)

curl -X POST "https://4signer.com/api/v1/connector/v1/providers/birdid/certificates/list" \
  -H "Authorization: Bearer TOKEN_DA_ACCOUNT" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "signature_id": "UUID_DA_ASSINATURA"
  }'

Connector JS (pós-auth)

const certificates = await connector.listCertificates({
  provider: 'birdid',
  signatureId: 'UUID_DA_ASSINATURA'
  // ou accessToken / username
})

console.log(certificates.certificates)

Webhooks

Webhook notifica sua aplicacao quando o status da assinatura muda. A configuracao e feita no painel da conta em Webhooks.

Campo	Uso
url	Endpoint HTTPS que recebera os eventos
secret	Chave para validar assinatura HMAC no header
max_attempts	Quantidade maxima de tentativas de entrega
retry_interval_seconds	Intervalo entre retries quando falhar
timeout_seconds	Timeout HTTP por tentativa de envio

Evento atual de entrega: signature.status_changed.

Headers enviados

Content-Type: application/json
Accept: application/json
X-Signer-Event: signature.status_changed
X-Signer-Delivery-Id: 9123
X-Signer-Signature-Timestamp: 2026-02-17T14:32:11Z
X-Signer-Signature: sha256=HMAC_DO_PAYLOAD

Payload do evento

{
  "event": "signature.status_changed",
  "occurred_at": "2026-02-17T14:32:11Z",
  "account": {
    "id": 9
  },
  "signature": {
    "id": "sig_01J...",
    "provider": "clicksign",
    "processing_mode": "async",
    "status_from": "pending_provider",
    "status_to": "signed",
    "external_id": "pedido-123",
    "error_code": null,
    "error_message": null,
    "started_at": "2026-02-17T14:31:00Z",
    "completed_at": "2026-02-17T14:32:11Z",
    "duration_ms": 71000
  }
}

Entrega considerada sucesso com resposta HTTP 2xx. Em falha, o sistema reenvia ate max_attempts.

Respostas e erros

Sucesso (sync)

{
  "id": "sig_01J...",
  "status": "completed",
  "signed_file_base64": "..."
}

Assíncrono (cloud)

{
  "id": "sig_01J...",
  "status": "pending_provider",
  "webhook_status": "scheduled"
}

Documentação completa de assinatura PDF e XML

Autenticação

Agent Desktop

PDF

PDF simples

PDF com aparência

PDF sem aparência

PDF com A1

PDF com A3 Desktop (Connector)

PDF em nuvem

Carimbo de tempo (RFC3161)

XML

XML Fiscal (NFe/CTe/NFSe)

XML Diploma

Connector JS

Webhooks

Respostas e erros