Envelopes

Adicionar sessão de signatário ao envelope

Adiciona uma sessão de assinatura para um signatário no envelope. Retorna a URL e clientSecret para integração. O link entregue àquele signatário é {url}?cs={clientSecret} — a url sozinha não abre.

Suporta idempotência via header X-Idempotency-Key. Use uma chave distinta por signatário (o corpo muda a cada signerIndex): reenviar a mesma chave devolve a resposta original, incluindo o clientSecret — que só é retornado nesta resposta e não pode ser recuperado depois.

Requer scope transactions:write.

post/v1/envelopes/{envelopeId}/sessions

Request

  • Base URL: https://api.signdocs.com.br
  • URL: https://api.signdocs.com.br/v1/envelopes/{envelopeId}/sessions
  • Auth: HTTP bearer

Path parameters

envelopeIdstring required

Identificador único do envelope.

Headers

X-Idempotency-Keystring uuid

Chave de idempotência para evitar criação duplicada. Reenviar a mesma chave com o mesmo corpo dentro de 24h devolve a resposta original, sem consumir cota nem repetir efeitos (e-mails, webhooks). A mesma chave com um corpo diferente responde 409.

A resposta repetida é a original byte a byte, incluindo os cabeçalhos RateLimit-* — eles refletem a cota no momento da chamada original, já que a repetição não consumiu nada.

Request body

purpose'DOCUMENT_SIGNATURE' | 'ACTION_AUTHENTICATION'

Finalidade da sessão.

signerIndexinteger required

Índice do signatário no envelope (mínimo 1). Define a ordem em modo SEQUENTIAL.

returnUrlstring uri

URL de retorno após conclusão desta sessão. Sobrescreve a URL do envelope.

cancelUrlstring uri

URL de retorno em caso de cancelamento. Sobrescreve a URL do envelope.

metadataobject

Metadados livres específicos desta sessão.

deliverViastring[]

Canais pelos quais a SignDocs entrega o link de assinatura a este signatário; cada signatário escolhe os seus. Omita para manter o comportamento anterior: apenas o e-mail de convite.

Num envelope SEQUENTIAL, o signatário posterior não recebe link antes da sua vez; quando ela chega, recebe pelos canais escolhidos aqui. O envio é admitido nesta chamada, com a verificação de cota, porque depois não há a quem devolver um 429. Provisionamento e kill switch são conferidos de novo no momento do envio. Se nenhum canal pedido conseguir entregar, o signatário recebe o convite por e-mail quando tem endereço e o envelope tem owner.

WhatsApp e Telegram são habilitados sob demanda: o tenant pede ao time comercial, e não é algo que se liga pelo painel. Pedir um canal que o tenant não tem retorna 403 antes de qualquer gravação.

whatsapp exige signer.phone em E.164. whatsappInviteSent: true significa que a Meta aceitou a mensagem, não que ela foi entregue ou lida; em qualquer outro caso o campo é omitido da resposta. Se a Meta reportar falha depois e o signatário tiver e-mail, a SignDocs reenvia o convite por e-mail automaticamente, com um link novo, diferente do que veio nesta resposta; nenhum webhook, campo ou endpoint informa esse reenvio. Um número que respondeu "parar", "sair" ou "stop" deixa de receber mensagens da SignDocs por WhatsApp.

telegram exige signer.cpf e só alcança signatários que já registraram o próprio CPF no bot da SignDocs. telegramInviteSent vem na resposta sempre que o convite por Telegram é tentado nesta chamada, false quando não chegou.

Cada envio por WhatsApp ou Telegram consome a cota de mensagens do tenant. Esgotada a cota, a requisição é recusada com 429 antes de qualquer gravação; com o canal suspenso por kill switch, com 503. Credenciais de sandbox também enviam mensagens reais por WhatsApp e consomem a cota de mensagens de sandbox.

Example request

{
  "signer": {
    "name": "Maria Oliveira",
    "userExternalId": "usr-67890",
    "cpf": "98765432109",
    "cnpj": "98765432000188",
    "email": "maria@exemplo.com.br",
    "phone": "+5511988887777",
    "birthDate": "1990-05-15"
  },
  "policy": {
    "profile": "STANDARD"
  },
  "signerIndex": 1,
  "returnUrl": "https://app.example.com/signer/1/done",
  "cancelUrl": "https://app.example.com/signer/1/cancelled",
  "deliverVia": [
    "email",
    "whatsapp"
  ]
}

Response

Sessão de signatário adicionada com sucesso.

sessionIdstring required

Identificador único da sessão.

transactionIdstring required

Identificador da transação subjacente.

signerIndexinteger required

Índice do signatário no envelope.

status'ACTIVE' | 'COMPLETED' | 'CANCELLED' | 'EXPIRED' | 'FAILED' required

Status da sessão de assinatura.

urlstring uri required

Endereço da página de assinatura hospedada. Não é um link utilizável sozinho: o clientSecret é a autenticação da sessão e precisa viajar na query string. O link entregue ao signatário é {url}?cs={clientSecret}, com o clientSecret URL-encoded. Sem o parâmetro cs a página abre em tela de erro. No navegador não é preciso montar nada — o SDK JS deriva a URL do próprio clientSecret (sd.checkout() abre em popup, sd.redirect() redireciona).

clientSecretstring required

Token de sessão para autenticação no widget/redirect. Formato ss_secret_ + JWT.

expiresAtstring date-time required

Data/hora de expiração da sessão (ISO 8601 UTC).

inviteSentboolean

Verdadeiro quando a SignDocs enviou um e-mail de convite para signer.email. Só é populado quando o envelope foi criado com owner e signer.email é diferente de owner.email (case-insensitive).

whatsappInviteSentboolean

true quando a Meta aceitou a mensagem com o link para signer.phone. Aceitar não é entregar: a entrega é confirmada depois, por webhook da Meta, e não é exposta pela API. Omitido em qualquer outro caso (número que pediu para não receber mensagens, falha no envio) e só considerado quando deliverVia incluiu whatsapp.

telegramInviteSentboolean

Resultado da entrega por Telegram. false significa que o signatário não tem CPF registrado no bot, ou que o envio falhou — em ambos os casos o link não chegou por esse canal. Só é populado quando deliverVia incluiu telegram.

Example response

{
  "sessionId": "ss_01JXYZ...",
  "transactionId": "tx_01JXYZ...",
  "signerIndex": 1,
  "url": "https://sign.signdocs.com.br/s/ss_01JXYZ...",
  "clientSecret": "ss_secret_eyJhbGciOi..."
}

Changes

No recorded changes to this operation across all 1 revision of this API.