Transferência Parcial de Documentos e Definições de Marca de Água (API v1.16.0)

A API v1.16.0 introduz duas funcionalidades que resolvem um problema comum: descarregar documentos de pedidos de assinatura antes de todos os signatários terem terminado, e controlar o aspeto desses PDFs parciais com uma marca de água configurável.

Descarregar Documentos em Qualquer Fase

Antes desta atualização, só podia descarregar o PDF de um pedido de assinatura depois de todos os signatários terem concluído. Isso funciona bem para acordos simples entre duas partes, mas deixa de ser suficiente quando tem contratos com vários signatários em que as equipas jurídicas ou de conformidade precisam de visibilidade sobre o progresso antes de chegar a última assinatura.

O novo endpoint GET /signing-requests/{id}/download devolve um URL de transferência pré-assinado para o documento no seu estado atual. Funciona em todos os estados do pedido de assinatura: em curso, cancelado, recusado e expirado.

Para pedidos de assinatura concluídos, obtém o PDF assinado final, como antes. Para tudo o resto, obtém uma captura instantânea que inclui apenas os campos concluídos pelos signatários que já terminaram. Os campos dos signatários pendentes são omitidos por completo, pelo que o documento reflete exatamente o que já foi executado até ao momento.

Cada PDF parcial também inclui uma página de trilho de auditoria com uma tabela de estado por signatário e enquadramento probatório, dando-lhe um registo claro de quem assinou, quem ainda não assinou e quando.

Para ativar transferências parciais num pedido de assinatura, defina allow_partial_download: true nas definições do pedido de assinatura. O documento é gerado sob pedido na primeira vez que o solicitar e fica em cache para chamadas subsequentes. Se o documento ainda não tiver sido gerado, receberá um 503 com um cabeçalho Retry-After.

Controlo da Marca de Água por Workspace

Algumas equipas querem que os PDFs parciais estejam claramente assinalados como incompletos. Outras querem documentos limpos que possam encaminhar para as partes interessadas sem ruído visual. A nova definição show_partial_watermark em definições do workspace dá-lhe esse controlo.

Quando ativada, os PDFs parciais incluem uma marca de água diagonal "EM CURSO — AINDA NÃO EXECUTADO" em cada página. Quando desativada (o predefinido), o documento é descarregado limpo.

Esta é uma definição ao nível do workspace, por isso, se estiver a usar Workspaces de Cliente para segmentar os clientes da sua plataforma, cada workspace pode ter a sua própria preferência de marca de água.

Detalhes da API

Aqui está o resumo rápido do que há de novo na API:

• Novo endpoint: GET /signing-requests/{id}/download devolve um download_url pré-assinado com um carimbo temporal expires_at

• Nova definição: allow_partial_download (boolean) nas definições do pedido de assinatura permite transferências parciais

• Nova definição de workspace: show_partial_watermark (boolean | null) controla a marca de água diagonal nos PDFs parciais

• Estados suportados: finished, in_progress, cancelled, declined, expired

Para a especificação completa do endpoint, consulte a documentação de download de pedidos de assinatura. Para notas de migração, veja o registo de alterações da API.

Esta é uma atualização não disruptiva. Não há alterações ao comportamento existente, e as integrações existentes continuarão a funcionar sem necessidade de modificações.

Começar

Se já estiver na API da Firma.dev, pode começar a usar o novo endpoint imediatamente atualizando o cabeçalho da sua versão da API para v01.16.00. Se for novo na Firma.dev, obtenha já a sua chave de API e comece a desenvolver gratuitamente, sem necessidade de cartão de crédito.