Convite de Assinatura pelo WhatsApp via API: Como Usar o deliverVia

Boa parte dos signatários no Brasil abre o WhatsApp muitas vezes por dia e o e-mail bem menos. Para integrações diretas, a API da SignDocs Brasil pode mandar o convite de assinatura pelo WhatsApp, pelo e-mail ou pelo Telegram, com a escolha feita por signatário no campo deliverVia. Este guia mostra como pedir cada canal, o que a resposta da API informa, como os envelopes sequenciais e o reenvio tratam a escolha, e quais erros tratar no seu código.

O assunto aqui é o convite, a mensagem que leva o link de assinatura até a pessoa. O código de uso único (OTP), que alguns perfis pedem depois que o signatário abre o link, tem canal próprio e independente; ele está explicado em OTP por e-mail, SMS, WhatsApp e escolha do canal.

E-mail, WhatsApp ou Telegram: o que muda para o signatário

Nos três canais o signatário recebe o mesmo link da página de assinatura hospedada, abre no navegador e assina sem criar conta. O que muda é por onde o link chega e o que cada canal exige do seu cadastro:

Um detalhe importante para quem recebe: a mensagem do WhatsApp identifica o remetente pelo nome verificado do seu tenant, cadastrado na SignDocs, e não por um texto enviado na requisição. Isso evita que uma chamada da API se apresente em nome de outra empresa, e dá ao signatário uma referência que ele reconhece.

deliverVia na prática

deliverVia é um array no nível de cima do corpo da requisição, ao lado de signer e policy. Ele é aceito em POST /v1/signing-sessions, em POST /v1/envelopes/{id}/sessions e em POST /v1/signing-sessions/{id}/resend-invite. Os valores válidos são email, whatsapp e telegram, em qualquer combinação.

Quatro regras definem o comportamento:

• Omitido é e-mail. Sem deliverVia, a API mantém o contrato anterior: só o convite por e-mail. Nenhum envio pelo WhatsApp acontece sem pedido explícito.
• Só os canais pedidos. ["whatsapp"] manda o convite apenas pelo WhatsApp. Se você quer os dois, peça os dois: ["whatsapp", "email"].
• O e-mail continua com a regra do owner. Na sessão avulsa, o e-mail de convite sai quando há owner.email e ele é diferente do signer.email; isso impede que o remetente mande o convite para si mesmo. O WhatsApp não tem essa condição, porque vai para o número do signatário.
• Telefone em E.164. signer.phone precisa começar com + e o código do país, só com dígitos. Formatos como (11) 99999-8888 são recusados com 400.

Os canais são validados antes de qualquer gravação. Um pedido inválido não cria sessão, não consome cota e não manda nada; você corrige e repete com a mesma chave de idempotência.

O que a resposta diz, e o que ela não diz

A resposta da criação traz os campos de sempre (sessionId, transactionId, url, clientSecret, expiresAt) e, conforme os canais, indicadores do convite:

"Aceita pela Meta" não é o mesmo que "lida pelo signatário". A API não expõe, por endpoint nem por webhook, o status do WhatsApp depois do aceite. Por isso o seu sistema deve acompanhar o que importa, a assinatura, pelos eventos de sempre: SIGNING_SESSION.COMPLETED, TRANSACTION.COMPLETED, TRANSACTION.EXPIRED. O desenho do consumidor está em webhooks e eventos da API.

Envelopes sequenciais e reenvio

Em envelopes, cada signatário entra com o seu próprio deliverVia em POST /v1/envelopes/{id}/sessions, então um envelope pode ter um signatário convidado pelo WhatsApp e outro pelo e-mail. A escolha fica gravada na transação daquele signatário.

• Envelope PARALLEL: todos são convidados quando a sessão é criada, cada um nos seus canais.
• Envelope SEQUENTIAL: a partir do segundo signatário, o convite não sai na criação. A resposta traz inviteDeferred: true e invitedAfterSigner; quando chega a vez dele, a SignDocs o convida nos canais que foram gravados. Se nenhum dos canais pedidos conseguir enviar naquele momento e houver e-mail no cadastro, o convite sai por e-mail.

O reenvio segue a mesma lógica. POST /v1/signing-sessions/{id}/resend-invite sem corpo reenvia pelos canais gravados na criação. Com corpo, você escolhe outro canal para aquele reenvio:

O reenvio só vale para sessões ACTIVE e respeita um intervalo de 60 segundos por sessão; antes disso, a resposta é 409. Pedir email num reenvio de sessão sem e-mail do signatário também devolve 409. Se a sessão já expirou, o caminho é outro, descrito em sessão expirada: reenviar ou recriar.

Erros que o seu código precisa tratar

Cada convite pelo WhatsApp consome a cota de mensagens do tenant, separada da cota de documentos. A checagem acontece antes de criar a sessão, então um 429 não deixa sessão órfã. Os cabeçalhos RateLimit-* e Retry-After seguem o mesmo padrão descrito em rate limits, paginação e idempotência, e o tratamento geral de códigos está em códigos de erro da API.

Boas práticas

• Valide o telefone na entrada. Converta para E.164 no momento do cadastro, não na hora do envio, e confirme com o cliente que o número é de celular com WhatsApp.
• Sempre informe o e-mail também. Ele é o que permite o reenvio por outro canal e o convite automático por e-mail quando o número não tem WhatsApp.
• Escolha o canal com o signatário. Pergunte na sua própria interface por onde a pessoa prefere receber, e guarde essa preferência junto do cadastro.
• Respeite quem pediu para parar. Se o signatário responde à mensagem com "parar", "sair" ou "stop", a SignDocs deixa de mandar WhatsApp para aquele número; nesse caso whatsappInviteSent não aparece. Reenvie por e-mail.
• Não espalhe o link. A URL com ?cs= dá acesso à assinatura. Não grave o clientSecret em logs de aplicação nem o repasse por canais que você não controla.
• Use idempotência na criação. Um retry de rede sem X-Idempotency-Key pode gerar uma segunda sessão e um segundo convite no celular do signatário.

Testando no sandbox

No ambiente de homologação você valida o que é do seu código: o payload com deliverVia, o tratamento de 400, 403 e 429, a gravação do canal escolhido e o fluxo completo por e-mail até o webhook de conclusão. Uma conta de sandbox sem WhatsApp habilitado responde 403 a pedidos com whatsapp, o que já permite testar o caminho de erro. Para validar o envio real pelo WhatsApp antes da produção, combine a habilitação com o time comercial. Mensagens do WhatsApp são mensagens de modelo reais, por isso o volume de teste é limitado.

Com o convite resolvido, os próximos passos naturais são a ordem de assinatura com vários signatários e a escolha do nível de autenticação de cada documento. A visão geral da plataforma está na página da API de assinatura digital.

Perguntas Frequentes