Casos de uso

Como combinar as operações do Assinaturas em fluxos práticos. Os fluxos abaixo usam apenas comportamentos descritos na documentação da API.

1. Contrato com assinatura em ordem (prioridade)

Objetivo: enviar um contrato para dois signatários que devem assinar em sequência — primeiro o contratante, depois a contratada.

Prepare o documento

Obtenha o link de upload em GET /v1/documentos/obter-link-upload-temporario, envie o PDF por PUT e guarde a chave.

Defina a ordem

Crie o envelope com prioridade: 1 para o contratante e prioridade: 2 para a contratada. A prioridade define a ordem de envio dos links.

Acompanhe até finalizar

Consulte GET /v1/envelopes/{envelope} até o status ficar finalizado.

Exemplo — criação com dois signatários em ordem

POST /v1/envelopes

curl -X POST \
  "https://api.assertivasolucoes.com.br/autentica-assinaturas/v1/envelopes" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Contrato de prestação de serviços",
    "signatarios": [
      {
        "nome": "João da Silva",
        "documento": "12345678901",
        "email": "joao@exemplo.com.br",
        "perfilAssinatura": "contratante",
        "formaEnvio": "email",
        "prioridade": 1
      },
      {
        "nome": "Maria de Souza",
        "documento": "98765432100",
        "email": "maria@exemplo.com.br",
        "perfilAssinatura": "contratada",
        "formaEnvio": "email",
        "prioridade": 2
      }
    ],
    "documentos": [
      { "nome": "contrato.pdf", "chave": "00000000-0000-0000-0000-000000000000" }
    ]
  }'

const accessToken = process.env.ASSERTIVA_ACCESS_TOKEN;

const envelope = {
  nome: "Contrato de prestação de serviços",
  signatarios: [
    {
      nome: "João da Silva",
      documento: "12345678901",
      email: "joao@exemplo.com.br",
      perfilAssinatura: "contratante",
      formaEnvio: "email",
      prioridade: 1
    },
    {
      nome: "Maria de Souza",
      documento: "98765432100",
      email: "maria@exemplo.com.br",
      perfilAssinatura: "contratada",
      formaEnvio: "email",
      prioridade: 2
    }
  ],
  documentos: [{ nome: "contrato.pdf", chave }]
};

const resposta = await fetch("https://api.assertivasolucoes.com.br/autentica-assinaturas/v1/envelopes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(envelope)
});
const dados = await resposta.json();
console.log(dados.data.id);

import os
import requests

access_token = os.environ["ASSERTIVA_ACCESS_TOKEN"]

envelope = {
    "nome": "Contrato de prestação de serviços",
    "signatarios": [
        {
            "nome": "João da Silva",
            "documento": "12345678901",
            "email": "joao@exemplo.com.br",
            "perfilAssinatura": "contratante",
            "formaEnvio": "email",
            "prioridade": 1,
        },
        {
            "nome": "Maria de Souza",
            "documento": "98765432100",
            "email": "maria@exemplo.com.br",
            "perfilAssinatura": "contratada",
            "formaEnvio": "email",
            "prioridade": 2,
        },
    ],
    "documentos": [{"nome": "contrato.pdf", "chave": chave}],
}

resposta = requests.post(
    "https://api.assertivasolucoes.com.br/autentica-assinaturas/v1/envelopes",
    headers={"Authorization": f"Bearer {access_token}"},
    json=envelope,
)
resposta.raise_for_status()
print(resposta.json()["data"]["id"])

2. Envio do link por SMS

Objetivo: enviar o link de assinatura por SMS quando o signatário for mais facilmente alcançado pelo celular.

Defina formaEnvio: "sms" no signatário.
Informe o campo celular com DDD e somente números — ele é obrigatório nesse caso.

Sem o celular, um signatário com formaEnvio: "sms" não será aceito. Use apenas números, sem máscara.

3. Reenvio de links de assinatura

Objetivo: reenviar o link quando um signatário não recebeu ou perdeu a mensagem original.

Todo o envelope

PUT /v1/envelopes/{envelope}/reenviar-link reenvia os links aos signatários autorizados por e-mail. Faça isso apenas quando o envelope permitir o reenvio.

Um signatário

PUT /v1/signatarios/{signatario}/reenviar-link reenvia o link individual conforme a forma de envio cadastrada.

Obter o link direto

GET /v1/signatarios/{signatario}/obter-link retorna a url de assinatura do signatário.

Consulte o envelope antes de reenviar. O indicador de permissão para reenvio vem na consulta GET /v1/envelopes/{envelope}.

4. Editar um signatário antes da assinatura

Objetivo: corrigir dados de um signatário (por exemplo, um e-mail errado) que ainda não finalizou a assinatura.

PUT /v1/signatarios/{signatarioId} — atualiza os dados do signatário

Os campos nome, documento, email, perfilAssinatura e formaEnvio são obrigatórios na edição.

PUT /v1/signatarios/{signatarioId} — corpo

{
  "nome": "João da Silva",
  "documento": "12345678901",
  "celular": "11999999999",
  "email": "novoemail@exemplo.com.br",
  "perfilAssinatura": "contratante",
  "formaEnvio": "email"
}

Não é permitido editar um signatário cujo status seja finalizado.

5. Cancelamento de um envelope

Objetivo: encerrar um processo de assinatura que não deve mais prosseguir.

Verifique a permissão

Consulte GET /v1/envelopes/{envelope} e confira o indicador de permissão para cancelar. O cancelamento depende do status atual.

Cancele

PUT /v1/envelopes/{envelope}/cancelar cancela o envelope e seus signatários.

6. Download dos documentos assinados

Objetivo: obter os arquivos finais após a conclusão das assinaturas.

GET /v1/envelopes/{envelope}/links-documentos-assinados retorna os links de todos os documentos. Use auditoria=true (query) para incluir o documento de auditoria.
GET /v1/envelopes/{envelope}/documentos/{documento}/link-download retorna o link de um documento específico. Com o envelope finalizado, o link traz o documento assinado; se ainda em andamento, pode retornar o documento original.

Os links são temporários. Faça o download imediatamente, dentro do período de validade informado pela API.

7. Relatório de solicitações

Objetivo: gerar um relatório das solicitações em um período e baixá-lo. A geração ocorre em segundo plano.

Crie a solicitação

POST /v1/relatorios com tipo (ex.: solicitacoes), dataInicial e dataFinal no formato yyyy-MM-dd. Guarde o id retornado.

Acompanhe o status

Use GET /v1/relatorios/filtrar (com index e size) para acompanhar o processamento.

Baixe o arquivo

GET /v1/relatorios/{id}/gerar-link retorna uma URL temporária, válida por 60 segundos.

POST /v1/relatorios — corpo

{
  "tipo": "solicitacoes",
  "dataInicial": "2023-01-01",
  "dataFinal": "2023-03-31"
}

Recomendações

Boas práticas

Evite duplicidade

Não crie envelopes com nomes repetidos e não repita o mesmo documento entre signatários.

Consulte antes de agir

Verifique o status e os indicadores de permissão antes de cancelar ou reenviar links.

Guarde os identificadores

Armazene os IDs de envelopes, documentos, signatários e relatórios para operações e auditoria.

Proteja os dados

Use HTTPS, não registre tokens ou dados pessoais completos e proteja os documentos assinados conforme suas políticas internas.