Waafir
Esta página é uma tradução automática pendente de revisão humana. Pode conter erros.

Referência do waafir-esign

O servidor waafir-esign disponibiliza o serviço próprio de assinatura eletrônica do Waafir para um cliente de IA conectado: crie um envelope sobre um arquivo da sua organização, faça com que seus signatários assinem (ou recusem), acompanhe o status e baixe o PDF assinado. As assinaturas são AES (PAdES) segundo o eIDAS, produzidas pelo próprio mecanismo de assinatura do Waafir; cada assinatura registra o consentimento do signatário (endereço IP, user agent, carimbo de data/hora) em uma trilha de auditoria à prova de adulteração, e o PDF assinado é armazenado como a versão mais recente do arquivo de origem.

Conexão: https://app.waafir.io/api/mcp/waafir ou o servidor da área https://app.waafir.io/api/mcp/waafir-esign — consulte Configuração. Os nomes das ferramentas são os mesmos em ambos. As ferramentas de leitura exigem escopo read, em uma conexão feita por login ou em um PAT; criar, enviar, recusar, revisar signatários e anular exigem escopo write. Assinar exige write e permissão para assinar documentos: aprovada na tela de consentimento, no caso de uma conexão, ou ativada quando um token é criado (consulte Permitir que um token assine documentos); sem ela, esign_sign fica oculta na lista de ferramentas e é recusada se for chamada. Uma conexão ou um token restrito a salas de dados específicas só pode trabalhar com envelopes sobre arquivos dessas salas de dados — o mesmo limite que as ferramentas de sala de dados impõem.

Uma cota mensal de envelopes

A assinatura eletrônica é medida por envelope — um documento / job de assinatura conta uma única vez, não importa quantos signatários tenha. Este servidor MCP e a área de assinatura no aplicativo consomem um único conjunto mensal compartilhado:

  • O acesso exige o complemento E-Signatures ou uma assinatura ativa do Waafir. Sem nenhum dos dois, toda requisição ao waafir-esign é recusada logo na entrada com HTTP 402, antes de qualquer ferramenta ser executada — uma recusa de Camada 1. ADDON_NOT_PURCHASED aparece no texto do message dessa resposta; não é um campo separado legível por máquina, portanto ramifique pelo status 402, não por um código. No waafir, as ferramentas esign_ ficam ocultas na lista de ferramentas, e uma chamada a uma delas é recusada na Camada 2 com QUOTA_EXCEEDED e uma mensagem que nomeia a ferramenta e também contém ADDON_NOT_PURCHASED.
  • Seu plano inclui um pacote mensal de envelopes: Starter 10, Premium 50, Enterprise 50 por assento ativo (mês do calendário).
  • Cada unidade adquirida do complemento E-Signatures adiciona 100 envelopes por mês ao pacote do seu plano; as unidades se somam em qualquer plano.
  • A cota é um teto rígido: quando você envia um envelope no limite, o envio é recusado com o código QUOTA_EXCEEDED, indicando que você compre mais unidades ou faça upgrade — nada é cobrado automaticamente por envelope. O texto da mensagem também cita um token interno ESIGN_QUOTA_EXCEEDED; isso é texto em prosa, portanto ramifique por error.code, que é QUOTA_EXCEEDED. Uma criação com send: true que atinge o teto ainda deixa o rascunho criado — envie-o quando houver margem, em vez de criá-lo novamente.

A cota é consumida quando um envelope é enviado (aberto para assinatura), não por assinatura — portanto, assinar e recusar nunca consomem cota. Leituras e downloads também não. Verifique a margem a qualquer momento com esign_quota_status.

Seu próprio NDA, assinado eletronicamente

Quando sua organização carrega o próprio NDA (Investidores → NDA → Carregar o seu próprio NDA, consulte Personalização), cada investidor o assina no assinador do Waafir: um investidor conectado escolhe Assinar o NDA e o documento abre em uma nova aba; um visitante de link de compartilhamento recebe o link de assinatura por e-mail no endereço que informou. Esses envelopes de NDA não contam para a cota mensal, e o modelo de NDA em si não pode ser enviado como um envelope comum.

Ferramentas

As chaves de argumentos e resultados deste servidor estão em snake_case — a mesma convenção que todos os outros servidores MCP do Waafir usam. file_id, envelope_id, signing_mode, field_layout, consent_affirmed, confirm_send, download_url, has_more.

Alteração incompatível — o waafir-esign aceitava antes argumentos em camelCase. fileId, envelopeId, signingMode, fieldLayout e consentAffirmed não são mais aceitos; cada um tem agora uma grafia em snake_case, listada nas tabelas abaixo. confirm_send não mudou — ele já estava em snake_case.

Quando a grafia descontinuada era um argumento obrigatório, ela é rejeitada, e não aceita silenciosamente: uma chamada que ainda envia fileId para esign_create_envelope falha na validação de argumentos, que aponta file_id como a chave ausente. Quando era opcional, ela é descartada silenciosamente, exatamente como qualquer outra chave não reconhecida — veja os dois modos de falha abaixo. Atualize suas chamadas para as grafias desta página.

Uma chave com erro de grafia falha de uma de duas formas, e uma delas é silenciosa. Um argumento não reconhecido é descartado, nunca rejeitado, então o que acontece em seguida depende apenas de a chave pretendida ser obrigatória ou não:

  • Chave obrigatória → a chamada é recusada. O argumento simplesmente está ausente. Este é o caso explícito e seguro, e abrange esign_create_envelope (file_id), esign_get_envelope, esign_sign (envelope_id e consent_affirmed), esign_decline, esign_void_envelope, esign_revise_signers (envelope_id e signatories) e esign_download_signed — incluindo todas as grafias camelCase descontinuadas dessas chaves.

    Ela não traz error.code. Os argumentos são validados contra o schema publicado da ferramenta antes de a ferramenta ser executada, então uma chave obrigatória ausente — ou uma de tipo errado — volta como um resultado de erro gerado pelo próprio servidor: a resposta é marcada como erro e seu texto nomeia o argumento problemático, mas nenhuma ferramenta foi executada, então nada preenche o campo error.code da Camada 2. Não ramifique por INVALID_ARGUMENT em uma falha de formato de argumento — leia a mensagem. INVALID_ARGUMENT continua sendo o que você recebe em uma recusa que uma ferramenta gera depois de iniciada, como um confirm_token malformado.

  • Chave opcional → a chamada é bem-sucedida e faz outra coisa. Você recebe um 200 e um resultado bem formado que responde a uma pergunta diferente:

    • Os filtros de esign_list_envelopes são opcionais, então um fileId perdido é descartado e você recebe a lista sem filtro de todos os envelopes que o token pode ver — um superconjunto retornado como se fosse a resposta filtrada.
    • Em esign_create_envelope, um signingMode: "sequential" descartado deixa o envelope no modo padrão parallel. Enviá-lo então dispara por e-mail uma solicitação de assinatura juridicamente vinculante para todos os signatários de uma vez, que é exatamente o que pedir sequential deveria evitar. fieldLayout é descartado da mesma forma.

Como uma chave opcional descartada não tem como se anunciar, verifique se o resultado reflete o que você pediu — o envelope criado informa o próprio signing_mode, e esign_list_envelopes só é filtrado se você grafou o filtro corretamente.

esign_create_envelope (escrita)

Cria um envelope sobre um arquivo da sua organização, nomeando seus signatários. Qualquer endereço de e-mail é aceito — um signatário não precisa de uma conta no Waafir. A forma de alcançar cada um é decidida quando o envelope é enviado, de acordo com o fato de esse endereço já ter ou não uma conta no Waafir: quem tem conta assina na sessão (uma notificação no aplicativo e um e-mail com link para a tela de assinatura), e todos os demais recebem por e-mail um link de assinatura como convidado. O critério é a existência da conta, não a participação na sua organização, então um signatário que pertence a outra organização também assina na sessão. Cada signatário pendente recebe exatamente uma das duas opções — nunca ambas, nunca nenhuma.

CampoTipoObrigatórioDescrição
file_idstring (UUID)simO arquivo a ser assinado. Deve pertencer à sua organização.
signatoriesarraysimDe 1 a 50 itens { "email": string, "name"?: string }. Qualquer e-mail é aceito — os signatários não precisam ser usuários do Waafir; endereços externos recebem um link de assinatura como convidado.
transaction_idstring (UUID)nãoObsoleto e ignorado. Aceito para que as integrações existentes continuem funcionando; pare de enviá-lo.
sendbooleannãoQuando true, abre o envelope para assinatura imediatamente, em duas etapas (veja abaixo). Exige um token com Enviar para pessoas fora da sua organização.
confirm_tokenstringnãoSomente com send: true: o token da chamada de prévia.
confirm_sendbooleannãoObsoleto e ignorado: send: true agora usa confirm_token.
signing_mode"parallel" | "sequential"nãoOrdem de assinatura. "parallel" é o padrão: os signatários podem assinar em qualquer ordem, e o envio dispara e-mails para todos de uma vez. "sequential" envia e-mail apenas ao primeiro e libera cada signatário quando todos os anteriores tiverem assinado; assinar fora da vez é recusado com CONFLICT. Omitido — ou grafado erroneamente como signingMode — significa "parallel".
field_layoutarraynãoSubstituição do layout de posicionamento de campos; omita para usar o layout padrão.
observersarraynãoAté 20 observadores (cc) no formato { "email": string, "name"?: string }. Um observador recebe por e-mail uma cópia da solicitação de assinatura e de cada lembrete, com um link somente leitura para acompanhar o status. Observadores nunca assinam e não recebem a cópia assinada.

send: true funciona em duas etapas, porque o envio dispara e-mails reais de solicitação de assinatura, juridicamente vinculantes, para todos os endereços listados no momento em que é bem-sucedido. A primeira chamada não cria nem envia nada: ela retorna uma prévia (os signatários, o número de observadores e sua cota) e um confirm_token. Chame novamente com argumentos idênticos e o token para criar e enviar. Um token funciona uma única vez e expira após alguns minutos. Sem a permissão, send: true é recusado com FORBIDDEN (GRANT_REQUIRED); crie o envelope sem send e envie-o pelo Waafir.

esign_revise_signers segue as mesmas duas etapas, e exige a mesma permissão, quando for enviar e-mail a alguém: um novo signatário ou observador em um envelope já enviado.

Retorna o envelope. Seus campos são exatamente id, file_id, status, signing_mode, created_by, signed_output_name, signed_output_version_count, field_layout, packet_page_count e expires_at — o resultado é uma lista de permissões mapeada manualmente, então nada mais é transmitido. Os carimbos de data/hora são strings ISO-8601.

Um envelope em rascunho precisa ser enviado antes que alguém possa assinar. O envio consome um envelope da sua cota mensal — no teto, um send retorna QUOTA_EXCEEDED e o envelope continua como rascunho, que você pode enviar depois. Um envelope enviado por engano pode ser recolhido com esign_void_envelope.

Um arquivo que ainda está sendo verificado. Se o arquivo for um novo envio ou uma nova versão que o Waafir ainda não terminou de verificar, a chamada responde UNAVAILABLE com error.reason: "ACTIVATION_PENDING" e a mensagem This file is still being checked. Try again shortly. Nada é criado; chame de novo após uma breve espera.

esign_list_envelopes (leitura)

Lista os envelopes da sua organização, do mais recente para o mais antigo, com os signatários e status de cada envelope. Filtro opcional: file_id. (transaction_id está obsoleto e é ignorado.) Como os filtros são opcionais, uma grafia camelCase descontinuada é descartada silenciosamente e a chamada retorna a lista sem filtro, em vez de um erro; veja a observação sobre chaves acima.

Paginado — limit (opcional, de 1 a 100, padrão 25) e offset (opcional, padrão 0) devem ser números; um valor de outro tipo falha na validação de argumentos como qualquer outra incompatibilidade de tipo. Um número fora do intervalo é ajustado ao limite, não rejeitado — limit: 10000 vira 100, offset: -2 vira 0. Retorna:

{ envelopes: [...],
  pagination: { limit, offset, count, has_more, next_offset, total },
  filtered_by_pat_scope: boolean }

Use has_more para distinguir um resultado cortado de um completo e siga next_offset até que seja null; nunca deduza que há mais páginas a partir de count === limit. total é o número de envelopes que este token pode ver.

filtered_by_pat_scope é true quando o token está restrito a salas de dados específicas e essa lista de permissões limitou o resultado — a janela é aplicada depois do filtro, então as páginas são sempre exatas. É propositalmente um booleano, e não uma contagem de envelopes ocultos: informar quantos foram retidos revelaria a existência e o volume de envelopes que o token foi impedido de ver.

esign_get_envelope (leitura)

Obtém um envelope com seus signatários e os respectivos status (pending / signed / declined). Entrada: envelope_id. Além dos campos da ferramenta de criação acima, o envelope traz created_at, updated_at e signatories (cada um { id, email, name, status, signed_at }).

esign_sign (escrita)

Assina a sua própria vaga de signatário pendente — a vaga cujo e-mail corresponde ao usuário proprietário do token. Assinar não consome cota (o envelope já foi contabilizado quando foi enviado). Exige um token com Assinar documentos ativado.

A assinatura exige duas chamadas, para que seu assistente mostre o que você está prestes a assinar antes que qualquer coisa seja assinada:

  1. Prévia. Chame sem confirm_token. Nada é assinado. O resultado é dry_run: true com o envelope, os documents em ordem, um único document_hash cobrindo todos eles, o signer, os fields que você informou, a declaração de consentimento, um confirm_token e o respectivo expires_at.
  2. Confirmação. Depois que a pessoa concordar, chame novamente com argumentos idênticos mais esse confirm_token. Esta chamada assina.

Um confirm_token funciona uma única vez, somente para este token e estes argumentos, e expira após cinco minutos. Se o envelope, seus documentos, a sua posição na ordem de assinatura ou os seus campos mudarem nesse intervalo, a confirmação é recusada e você gera a prévia novamente.

CampoTipoObrigatórioDescrição
envelope_idstring (UUID)simO envelope a assinar.
consent_affirmedbooleansimDeve ser literalmente true — uma afirmação explícita da declaração de consentimento. Não há valor padrão; omiti-lo, ou passar false, faz a chamada falhar no limite do protocolo.
fieldsobjectnãoValores de preenchimento indexados pelo rótulo do campo; nome e data assumem valores padrão quando omitidos.
confirm_tokenstringnãoOmita para gerar a prévia. Passe o token retornado pela prévia para assinar.

A confirmação retorna { envelope }, o envelope no mesmo formato com lista de permissões que esign_create_envelope retorna.

Erros que você pode ver: FORBIDDEN se você não for um signatário pendente do envelope; CONFLICT se o envelope não estiver aberto para assinatura — ou, em um envelope sequential, se um signatário anterior ainda não tiver assinado. Esses são valores de error.code dentro do payload, não status HTTP — consulte Configuração.

A confirmação em duas etapas acrescenta estas recusas, cada uma com seu (code: …) na mensagem:

error.codecode:O que fazer
FORBIDDENGRANT_REQUIREDO token não pode assinar. Crie um novo com Assinar documentos ativado.
INVALID_ARGUMENTCONFIRM_TOKEN_MALFORMEDChame novamente sem confirm_token para obter um.
CONFLICTCONFIRM_TOKEN_INVALIDO token expirou, já foi usado ou pertence a outro token. Gere a prévia novamente.
CONFLICTCONFIRM_ARGS_MISMATCHOs argumentos diferem dos da prévia. Gere a prévia novamente.
CONFLICTCONFIRM_STATE_CHANGEDO envelope mudou desde a prévia. Gere a prévia novamente e mostre-a à pessoa.
CONFLICTDOCUMENT_NOT_PINNEDO envelope foi enviado antes da fixação de documentos. Assine-o no Waafir a partir do e-mail de assinatura.
UNAVAILABLECONFIRM_UNAVAILABLEA confirmação está temporariamente indisponível. Tente novamente em instantes.

Se o layout do envelope tiver campos obrigatórios e fields não os fornecer, a chamada é recusada com INVALID_ARGUMENT e uma mensagem contendo (code: MISSING_REQUIRED_FIELDS). A mensagem não nomeia os rótulos ausentes; a tela de assinatura no aplicativo nomeia. Preencha-os e chame novamente.

esign_decline (escrita)

Recusa a sua própria vaga pendente (terminal — o envelope passa a declined). Entrada: envelope_id. Retorna { id, status: "declined" }. Não consome cota.

esign_void_envelope (escrita)

Recolhe um envelope enviado por engano. Este é o remédio quando uma solicitação de assinatura foi enviada e não deveria ter sido: o envelope deixa de aceitar assinaturas, todos os links de assinatura de convidado pendentes são invalidados imediatamente, e os signatários pendentes não podem mais agir.

Entrada: envelope_id. Retorna o envelope anulado, no mesmo formato com lista de permissões que esign_create_envelope retorna.

  • Terminal. Um envelope anulado não pode ser reenviado — crie um novo em seu lugar.
  • As assinaturas já registradas e a trilha de auditoria completa são preservadas; anular não apaga o que já foi assinado.
  • Permitido somente enquanto o envelope está draft, sent ou partially_signed. Qualquer outro status retorna CONFLICT, e um envelope que expirou informa isso, em vez de um status desatualizado.
  • Quem pode anular: somente a pessoa que criou a solicitação de assinatura, ou um proprietário ou administrador da organização. Qualquer outra pessoa recebe FORBIDDEN; quem chama sem ser parte do envelope recebe NOT_FOUND, de modo que a ferramenta nunca confirma que um envelope existe para alguém que não deveria saber.
  • Anular não consome cota — e não devolve cota. A cota é cobrada quando um envelope é enviado.

esign_revise_signers (escrita, destrutiva)

Corrige quem está sendo solicitado a assinar, sem anular o envelope nem gastar um segundo envelope da sua cota: um e-mail digitado errado, uma contraparte esquecida, a ordem de assinatura errada. O envelope mantém seu id, sua trilha de auditoria e sua unidade de cota. Não consome cota.

CampoTipoObrigatórioDescrição
envelope_idstring (UUID)simO envelope a revisar.
signatoriesarraysimA lista completa de signatários que o envelope deve ter ao final, na ordem de assinatura: de 1 a 50 itens { "email": string, "name"?: string }. Ela substitui a lista atual.
signing_mode"parallel" | "sequential"nãoAltera a ordem de assinatura. Omitido significa que o modo atual é mantido; ele não volta para "parallel".
observersarraynãoA lista completa de observadores (cc), até 20. Omitida significa que os observadores atuais são mantidos; um observador que você deixar de fora é removido e o link somente leitura dele para de funcionar.

Ela é destrutiva. Um signatário que você deixar de fora de signatories é removido: o convite dele é retirado e o link de assinatura para de funcionar imediatamente, sem que ele seja avisado. Todos os campos posicionados para ele são excluídos. Um signatário que já está no envelope mantém o link e não recebe novo e-mail. Um novo signatário é convidado imediatamente se o envelope já tiver sido enviado. A ferramenta é marcada com destructiveHint: true, então um cliente que confirma chamadas destrutivas perguntará antes de executá-la.

  • Somente até a primeira assinatura. Assim que alguém assina, a lista de signatários e o modo de assinatura ficam congelados: a chamada é recusada com CONFLICT (code: ESIGN_SIGNERS_FROZEN), e o remédio é anular e criar um novo envelope. Um envelope expirado também é recusado com CONFLICT.
  • Alterar somente os observadores. Passe a lista de signatários inalterada (e o modo) com uma nova lista observers. Remover um observador é permitido a qualquer momento, mesmo após a assinatura ou a conclusão. Adicionar um é permitido somente enquanto o envelope é um rascunho ou está em assinatura.
  • Quem pode revisar um envelope enviado: somente a pessoa que criou a solicitação de assinatura, ou um proprietário ou administrador da organização; qualquer outra pessoa recebe FORBIDDEN. Um rascunho pode ser revisado por qualquer pessoa que possa vê-lo.
  • Outras recusas trazem o motivo na mensagem: um endereço duplicado (ESIGN_DUPLICATE_SIGNATORY) ou uma lista vazia (ESIGN_EMPTY_ROSTER) é INVALID_ARGUMENT; um novo signatário ou observador em um envelope enviado quando você não pode ler todos os documentos que ele abrange é FORBIDDEN.

Retorna o envelope no mesmo formato que esign_get_envelope, mais um resumo revision do que mudou (e observer_revision quando observadores foram passados).

esign_list_my_pending_signatures (leitura)

Lista os envelopes que aguardam a sua própria assinatura nesta organização: todo envelope aberto com uma vaga de signatário pendente que corresponda ao e-mail do proprietário do token. Esta é a leitura mais útil a fazer antes de esign_sign.

Sem entradas. Retorna { envelopes: [{ id, file_id, document_name, status, created_at }] }.

Restrito à organização deste token e, se o token for restrito, à sua lista de permissões de salas de dados — assinaturas pendentes em outras organizações nunca são exibidas, mesmo que você seja signatário nelas.

esign_download_signed (leitura)

Obtém uma URL de download pré-assinada de curta duração para o PDF assinado. Entrada: envelope_id. Retorna { download_url, expires_in_seconds }. O envelope precisa ter pelo menos uma assinatura registrada; o PDF assinado também está disponível no produto como a versão mais recente do arquivo de origem. Exige um token com Ler conteúdo do documento ativado; sem isso, a chamada é recusada com GRANT_REQUIRED.

esign_quota_status (leitura)

Sem entradas. Retorna { quota, used, remaining } para o mês do calendário atual — cota total de envelopes (pacote do plano + unidades adquiridas), envelopes enviados e margem até o teto.

esign_remind (escrita)

Entrada envelope_id. Envia novamente um e-mail a todos os signatários pendentes de um envelope em assinatura, e uma cópia a cada observador, no máximo uma vez por hora por envelope. Exige Enviar para pessoas fora da sua organização e funciona em duas etapas: a primeira chamada não envia nada e retorna quem receberia o e-mail, os observadores por nome, além de um confirm_token; chame novamente com ele. Um observador adicionado nesse intervalo faz a confirmação falhar. Somente membros da equipe da transação.

esign_resend_signatory (escrita)

Entradas envelope_id, signatory_id. Limpa um endereço com devolução (bounce) ou suprimido e envia novamente um e-mail a esse signatário. Mesma permissão e mesmas duas etapas que esign_remind.

esign_send_draft (escrita)

Entrada envelope_id. Envia um rascunho salvo: cada signatário recebe por e-mail uma solicitação de assinatura juridicamente vinculante, cada observador recebe uma cópia, e um envelope da cota é usado. Mesma permissão e mesmas duas etapas; a prévia nomeia os signatários, os observadores e sua cota, e a lista de signatários e os observadores que você visualizou na prévia são os que são enviados. O resultado lista qualquer endereço suppressed que não recebeu e-mail.

esign_preview (leitura)

Entrada envelope_id. Retorna o envelope como o painel de assinatura o mostra: { envelope_id, status, file_id, document_name, is_creator, signers, placed, fields, shows_signed_output, shows_live_source }. document_name é null quando você não pode ler o documento. Nenhum conteúdo do documento é retornado. Somente membros da equipe da transação.

esign_verify (leitura)

Entrada envelope_id. Retorna o resumo de certificado e integridade que a página de verificação do Waafir mostra. Somente membros da equipe da transação.

Validade jurídica

As assinaturas são Assinaturas Eletrônicas Avançadas (PAdES) segundo o eIDAS, válidas para NDAs e contratos sob o US ESIGN/UETA e o eIDAS da UE. O consentimento do signatário (IP, user agent, carimbo de data/hora) é registrado na trilha de auditoria do Waafir, somente de acréscimo e encadeada por hash, no momento da assinatura. Os envelopes criados ou enviados por este servidor MCP são registrados nessa trilha como ações iniciadas por token, de modo que um envio iniciado por um agente é sempre distinguível de um realizado por uma pessoa no aplicativo. Assinaturas qualificadas (QES) não fazem parte desta versão.