Skip to main content
POST
Criar assinatura incremental
Recebe um ou mais PDFs que já contêm assinaturas digitais, mais os signatários novos, e já envia o pedido de assinatura. Cada assinatura nova entra como revisão no fim do arquivo, e as assinaturas que já estavam dentro continuam válidas. Veja Assinatura incremental para entender as regras. Para montar o pedido em etapas, como numa tela de cadastro, use POST .../drafts.

Parâmetros

string
required
Título da assinatura, ex.: "CCB 2026-0001". Máximo 255 caracteres.
string
required
Vencimento (ISO 8601). Precisa estar no futuro.
number
Frequência dos lembretes, em horas. Padrão: 24.
enum
sequential (na ordem da lista) ou parallel (todos ao mesmo tempo). Padrão: parallel.
enum
Por onde os signatários são avisados: EMAIL, SMS ou NONE. Com EMAIL ou SMS o portal envia o convite e os lembretes. Com NONE ninguém é avisado, os links voltam na resposta para você entregar, e urlNotification passa a ser obrigatória.
string
URL HTTPS que recebe os eventos da assinatura (SENT, SIGNED, REFUSED, FINISHED, CANCELLED e EXPIRED). Obrigatória com notificationChannel=NONE.
array
required
Os PDFs que já vêm assinados, ao menos um. Cada item:
  • filename (string, obrigatório): nome do arquivo.
  • content (string): o PDF em base64.
  • url (string): URL de onde baixar o PDF.
Informe content ou url, não os dois.
array
required
Os signatários novos. Cada item:
  • name (string, obrigatório): nome completo.
  • email (string, obrigatório): e-mail.
  • cpf (string, obrigatório): CPF, com ou sem pontuação.
  • placementMode (enum, obrigatório): OPERATOR ou SIGNER. Com OPERATOR você manda a posição da chancela agora, em positions. Com SIGNER o próprio signatário posiciona a chancela antes de assinar.
  • positions (array): obrigatório com OPERATOR, uma posição para cada documento do pedido. Veja abaixo.
  • signatureType (enum): ICP_BRASIL, MFA_EMAIL, MFA_SMS, LIVENESS, MFA_EMAIL_LIVENESS ou MFA_SMS_LIVENESS. Padrão: ICP_BRASIL.
  • qualification (string): qualificação impressa na chancela, ex.: "Tomador".
  • phoneCountryCode (string): DDI, ex.: "55".
  • phoneNumber (string): celular com DDD. Obrigatório nos tipos por SMS.
  • queueOrder (number): ordem na fila. Padrão: a posição na lista, a partir de 1.

Cada item de positions

Respostas

string
Identificador da assinatura incremental. Use-o em GET /signer/v1/envelopes/:uuid.
array
Os documentos recebidos, na ordem do pedido. Cada item tem index, filename e fileUuid.
array
Os signatários, cada um com signerUuid, email e signUrl, o link da página de assinatura. Com EMAIL ou SMS o portal já enviou o link; com NONE, entregar é com você.

Erros

Veja Autenticação e erros.
  • 400: Corpo inválido, vencimento no passado, posição faltando para algum documento, tipo de assinatura desconhecido ou PDF ilegível.
  • 401: Nem x-api-key nem Authorization válidos.
  • 422: O documento não aceita assinatura nova: certificado como “nenhuma alteração permitida” (DocMDP /P 1), protegido por senha ou com estrutura que impede a revisão incremental.

Exemplo

Importante

  • O arquivo recebido não muda. Não há conversão para PDF/A nem página de manifesto.
  • Toda chancela precisa de lugar. Com OPERATOR, mande uma posição para cada documento; com SIGNER, o signatário posiciona antes de assinar.
  • O portal assina no fim. Quando o último signatário assina, o portal assina cada documento com o certificado do assinador, de forma invisível.

Relacionado