Primeira requisição

Este passo a passo leva você até o seu primeiro envelope criado no Assinaturas: você prepara o documento (upload), cria o envelope com os signatários e acompanha o status até a finalização.

Pré-requisitos

Credenciais

Ter suas credenciais de aplicação (Client ID e Secret).

Token de acesso

Ter gerado um token de acesso — veja Autenticação.

Documento PDF

Ter o arquivo PDF a ser assinado (até 30 MB no total do envelope).

Os valores abaixo são fictícios, apenas para ilustração. Use dados reais só em produção e conforme as políticas de privacidade.

Passo 1

Obtenha o link temporário de upload

GET /v1/documentos/obter-link-upload-temporario — gera a URL para enviar o PDF

Parâmetros (query):

Parâmetro	Obrigatório	Descrição
`quantidadeLinks`	não	Quantidade de links desejada. Se omitido, é gerado um único link.

GET /v1/documentos/obter-link-upload-temporario

curl -X GET \
  "https://api.assertivasolucoes.com.br/autentica-assinaturas/v1/documentos/obter-link-upload-temporario?quantidadeLinks=1" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

// Node 18+ possui fetch nativo.
const accessToken = process.env.ASSERTIVA_ACCESS_TOKEN;

const url = new URL("https://api.assertivasolucoes.com.br/autentica-assinaturas/v1/documentos/obter-link-upload-temporario");
url.searchParams.set("quantidadeLinks", "1");

const resposta = await fetch(url, {
  headers: { Authorization: `Bearer ${accessToken}` }
});
if (!resposta.ok) throw new Error(`Consulta falhou: ${resposta.status}`);
const dados = await resposta.json();
const { url: urlUpload, chave } = dados.data.links[0];
console.log(urlUpload, chave);

import os
import requests

access_token = os.environ["ASSERTIVA_ACCESS_TOKEN"]

resposta = requests.get(
    "https://api.assertivasolucoes.com.br/autentica-assinaturas/v1/documentos/obter-link-upload-temporario",
    headers={"Authorization": f"Bearer {access_token}"},
    params={"quantidadeLinks": 1},
)
resposta.raise_for_status()
link = resposta.json()["data"]["links"][0]
print(link["url"], link["chave"])

A resposta traz uma lista de links, cada um com:

url: URL temporária usada para o upload;
chave: identificador do arquivo, informado depois no campo chave do documento ao criar o envelope.

Passo 2

Envie o PDF para a URL temporária

Faça o upload do arquivo diretamente para a url recebida, usando PUT e Content-Type: application/application-pdf.

PUT {url-temporaria}

curl -X PUT \
  "https://url-temporaria-de-upload" \
  -H "Content-Type: application/application-pdf" \
  --data-binary "@contrato.pdf"

import { readFile } from "node:fs/promises";

const pdf = await readFile("contrato.pdf");

await fetch(urlUpload, {
  method: "PUT",
  headers: { "Content-Type": "application/application-pdf" },
  body: pdf
});

with open("contrato.pdf", "rb") as arquivo:
    requests.put(
        url_upload,
        headers={"Content-Type": "application/application-pdf"},
        data=arquivo,
    ).raise_for_status()

A URL de upload é temporária. Realize o envio imediatamente após obtê-la e guarde a chave para o próximo passo.

Passo 3

Crie o envelope

POST /v1/envelopes — cria a solicitação de assinatura

Estrutura da requisição:

Campo	Obrigatório	Descrição
`nome`	sim	Nome do envelope. Não pode se repetir entre envelopes.
`signatarios`	sim	Lista de pessoas que deverão assinar.
`documentos`	sim	Lista de documentos, cada um com `nome` e a `chave` do upload.

Cada signatário deve conter:

Campo	Obrigatório	Descrição
`nome`	sim	Nome completo do signatário.
`documento`	sim	CPF (11 dígitos) ou CNPJ (até 14 caracteres) do signatário.
`email`	sim	E-mail do signatário.
`celular`	condicional	Celular com DDD, somente números. Obrigatório quando `formaEnvio` for `sms`.
`perfilAssinatura`	sim	Papel do signatário (ex.: `contratante`).
`formaEnvio`	sim	Forma de envio do link: `email` ou `sms`.
`prioridade`	sim	Ordem de envio e assinatura.

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
      }
    ],
    "documentos": [
      { "nome": "contrato.pdf", "chave": "00000000-0000-0000-0000-000000000000" }
    ]
  }'

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
    }
  ],
  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);

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,
        }
    ],
    "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"])

Entenda a resposta

Em caso de sucesso, a API retorna 201 com o identificador do envelope. Guarde esse id: ele é usado nas consultas e operações seguintes.

Exemplo de resposta (dados fictícios)

{
  "status": 201,
  "success": true,
  "data": {
    "id": "00000000-0000-0000-0000-000000000000"
  }
}

Passo 4

Acompanhe o status

Consulte o envelope para acompanhar o andamento das assinaturas com GET /v1/envelopes/{envelope}. A resposta traz o status atual (emProcesso, finalizado, expirado ou cancelado), o total de signatários, o total de assinaturas realizadas e indicadores de permissão para reenviar links ou cancelar.

Quando o envelope estiver finalizado, use GET /v1/envelopes/{envelope}/links-documentos-assinados para obter os links de download dos documentos assinados (e, opcionalmente, do documento de auditoria).

Formato das respostas

As respostas de sucesso seguem o padrão:

Campo	Descrição
`status`	Código HTTP da operação.
`success`	Indica se a operação foi realizada com sucesso.
`data`	Dados retornados pela API.

Em respostas de erro, o campo messages traz a lista de mensagens.

Principais respostas de erro

Código	Significado	Tratamento recomendado
`400`	Dados ou campos inválidos.	Validar o corpo e os parâmetros da requisição.
`401`	Usuário não autenticado.	Verificar o token e as credenciais utilizadas.
`403`	Acesso não autorizado.	Confirmar as permissões da aplicação.
`408`	Tempo limite de resposta excedido.	Repetir a operação após validar a disponibilidade do serviço.
`500` / `503` / `504`	Erro interno, indisponibilidade ou gateway sem resposta.	Aguardar e repetir; acionar o suporte se persistir.

Próximo passo

Veja como encadear as operações em fluxos reais nos casos de uso.