Logo PDFHQ

Documentos

DocumentaçãoAssinatura

API de solicitações de assinatura eletrônica

Crie e edite rascunhos de assinatura versionados, coloque e valide campos atribuídos pelo remetente, envie solicitações de sandbox explícitas e recupere artefatos assinados.

Chaves de API do lado do servidor Uploads de armazenamento assinado

Ciclo de vida do pedido de assinatura — sandbox primeiro#

PDFHQ eSign suporta um recurso de envelope neutro de provedor: envie e verifique um PDF com POST /v1/documents/uploads, depois crie um rascunho de solicitação de assinatura. Os rascunhos têm sua própria identidade, signatários e status separados das tarefas de conversão de PDF.

Versão atual: Modo de teste Dropbox Sign apenas. Os documentos de teste têm marca d'água e não têm validade legal. O provedor envia seus próprios emails de signatário. Solicitações de assinatura ao vivo, conexões OAuth corporativas e tarifas de produção não estão ativadas.

Criar rascunho de assinatura eletrônica
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes' \
  -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"upload_id":"VERIFIED_UPLOAD_UUID","provider":"managed","title":"Mutual NDA","subject":"Please review and sign","message":"Please sign this agreement.","signers":[{"name":"Alice Example","email":"alice@example.com","order":0},{"name":"Bob Example","email":"bob@example.com","order":1}]}'

Prepare campos de assinante exatos e rascunhos versionados#

Clientes Sandbox podem colocar campos de assinatura, iniciais e data de assinatura em um PDF US Letter selado, vertical e não cortado. As coordenadas de retângulo público são normalizadas de 0 a 1 em relação ao canto superior esquerdo da página; o número da página começa em 1. Cada signatário deve receber um campo de assinatura obrigatório. Rejeite posicionamentos sobrepostos, ausentes ou fora dos limites. Para todos os outros tamanhos de página, omita fields para usar a página de assinatura anexada do provedor enquanto o suporte está sendo validado.

Criar rascunho posicionado com dois signatários
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes' \
  -H 'x-api-key: YOUR_API_KEY' -H 'Idempotency-Key: sample-signing-draft-001' \
  -H 'Content-Type: application/json' \
  -d '{"upload_id":"VERIFIED_UPLOAD_UUID","provider":"managed","title":"NDA", "subject":"Sign NDA","message":"Please review and sign","signers":[{"name":"Example One","email":"first@example.test","order":0},{"name":"Example Two","email":"second@example.test","order":1}],"fields":[{"field_id":"first_sig","signer_index":0,"type":"signature","page":1,"rect":{"x":0.10,"y":0.72,"width":0.30,"height":0.08},"required":true},{"field_id":"second_sig","signer_index":1,"type":"signature","page":1,"rect":{"x":0.55,"y":0.72,"width":0.30,"height":0.08},"required":true}]}'

A criação é idempotente com um Idempotency-Key. A mesma chave e os mesmos dados de documento/rascunho selado retornam o rascunho existente; um payload diferente retorna 409. Um rascunho pode ser editado apenas antes do envio por PATCH /v1/esign/envelopes/ENVELOPE_UUID com um conjunto de campos de substituição completo e If-Match: 1 de seu draft_version. Edições incrementam a versão e o resumo. Os campos permanecem imutáveis após o envio.

Verificação prévia exata da origem e layout de campo
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/validate' \
  -H 'x-api-key: YOUR_API_KEY'

Este pré-voo compara dimensões de página e rotação contra bytes lacrados reais, não metadados do navegador. Tem limite de taxa e é somente leitura. Uma visualização local bem-sucedida não certifica posicionamento pixel-perfeito do Dropbox Sign; revise a cerimônia de assinatura de teste real antes da ativação em produção.

Enviar com reconhecimento de teste explícito#

cURL
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/send' \
  -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"confirm_test_mode":true,"draft_version":1}'

# Poll the envelope for status; never auto-retry an uncertain send.
curl 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID' -H 'x-api-key: YOUR_API_KEY'

O despacho do provedor é protegido por uma configuração explícita no servidor e desabilitado em produção. Solicitações que podem ter chegado ao Dropbox mas perderam sua resposta entram needs_reconciliation e não podem ser reenviados cegamente.

Lembretes de sandbox e cancelamento — callbacks assinados são autoritários#

Após um pedido de teste ser enviado, o remetente pode emitir um lembrete de teste por email por destinatário em 24 horas. Pedidos de cancelamento usam a API do provedor de forma assíncrona; um HTTP 202 apenas significa que o cancelamento foi solicitado, não que os destinatários não possam mais assinar. Nenhuma operação é um fluxo de trabalho de assinatura eletrônica de produção.

Solicitar um lembrete para um destinatário
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/remind'   -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"recipient_index":0,"confirm_test_mode":true}'

curl 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/reminders'   -H 'x-api-key: YOUR_API_KEY'

Relatórios de lembretes registram aceitação/rejeição/incerteza, não entrega real de email. Uma tentativa de lembrete é registrada permanentemente antes de contatar o provedor; se o resultado da rede for incerto, não tente novamente. Apenas chamadores dentro da conta/projeto de API original podem acessar recibos; emails de signatários são excluídos.

Solicitar cancelamento assíncrono; inspecionar status
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/void'   -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"reason":"agreement_withdrawn","confirm_test_mode":true}'

curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/sync'   -H 'x-api-key: YOUR_API_KEY'

O cancelamento é permitido apenas enquanto enviado, visualizado ou aguardando entrega. Solicitações parcialmente assinadas e concluídas não podem ser canceladas do PDFHQ. HTTP 200 do provedor não significa que o envelope foi anulado. Aguarde um signature_request_canceled callback ou status de provedor confirmado. Respostas como cancel_uncertain exigem investigação do operador; nunca envie novamente cegamente.

Esta API não promete exclusão de convites previamente enviados por email, exigibilidade legal, cancelamento retroativo de uma assinatura existente, reembolsos automáticos ou SLA de provedor em nível de produção. O modo ativo futuro requer faturamento centralizado baseado em crédito, verificação de identidade, revisão contratual e aceitação completa do provedor de staging.

Recuperação de documento assinado#

Após um verificado signature_request_downloadable retorno de chamada, uso POST /v1/esign/envelopes/ENVELOPE_UUID/archive . PDFHQ baixa o PDF concluído do Dropbox para o namespace de armazenamento privado HQ. Depois recupere GET /v1/esign/envelopes/ENVELOPE_UUID/download-url para uma URL de saída com escopo de conta e curta duração.

O PDF de origem nunca é enviado através de uma URL especificada pelo cliente. Encaminhamos bytes de arquivo selado verificados para o host fixo da API Dropbox. Páginas de signatário hospedadas pelo provedor e evidência de auditoria do provedor são gerenciadas pelo serviço selecionado.

Segurança de webhook e transições de estado →
Logo PDFHQ

Ferramentas PDF e inteligência de documentos. Prepare, compreenda e trabalhe com seus documentos.

© 2026 PDFHQ. Todos os direitos reservados.