REST API v1

API do TesseraSign

Integre seu ERP, CRM ou sistema externo ao TesseraSign para enviar documentos para assinatura eletrônica, acompanhar o status em tempo real e receber notificações automáticas via webhooks quando cada signatário agir.

Assinatura eletrônica avançada

Webhooks com retry automático

Auditoria criptográfica

Autenticação

Todas as requisições à API devem incluir uma chave de integração (API Key) no cabeçalho Authorization, no formato Bearer. A chave identifica sua organização e determina quais documentos você pode consultar.

header

Authorization: Bearer tsk_live_a1b2c3d4e5f6...

Como obter sua chave:Acesse o TesseraSign → Minha Organização → cartão Chave de API. Clique em "Gerar Chave de API" para criar uma nova chave. Guarde-a em segredo — ela concede acesso a todos os documentos da sua organização. Se comprometida, regenere imediatamente (a anterior é invalidada).

Formato único aceito: somente Authorization: Bearer <chave>. Outros formatos (x-api-key, query param, header api-key) não são suportados e sempre retornam 401.

URL Base

Todos os endpoints partem desta URL base:

url

https://tesserasign.base44.app/functions/publicApi

Não há versionamento por caminho de URL — a versão atual é v1. O roteamento é feito por método HTTP e query params:

Roteamento

POST/functions/publicApi — criar documento

GET/functions/publicApi?id={id} — consultar status

GET/functions/publicApi?id={id}&download=pdf — baixar PDF

Criar Documento para Assinatura

Envia o PDF como binário (multipart/form-data), cria o envelope de assinatura, registra os signatários, envia os e-mails de convite automaticamente e configura o webhook de retorno.

POST/functions/publicApi

Cria um novo documento, abre o envelope e envia convites aos signatários.

Corpo da requisição (multipart/form-data)

Parâmetro	Tipo	Obrigatório	Descrição
file	File (binary)	Sim	Arquivo PDF em binário. O nome do arquivo é extraído automaticamente do File.
reference_id	string	Sim	Identificador único no seu sistema (ex: ID do contrato no ERP).
signers	string (JSON)	Sim	Array de signatários serializado como JSON string. Ex: [{"name":"João","email":"joao@x.com"}].
message	string	Não	Mensagem personalizada enviada no e-mail de convite.
expires_at	string (ISO 8601)	Não	Data de expiração. Padrão: 30 dias.
signature_type	string	Não	simple \| advanced \| qualified. Padrão: advanced.
delivery_method	string	Não	email \| sms \| whatsapp \| link. Padrão: email.
source_system	string	Não	Nome do sistema de origem (ex: "Arcarius ERP").
filename	string	Não	Sobrescreve o nome do arquivo (opcional — por padrão usa o nome do File enviado).

multipart/form-data (não JSON)O PDF deve ser enviado como um campo file binário em uma requisição multipart/form-data. Não defina Content-Type manualmente — o cliente HTTP define o boundary automaticamente. O campo signers é uma string JSON dentro do multipart (não um array nativo).

Exemplo — curl

bash

curl -X POST https://tesserasign.base44.app/functions/publicApi \
  -H "Authorization: Bearer tsk_live_a1b2c3d4e5f6..." \
  -F "file=@acordo-colaboracao.pdf" \
  -F "reference_id=ACORD-2026-1234" \
  -F "source_system=Arcarius ERP" \
  -F 'signers=[{"name":"João Silva","email":"joao@empresa.com","cpf":"12345678901","phone":"11999999999"},{"name":"Maria Santos","email":"maria@empresa.com","cpf":"98765432109"}]' \
  -F "message=Prezado(a), favor assinar o acordo de colaboração." \
  -F "expires_at=2026-10-25T23:59:59Z" \
  -F "signature_type=advanced"

Exemplo — JavaScript (fetch)

javascript

const formData = new FormData();
formData.append("file", pdfFile); // pdfFile = File/Blob object
formData.append("reference_id", "ACORD-2026-1234");
formData.append("signers", JSON.stringify([
  { name: "João Silva", email: "joao@empresa.com" }
]));

const res = await fetch("https://tesserasign.base44.app/functions/publicApi", {
  method: "POST",
  headers: {
    "Authorization": "Bearer tsk_live_a1b2c3d4e5f6..."
    // NÃO defina Content-Type — o fetch define o boundary do multipart automaticamente
  },
  body: formData
});

const data = await res.json();
console.log(data.document_id, data.signers[0].sign_url);

Resposta — 201 Created

json

{
  "document_id": "6f7a8b9c0d1e2f3a4b5c6d7e",
  "envelope_id": "7a8b9c0d1e2f3a4b5c6d7e8f",
  "status": "pending",
  "reference_id": "ACORD-2026-1234",
  "signers": [
    {
      "signer_id": "abc123def456",
      "name": "João Silva",
      "email": "joao@empresa.com",
      "status": "pending",
      "sign_url": "https://tesserasign.base44.app/sign/a1b2c3d4e5f6"
    },
    {
      "signer_id": "ghi789jkl012",
      "name": "Maria Santos",
      "email": "maria@empresa.com",
      "status": "pending",
      "sign_url": "https://tesserasign.base44.app/sign/b3c4d5e6f7g8"
    }
  ],
  "created_at": "2026-09-25T13:33:00.000Z"
}

O campo sign_url em cada signatário é o link de assinatura enviado por e-mail. Você pode usá-lo para redirecionar o signatário diretamente do seu sistema, se preferir não depender do e-mail.

Consultar Status do Documento

Retorna o status atual do documento, dos signatários e o link do PDF assinado (quando concluído).

GET/functions/publicApi?id={document_id}

Consulta o status de um documento criado via API.

Parâmetro	Tipo	Obrigatório	Descrição
id	string (query)	Sim	O document_id retornado na criação do documento.

bash

curl -X GET "https://tesserasign.base44.app/functions/publicApi?id=6f7a8b9c0d1e2f3a4b5c6d7e" \
  -H "Authorization: Bearer tsk_live_a1b2c3d4e5f6..."

Resposta — 200 OK (pendente)

json

{
  "document_id": "6f7a8b9c0d1e2f3a4b5c6d7e",
  "reference_id": null,
  "status": "pending",
  "signed_pdf_url": null,
  "signed_at": null,
  "created_at": "2026-09-25T13:33:00.000Z",
  "signers": [
    {
      "name": "João Silva",
      "email": "joao@empresa.com",
      "status": "pending",
      "signed_at": null
    },
    {
      "name": "Maria Santos",
      "email": "maria@empresa.com",
      "status": "pending",
      "signed_at": null
    }
  ]
}

Resposta — 200 OK (assinado)

json

{
  "document_id": "6f7a8b9c0d1e2f3a4b5c6d7e",
  "reference_id": null,
  "status": "signed",
  "signed_pdf_url": "https://storage.tesserasign.app/signed/abc123.pdf",
  "signed_at": "2026-09-25T15:45:00.000Z",
  "created_at": "2026-09-25T13:33:00.000Z",
  "signers": [
    {
      "name": "João Silva",
      "email": "joao@empresa.com",
      "status": "signed",
      "signed_at": "2026-09-25T15:30:00.000Z"
    },
    {
      "name": "Maria Santos",
      "email": "maria@empresa.com",
      "status": "signed",
      "signed_at": "2026-09-25T15:42:00.000Z"
    }
  ]
}

Baixar PDF Assinado

Quando o documento está totalmente assinado (status: "signed"), este endpoint redireciona (HTTP 302) para a URL pública do PDF assinado com todas as evidências criptográficas incorporadas.

GET/functions/publicApi?id={document_id}&download=pdf

Redireciona para o PDF assinado. Use -L (follow redirects) no curl.

bash

curl -L -X GET "https://tesserasign.base44.app/functions/publicApi?id=6f7a8b9c0d1e2f3a4b5c6d7e&download=pdf" \
  -H "Authorization: Bearer tsk_live_a1b2c3d4e5f6..." \
  -o acordo-assinado.pdf

Retorna 409 Conflict se o documento ainda não foi totalmente assinado, ou 404 Not Found se o PDF ainda não foi gerado. Aguarde o webhookdocument.signed antes de tentar o download.

Webhooks

O TesseraSign envia notificações em tempo real para o endpoint do Arcarius (https://arcarius.base44.app/functions/webhookTesseraAssinatura), configurado automaticamente na criação do documento — não é necessário informá-lo na requisição. As notificações são entregues via POST comContent-Type: application/json e um timeout de 15 segundos.

Eventos disponíveis

document.viewed

Disparado quando o signatário abre o link de assinatura pela primeira vez.

document.signed

Disparado quando todos os signatários concluem a assinatura. Inclui signed_pdf_url.

document.rejected

Disparado quando um signatário recusa assinar. Inclui decline_reason.

document.expired

Disparado quando o envelope expira sem conclusão.

Payload enviado (exemplo — document.signed)

json

{
  "event": "document.signed",
  "document_id": "6f7a8b9c0d1e2f3a4b5c6d7e",
  "envelope_id": "7a8b9c0d1e2f3a4b5c6d7e8f",
  "reference_id": "ACORD-2026-1234",
  "status": "signed",
  "signed_pdf_url": "https://storage.tesserasign.app/signed/abc123.pdf",
  "signed_at": "2026-09-25T15:45:00.000Z",
  "signers": [
    {
      "name": "João Silva",
      "cpf": "***.456.***-**",
      "email": "joao@empresa.com",
      "status": "signed",
      "signed_at": "2026-09-25T15:30:00.000Z",
      "declined_at": null,
      "decline_reason": null,
      "ip": "189.45.12.34",
      "geolocation": { "city": "São Paulo", "region": "SP" }
    }
  ],
  "occurred_at": "2026-09-25T15:45:00.000Z"
}

Exemplo de recebimento (Node.js/Express)

javascript

app.post("/webhooks/tesserasign", express.json(), (req, res) => {
  const { event, document_id, reference_id, status, signed_pdf_url } = req.body;

  switch (event) {
    case "document.viewed":
      console.log("Documento visualizado:", reference_id);
      break;
    case "document.signed":
      console.log("Documento assinado:", reference_id, "PDF:", signed_pdf_url);
      // Atualize seu ERP, salve o signed_pdf_url, etc.
      break;
    case "document.rejected":
      console.log("Documento recusado:", reference_id);
      break;
    case "document.expired":
      console.log("Documento expirado:", reference_id);
      break;
  }

  // Responda 2xx para confirmar o recebimento
  res.status(200).json({ ok: true });
});

Política de retentativas

Seu endpoint deve responder com HTTP 2xx em até 15 segundos para confirmar o recebimento.
Qualquer outro status ou timeout dispara retentativa automática.
Até 3 tentativas com backoff crescente (imediato, +1 min, +5 min).
Após 3 falhas, o webhook é marcado como failed e não retenta mais.
O evento document.viewed é enviado apenas uma vez por documento.

Códigos de Erro

Parâmetro	Tipo	Obrigatório	Descrição
400	Bad Request	Não	Parâmetros obrigatórios ausentes ou inválidos no corpo da requisição.
401	Unauthorized	Não	Chave de API ausente, inválida ou organização inativa.
404	Not Found	Não	Documento não encontrado ou não pertence à sua organização.
405	Method Not Allowed	Não	Método HTTP não suportado neste endpoint.
409	Conflict	Não	Tentativa de baixar PDF de documento ainda não assinado.
500	Server Error	Não	Erro interno inesperado. Tente novamente ou contate o suporte.

json

// Exemplo de resposta de erro
{
  "error": "reference_id is required"
}

Status de Documento

Os status retornados pela API seguem este mapeamento:

pendingDocumento criado, aguardando ação dos signatários.

viewedPelo menos um signatário abriu o documento.

signedTodos os signatários assinaram. PDF assinado disponível.

rejectedUm signatário recusou assinar.

expiredO envelope expirou sem conclusão.

Plataforma de assinatura eletrônica com validade jurídica · ICP-Brasil

Dúvidas sobre a API? Contate o administrador da sua organização.