Assin — API Reference
Documentação completa da Gateway API da plataforma Assin — o ponto de entrada para criação de envelopes, gestão de documentos, controle de signatários, automações via webhook e muito mais.
Comece aqui
- Pegue as credenciais. No painel Assin, em Desenvolvimento → API Keys, crie uma chave e copie
publicKeyesecretKey(aparece só na criação). - Escolha como integrar (abaixo). Comece em Homologação:
https://api.hml.assin.com.br. - Siga um fluxo. O mais comum é Do PDF ao envelope enviado: enviar o PDF, definir quem assina e onde, lacrar e baixar o assinado.
Autenticação
Authorization.Toda requisição leva o header Authorization: Bearer <token>. O token é um JWT HS256 assinado com a sua secretKey, com este conteúdo:
{ "publicKey": "<sua publicKey>", "iat": 1760000000, "exp": 1760003600 }
As duas chaves estão no painel Assin, em Desenvolvimento → API Keys: publicKey e secretKey (a secretKey aparece só na criação da chave, guarde-a).
Por padrão, a API Key age em nome de quem a criou, então não é preciso informar o usuário no token. Para agir em nome de outro membro ativo da empresa (ex.: cada vendedor do seu sistema), envie "moreInfo": { "userId": "<User ID>" }: uma única chave atende vários usuários. Chaves criadas antes de outubro de 2026 não têm dono: nelas o userId é obrigatório.
Gere um token novo a cada requisição ou reutilize até o exp. Exemplos:
Node.js (npm i jsonwebtoken)
const jwt = require('jsonwebtoken');
const token = jwt.sign({ publicKey }, secretKey, { algorithm: 'HS256', expiresIn: '1h' });
Python (pip install pyjwt)
import jwt, time
now = int(time.time())
token = jwt.encode({"publicKey": public_key, "iat": now, "exp": now + 3600}, secret_key, algorithm="HS256")
PHP (composer require firebase/php-jwt)
use Firebase\JWT\JWT; $token = JWT::encode(['publicKey' => $publicKey, 'iat' => time(), 'exp' => time() + 3600], $secretKey, 'HS256');
C# (System.IdentityModel.Tokens.Jwt)
var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(secretKey));
var token = new JwtSecurityToken(
claims: new[] { new Claim("publicKey", publicKey) },
expires: DateTime.UtcNow.AddHours(1),
signingCredentials: new SigningCredentials(key, SecurityAlgorithms.HmacSha256));
var jwt = new JwtSecurityTokenHandler().WriteToken(token);
| Erro | Causa |
|---|---|
401 Not authorized for perform action | publicKey inexistente ou token assinado com a secretKey errada |
401 moreInfo.userId is required in the JWT payload | Chave antiga, sem dono: envie o userId |
403 moreInfo.userId is not an active member of the API key company | O usuário não é membro ativo da empresa |
403 API key is disabled | A chave foi desativada no painel |
Base URL
| Ambiente | URL |
|---|---|
| Produção | https://api.assin.com.br |
| Homologação (testes) | https://api.hml.assin.com.br |
Todas as rotas começam com /v1. Envie Content-Type: application/json nas requisições com corpo. Chamadas servidor a servidor não precisam do header Origin.
White label
A mesma base URL atende todas as marcas. A API Key define a empresa e a marca: envelopes, documentos e modelos ficam na sua conta, os links de assinatura saem no seu domínio (sign.seudominio.com.br) e e-mails e WhatsApp usam a sua identidade visual. Não envie Origin nem x-origin-with-label: o gateway define a marca pela chave. O que é criado pela API aparece no painel, e vice-versa.
Headers Obrigatórios
Presentes nas requisições à API:
| Header | Exemplo | Quando |
|---|---|---|
Authorization | Bearer eyJhbGciOiJIUzI1NiIs... | Sempre. Token JWT (ver Autenticação) |
Content-Type | application/json | Requisições com corpo JSON |
Idempotency-Key | 5f0c2b8e-6f4a-4a39-9d3e-2f7b9d1c8a10 | Opcional, nas rotas de criação, lacre e reenvio (ver Idempotência) |
x-dynamic-authorization | token de documents-url | Só em GET /v1/documents/get-link-document |
Chamadas servidor a servidor não precisam do header Origin.
Formato dos corpos
- A maioria das rotas recebe uma lista em
data, o que permite operar vários itens de uma vez:{ "data": [ { ... } ] }. - Signatários e campos de assinatura têm o
envelopeIdfora da lista:{ "envelopeId": "...", "data": [ { ... } ] }. - Grupos, pastas, contatos, webhooks e lotes recebem
datacomo objeto:{ "data": { ... } }.
Arquivos (upload e download)
- Upload: a criação do documento devolve uma URL temporária (5 minutos). Envie o PDF com
PUTnessa URL, corpo binário,Content-Type: application/pdfe semAuthorization. - Download: as URLs de download valem 5 minutos. Peça de novo quando precisar.
Erros Padrão
| Status | Significado |
|---|---|
400 | Dados inválidos ou regra de negócio violada. A mensagem diz o motivo |
401 | Token ausente ou inválido |
403 | Chave desativada, ou recurso de outra empresa |
404 | Recurso não encontrado |
409 | Mesma Idempotency-Key ainda em processamento |
422 | Mesma Idempotency-Key usada com outro corpo ou rota |
502 | Serviço interno indisponível; tente de novo |
{
"statusCode": 400,
"error": "Some Envelope does not have a signer",
"errorCode": "UNAUTHORIZED",
"message": "Some Envelope does not have a signer",
"rejectedInputs": [{ "identifier": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "reason": "Some Envelope does not have a signer", "errorCode": 2 }]
}
Erros de validação de campo listam cada problema em message (ex.: "data[0].email" is required).
Idempotência
Rotas que criam algo, lacram ou reenviam aceitam o header Idempotency-Key (até 255 caracteres, recomendamos um UUID). Repetir a mesma operação com a mesma chave em até 24 horas devolve a primeira resposta, sem criar ou cobrar de novo (header Idempotent-Replayed: true). Use sempre ao lacrar envelopes e processar lotes.
Fluxos passo a passo
Fluxo completo: do PDF ao envelope enviado
O caminho principal: envia um PDF, define quem assina e onde, e recebe o documento assinado.
Ao lacrar, a Assin envia os convites. Quando todos assinam, o envelope vai para COMPLETED e o PDF assinado fica disponível no último passo.
-
1
Criar documentoPOST
/documents -
2
Enviar o PDFPUT
{uploadUrl} -
3
Criar envelopePOST
/envelopes -
4
Vincular o documento ao envelopePOST
/envelopes/set/documents -
5
Adicionar signatáriosPOST
/envelope-signers -
6
Posicionar campos de assinaturaPOST
/tags -
7
Lacrar e enviardebita créditosPUT
/envelopes/close -
8
Acompanhar assinaturasGET
/envelope-signers -
9
Status do envelopeGET
/envelopes -
•
Link de assinatura para seu sistemaopcionalPOST
/envelope-signers/signing-link -
10
Baixar documento assinadoGET
/envelopes/{envelopeId}/documents
Envelope a partir de modelo
Contratos padronizados: a Assin preenche um modelo .docx e gera o PDF, sem upload.
Para contratos padronizados: a Assin gera o PDF preenchido e você segue o fluxo normal, sem upload. Precisa de um modelo cadastrado (no painel ou pela pasta Referência → Modelos).
-
1
Escolher o modeloGET
/templates -
2
Gerar documento preenchidoPOST
/templates/generate-document -
3
Criar envelopePOST
/envelopes -
4
Vincular o documento geradoPOST
/envelopes/set/documents -
5
Adicionar signatáriosPOST
/envelope-signers -
6
Posicionar camposPOST
/tags -
7
Lacrar e enviardebita créditosPUT
/envelopes/close
Envelope com grupo de signatários
Mesmos signatários de sempre (diretoria, testemunhas) importados de uma vez.
Use um grupo salvo (ex.: diretoria) em vez de cadastrar signatários um a um. Requer um documento já criado (documentId, ver fluxo 01 passos 1 e 2).
Envio em massa (lote)
Um envelope por pessoa, com os mesmos documentos: centenas de envios numa chamada.
Um envelope por signatário variável, com os mesmos documentos e signatários fixos. Para adicionar mais signatários, repita o passo 4 trocando e-mail e nome (fixed: true para quem assina todos).
-
1
Criar lotePOST
/batches -
2
Adicionar documentoPOST
/batches-document -
3
Enviar o PDFPUT
{uploadUrl} -
4
Adicionar signatário variávelPOST
/batches-signer -
5
Adicionar signatário fixo (assina todos)POST
/batches-signer -
6
Definir posições dos camposPUT
/batches-document -
7
Processar lotedebita créditosPOST
/batches-envelopes/{companyId}/{batchId} -
8
Ver envelopes geradosGET
/envelopes
Receber avisos (webhooks)
Seu sistema é avisado quando alguém assina, conclui, cancela ou expira.
Configure uma vez e receba avisos de assinatura, conclusão, cancelamento e expiração. Veja o formato do aviso na descrição da pasta Referência → Webhooks.
Gerenciar envelope enviado
Reenviar convite, corrigir signatário, gerar link, bloquear ou cancelar.
Operações sobre um envelope já enviado (usa envelopeId e signerId guardados).
-
1
Reenviar convite por e-mailPOST
/envelope-signers/resend-notification/EMAIL -
2
Reenviar convite por WhatsAppPOST
/envelope-signers/resend-notification/WHATSAPP -
3
Corrigir e-mail do signatárioPUT
/envelope-signers -
4
Gerar link de assinaturaPOST
/envelope-signers/signing-link -
5
Bloquear / desbloquearPUT
/envelopes/block-envelope -
6
CancelarPUT
/envelopes/cancel
SDK Node.js
SDK oficial para Node.js 18+, tipado (TypeScript) e sem dependências. Por baixo ele usa esta mesma API, mas cuida do token, do upload dos PDFs, das retentativas seguras e do formato das requisições.
npm install @ostenverse/assin-api-node
import { Assin } from '@ostenverse/assin-api-node'
import { readFile } from 'node:fs/promises'
const assin = new Assin({
publicKey: process.env.ASSIN_PUBLIC_KEY,
secretKey: process.env.ASSIN_SECRET_KEY,
environment: 'homologation',
})
const { envelope } = await assin.envelopes.send({
title: 'Contrato de Prestação de Serviços',
description: 'Contrato anual',
documents: [{ name: 'Contrato.pdf', file: await readFile('./contrato.pdf') }],
signers: [
{
fullName: 'Maria Souza',
email: 'maria@exemplo.com.br',
fields: [{ elementType: 'SIGNATURE', page: 1, axisX: 0.1, axisY: 0.8 }],
},
],
})
const signed = await assin.envelopes.downloadSigned(envelope.id)
| Recurso | Métodos principais |
|---|---|
assin.envelopes | send, create, get, list, close, cancel, files, downloadSigned |
assin.documents | createFromFile, list, verify, delete |
assin.signers | add, list, update, remove, resend, signingLinks |
assin.fields | add, list, update, remove |
assin.templates | list, create, generateDocument |
assin.webhooks | create, setHeaders, reprocess, list, delete |
assin.batches | send (lote inteiro numa chamada), create, addDocument, addSigner, setFields, process |
assin.signerGroups, assin.folders, assin.contacts | gestão |
O send também aceita documento gerado de modelo ({ template: { id, name, values } }), grupos de signatários (signerGroups) e campos de qualquer signatário pelo e-mail (fields). Tipos de signatário, campos, canais, eventos e status são listas fechadas: o editor sugere os valores e acusa erro antes de rodar. Guia completo no README do pacote: npmjs.com/package/@ostenverse/assin-api-node.
Novidades v2.9.0
Mudanças que exigem ajuste
| Rota | O que mudou |
|---|---|
GET /v1/envelope-signers | Agora lista os signatários de um envelope: envie ?envelopeId=. Antes listava os envelopes em que o usuário da chave assina |
PUT /v1/envelopes/edit | Não aceita mais status. Use lacrar, bloquear ou cancelar |
/v1/contacts | Refeito: contatos da empresa, corpo { "data": { "name", "email", "phone" } }. PUT /v1/contacts/{id} removido |
POST /v1/batches-template/update-templates-signer/... e GET /v1/batches-template/list-templates-signer/... | Removidas (eram rotas do signatário e não funcionavam com API Key) |
| Rotas de lote | O companyId precisa ser o da empresa da API Key (403 se for outro) |
POST /v1/batches-signer | email obrigatório |
POST /v1/envelope-signers | Só com envelope em DRAFT ou BLOCK |
| Todas as respostas e webhooks | CPF, data de nascimento, imagens de assinatura e rubrica e o token de acesso do signatário não são mais retornados (proteção de dados pessoais). Nome, e-mail, telefone e status continuam |
Novidades
GET /v1/envelopes/{envelopeId}/documents: links do PDF original e do PDF assinado.POST /v1/envelope-signers/signing-link: link de assinatura para abrir no seu sistema.PUT /v1/envelope-signers: corrigir nome, e-mail ou telefone de quem ainda não assinou.PUT /v1/envelopes/documents-order: reordenar documentos.- Webhooks: evento
ENVELOPE_EXPIRED, headers próprios (PUT /v1/webhook-domains/{id}/headers) e reenvio de falhas (POST /v1/webhook-domains/reprocess). - Campos de assinatura:
TEXT_BOX, tamanho (width,height) e fonte. - Criar envelope:
notificationChannel(EMAILouWHATSAPP),folderId, reenvio automático. - SDK Node.js
@ostenverse/assin-api-nodee collection Postman para download.
Correções
- Grupos de signatários, pastas e verificação de documento voltaram a funcionar.
- Lacrar envelope com problema responde
400explicando o motivo (antes200com lista vazia). eventIddo webhook é único por signatário.- Credencial inválida ou chave desativada respondem
401/403(antes500).
Sistema de Filtros
Nas listagens que aceitam:
| Parâmetro | Exemplo | Observação |
|---|---|---|
filters | status:WAITING_SIGNATURE | campo:valor. Vários campos separados por ;, vários valores por , |
status:DRAFT,WAITING_SIGNATURE | status DRAFT ou WAITING_SIGNATURE | |
title:contrato$%25iLike%25 | contém "contrato", sem diferenciar maiúsculas (%25 = %) | |
sortBy | createdAt:DESC | ASC ou DESC |
includes | envelopeSigners,envelopeSigners.signer | relacionamentos, separados por vírgula |
page | 1, 2, 3 | número da página, começando em 1 (padrão 1) |
pageSize | 20 | máximo 100 |
Operadores depois de $: equals (padrão), not, iLike, %iLike%, iLike%, %iLike, isEmpty, isNotEmpty. Codifique % como %25 na URL.
Postman
Como usar
- No Postman, clique em Import e selecione os três arquivos.
- No canto superior direito, escolha o ambiente (comece por Homologação).
- Em Environments, preencha
publicKeyesecretKey(painel Assin → Desenvolvimento → API Keys).userIdsó em chaves antigas ou para agir em nome de outro membro. - Rode 00 · Comece aqui. Resposta 200 = credenciais certas.
- Abra o fluxo desejado e rode as requisições em ordem. Nos passos de upload, selecione o arquivo em Body → binary.
A collection também funciona no Insomnia, Bruno e Hoppscotch (importação de collection Postman v2.1).
Envelopes
O envelope agrupa documentos e signatários em um fluxo de assinatura. Ele nasce em DRAFT, recebe documentos, signatários e campos, e é lacrado para ser enviado. Depois de lacrado, só dá para gerenciar (reenviar, bloquear, cancelar).
Status do envelope
| Status | Significado |
|---|---|
DRAFT | Rascunho: ainda pode receber documentos, signatários e campos |
CREATED | Lacrado, preparando o envio (dura segundos) |
WAITING_SIGNATURE | Enviado, aguardando assinaturas |
BLOCK | Bloqueado: assinaturas pausadas |
GET_LOCATIONS, GENERATE_FINGERPRINTS, GENERATE_BLOCKCHAIN, GENERATE_FINAL_DOC, GENERATE_ICP_BRASIL, FINISHING_DOC | Todos assinaram, gerando o documento final |
COMPLETED | Concluído: documento final disponível |
CANCELED | Cancelado |
ERROR | Falha no processamento (contate o suporte) |
Cria um ou mais envelopes em DRAFT. title precisa ser único dentro da requisição.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| data[].title | body | string | obrigatório | Título |
| data[].description | body | string | obrigatório | Descrição |
| data[].expiredAt | body | ISO 8601 | opcional | Prazo para assinar. No mínimo amanhã |
| data[].notificationChannel | body | enum | opcional | EMAIL (padrão) ou WHATSAPP. Com WhatsApp, todo signatário precisa de phone e há consumo de créditos de notificação |
| data[].validationByIcp | body | boolean | opcional | Assinatura com certificado ICP-Brasil. Só se a empresa tiver ICP liberado |
| data[].folderId | body | uuid | opcional | Pasta onde o envelope fica |
| data[].allowAutoResend | body | boolean | opcional | Reenviar o convite automaticamente a quem não assinou |
| data[].resendIntervalDays | body | string | opcional | Intervalo do reenvio automático, em dias (ex.: "3") |
Erros comuns
- 400
Company not authorized:validationByIcpsem ICP liberado - 400 data de expiração anterior a amanhã
{
"data": [
{
"title": "Contrato de Prestação de Serviços",
"description": "Contrato anual com a empresa X",
"expiredAt": "<expiredAt>",
"notificationChannel": "EMAIL"
}
]
}{
"totalElements": 1,
"envelopes": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"title": "Contrato de Prestação de Serviços",
"description": "Contrato anual com a empresa X",
"status": "DRAFT",
"companyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"expiredAt": "2026-10-28T12: 00: 00.000Z",
"notificationChannel": "EMAIL",
"validationByIcp": false,
"createdAt": "2026-10-13T12: 00: 00.000Z"
}
]
}Coloca documentos dentro do envelope. O envelope precisa estar em DRAFT (ou BLOCK). A ordem do array documents é a ordem no envelope.
Para desvincular, use a mesma rota com remove no lugar de set: POST /v1/envelopes/remove/documents.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| method | path | enum | obrigatório | set (vincular) ou remove (desvincular) |
| data[].envelopeId | body | uuid | obrigatório | Envelope |
| data[].documents[].id | body | uuid | obrigatório | Documento |
Erros comuns
- 400
Document already in envelope - 400 envelope fora de
DRAFT/BLOCK
{
"data": [
{
"envelopeId": "<envelopeId>",
"documents": [
{
"id": "<documentId>"
}
]
}
]
}{
"totalElements": 1,
"entities": [
{
"envelopeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"originalDocumentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"order": 1
}
]
}Define a nova ordem dos documentos. documentIds deve conter todos os documentos do envelope, sem repetir. Envelope em DRAFT.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| data[].envelopeId | body | uuid | obrigatório | Envelope |
| data[].documentIds | body | uuid[] | obrigatório | IDs na nova ordem |
{
"data": [
{
"envelopeId": "<envelopeId>",
"documentIds": [
"<documentId>"
]
}
]
}{
"totalElements": 1,
"entities": [
{
"envelopeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"originalDocumentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"order": 1
}
]
}Lacra o envelope, debita os créditos e dispara os convites aos signatários. Use sempre Idempotency-Key: se houver timeout e você repetir com a mesma chave, não há cobrança dupla.
Requisitos: envelope em DRAFT (ou BLOCK), ao menos 1 documento e 1 signatário, créditos suficientes. Com canal WhatsApp, todo signatário precisa de telefone válido.
A resposta traz o status CREATED; em segundos ele passa a WAITING_SIGNATURE.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| data[].id | body | uuid | obrigatório | Envelope |
Erros comuns
- 400
Some Envelope not found in database: id inexistente ou de outra empresa - 400
Some Envelopes does not have a draft status - 400
Some Envelope does not have a document - 400
Some Envelope does not have a signer - 400
Company does not have enough credit - 400
Invalid phone number: canal WhatsApp com signatário sem telefone E.164
{
"data": [
{
"id": "<envelopeId>"
}
]
}{
"totalElements": 1,
"envelopes": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "CREATED"
}
]
}Lista os envelopes da empresa com filtros, ordenação, paginação e relacionamentos (ver Filtros e paginação).
- Campos filtráveis:
id,title,description,status,expiredAt,createdAt,updatedAt. includes:envelopeSigners,envelopeSigners.signer,envelopeDocuments,envelopeDocuments.originalDocument,envelopeDocuments.tags,user.
Consultar um envelope com tudo: filters=id:<envelopeId>&includes=envelopeSigners,envelopeSigners.signer,envelopeDocuments.
{
"currentPage": 1,
"pageSize": 20,
"totalPages": 1,
"totalElements": 1,
"envelopes": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"title": "Contrato",
"status": "WAITING_SIGNATURE",
"expiredAt": "2026-10-28T12: 00: 00.000Z",
"createdAt": "2026-10-13T12: 00: 00.000Z",
"envelopeSigners": [
{
"signerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"order": 0,
"signatureType": "PARTY",
"status": "PENDING",
"signer": {
"fullName": "Maria Souza",
"email": "maria@exemplo.com.br"
}
}
]
}
]
}Devolve links de download (válidos por 5 minutos) de cada documento do envelope:
original: o PDF enviado.signed: o PDF final assinado, com a página de evidências. Só existe quando o envelope estáCOMPLETED.typeéICPquando houve assinatura ICP-Brasil, senãoSUMMARY.
Chame de novo quando precisar de um link novo.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| envelopeId | path | uuid | obrigatório | Envelope |
Erros comuns
- 404
Envelope not found
{
"envelopeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "COMPLETED",
"expiresIn": 300,
"documents": [
{
"order": 1,
"original": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"alias": "Contrato.pdf",
"url": "https://...presigned..."
},
"signed": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"alias": "Contrato.pdf",
"url": "https://...presigned...",
"type": "SUMMARY"
}
}
]
}Altera título, descrição, prazo ou ICP. Permitido antes de qualquer assinatura. validationByIcp só pode mudar em DRAFT/BLOCK e exige ICP liberado na empresa. O status não pode ser alterado por aqui.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| data[].id | body | uuid | obrigatório | Envelope |
| data[].title | body | string | opcional | |
| data[].description | body | string | opcional | |
| data[].expiredAt | body | ISO 8601 | opcional | |
| data[].validationByIcp | body | boolean | opcional |
Erros comuns
- 400
Envelope status cannot be changed through edit - 400
This company does not have permission to use the ICP
{
"data": [
{
"id": "<envelopeId>",
"title": "Contrato de Prestação de Serviços (rev. 2)"
}
]
}{
"totalElements": 1,
"envelopes": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"title": "Contrato de Prestação de Serviços (rev. 2)"
}
]
}Alterna o estado: WAITING_SIGNATURE → BLOCK (pausa as assinaturas) e BLOCK → WAITING_SIGNATURE. Não funciona se algum signatário já concluiu (inclusive CARBON_COPY, que conclui ao lacrar).
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| data[].id | body | uuid | obrigatório | Envelope |
{
"data": [
{
"id": "<envelopeId>"
}
]
}{
"totalElements": 1,
"envelopes": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "BLOCK"
}
]
}Cancela o envelope (CANCELED). Os links de assinatura deixam de funcionar e o webhook ENVELOPE_CANCELLED é disparado. Não pode ser desfeito.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| data[].id | body | uuid | obrigatório | Envelope |
{
"data": [
{
"id": "<envelopeId>"
}
]
}{
"totalElements": 1,
"envelopes": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "CANCELED"
}
]
}Exclui um envelope em DRAFT. Para envelopes já enviados, use cancelar.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| envelopeId | path | uuid | obrigatório | Envelope |
Erros comuns
- 400
Status of envelope is not DRAFT
{
"totalElements": 1,
"envelopes": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
]
}Totais de envelopes da empresa.
{
"allEnvelopes": 120,
"processing": 14,
"rejected": 3,
"finished": 103
}Documents
Um documento é um PDF da sua empresa. O envio do arquivo é feito em duas etapas: primeiro você cria o registro (recebe uma URL de upload), depois envia os bytes do PDF direto para essa URL. Em seguida o documento pode ser vinculado a um ou mais envelopes.
Cria o registro do documento e devolve, em url, uma URL de upload válida por 5 minutos. O PDF ainda não foi enviado: faça o PUT do arquivo nessa URL (próxima rota).
Envie vários documentos de uma vez colocando mais itens em data. alias precisa ser único dentro da requisição.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| data[].alias | body | string | obrigatório | Nome do documento (ex.: Contrato.pdf) |
{
"data": [
{
"alias": "Contrato de Prestação de Serviços.pdf"
}
]
}{
"totalElements": 1,
"documents": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"alias": "Contrato de Prestação de Serviços.pdf",
"url": "https://<bucket>.s3.amazonaws.com/companies/.../originalDocument.pdf?X-Amz-Expires=300&...",
"createdFrom": "API",
"companyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"createdAt": "2026-10-13T12: 00: 00.000Z"
}
]
}Envia os bytes do PDF para a url recebida na criação do documento.
- Corpo: o arquivo PDF puro (binário). Não é multipart nem JSON.
- Sem header
Authorization: esta requisição vai direto ao storage, não à API. - Header
Content-Type: application/pdf. - Faça em até 5 minutos. Se expirar, crie o documento de novo.
No Postman: aba Body → binary e selecione o PDF.
curl -X PUT "$UPLOAD_URL" -H "Content-Type: application/pdf" --data-binary @contrato.pdf
200 com corpo vazio.
Lista os documentos da empresa. Aceita filters, sortBy, page e pageSize (ver Filtros e paginação). Campos filtráveis: id, alias, createdFrom, createdAt. O url de cada item é um link de download válido por 5 minutos.
{
"currentPage": 1,
"pageSize": 20,
"totalPages": 1,
"totalElements": 1,
"documents": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"alias": "Contrato.pdf",
"url": "https://...presigned...",
"createdFrom": "API",
"createdAt": "2026-10-13T12: 00: 00.000Z"
}
]
}Exclui o documento e o arquivo. Só é permitido se o documento não estiver em nenhum envelope ou se os envelopes em que ele está ainda forem DRAFT. Documentos finais (assinados) não podem ser excluídos.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| documentId | path | uuid | obrigatório | ID do documento |
204 sem corpo
Consulta a situação de um documento. Informe um dos parâmetros:
fingerprint: o hash impresso no documento final. RespostaDocument is validse for autêntico.documentId: o ID do documento original. A resposta diz em que fase ele está.
Mensagens possíveis: Document is valid, Document waiting signatures, Document was signed on DD/MM/YYYY at HH:mm., Document has been canceled, Document in generating process, Document in process to be signed, There was an error, No info about the document.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| fingerprint | query | string | opcional | Hash do documento final |
| documentId | query | uuid | opcional | ID do documento original |
Erros comuns
- 400 se nenhum parâmetro for enviado ou o documento não for encontrado
{
"message": "Document was signed on 13/10/2026 at 15: 42."
}Gera um token (válido por 5 minutos) que libera o download dos documentos informados em GET /v1/documents/get-link-document. Para baixar documentos de um envelope, prefira GET /v1/envelopes/{envelopeId}/documents, que é mais simples e inclui o PDF assinado.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| data[].id | body | uuid | obrigatório | ID do documento |
{
"data": [
{
"id": "<documentId>"
}
]
}{
"token": "eyJhbGciOiJIUzI1NiIs..."
}Usa o token de POST /v1/envelopes/documents-url no header x-dynamic-authorization e devolve links de download (válidos por 5 minutos) dos documentos originais. Não retorna o PDF assinado: use GET /v1/envelopes/{envelopeId}/documents.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| x-dynamic-authorization | header | string | obrigatório | Token gerado em documents-url |
{
"totalElements": 1,
"documents": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"alias": "Contrato.pdf",
"url": "https://...presigned..."
}
]
}Templates
Modelos são arquivos .docx com campos no formato {{nomeDoCampo}}. A Assin preenche os campos e gera um PDF, que vira um documento normal para usar em envelopes.
Lista os modelos ativos e inativos. keys são os campos que precisam ser preenchidos. Aceita filters, sortBy, page, pageSize.
{
"totalElements": 1,
"templates": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"alias": "Contrato CLT",
"description": "Modelo padrão",
"isActive": true,
"file": "https://...presigned .docx...",
"keys": [
{
"alias": "nomeColaborador",
"description": "Nome",
"maxSize": 100
}
]
}
]
}Cria o modelo e devolve em file uma URL de upload válida por 5 minutos para o .docx. Envie o arquivo com PUT nessa URL, corpo binário e header Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document.
Cada item de keys descreve um campo {{alias}} existente no .docx.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| data[].alias | body | string | obrigatório | Nome do modelo |
| data[].description | body | string | obrigatório | |
| data[].keys[].alias | body | string | obrigatório | Nome do campo no .docx, sem as chaves |
| data[].keys[].description | body | string | obrigatório | Descrição do campo |
| data[].keys[].maxSize | body | integer | obrigatório | Tamanho máximo do valor |
{
"data": [
{
"alias": "Contrato CLT",
"description": "Modelo padrão de contratação",
"keys": [
{
"alias": "nomeColaborador",
"description": "Nome completo",
"maxSize": 120
},
{
"alias": "cpf",
"description": "CPF",
"maxSize": 14
}
]
}
]
}{
"totalElements": 1,
"templates": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"alias": "Contrato CLT",
"isActive": true,
"file": "https://<bucket>.s3.amazonaws.com/...docx?X-Amz-Expires=300&..."
}
]
}Envia o arquivo .docx para a URL recebida na criação do modelo. Corpo binário, sem Authorization.
200 com corpo vazio.
Preenche o modelo e gera um PDF. O id devolvido é um documento comum: vincule-o a um envelope com POST /v1/envelopes/set/documents.
key deve ser igual ao alias do campo no modelo. Valores maiores que maxSize ou campos inexistentes voltam em rejectedInputs.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| data[].templateId | body | uuid | obrigatório | Modelo |
| data[].documents[].alias | body | string | obrigatório | Nome do documento gerado |
| data[].documents[].keys[].key | body | string | obrigatório | Campo |
| data[].documents[].keys[].description | body | string | obrigatório | |
| data[].documents[].keys[].value | body | string | obrigatório | Valor |
{
"data": [
{
"templateId": "<templateId>",
"documents": [
{
"alias": "Contrato - João Silva",
"keys": [
{
"key": "nomeColaborador",
"description": "Nome completo",
"value": "João Silva"
},
{
"key": "cpf",
"description": "CPF",
"value": "123.456.789-00"
}
]
}
]
}
]
}{
"totalElements": 1,
"entities": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"alias": "Contrato - João Silva",
"url": "https://...presigned...",
"createdFrom": "GENERATE_BY_ASSIN"
}
]
}true no fim da URL ativa, false desativa.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| status | path | boolean | obrigatório | true ou false |
| data[].id | body | uuid | obrigatório | Modelo |
{
"data": [
{
"id": "<templateId>"
}
]
}{
"totalElements": 1,
"templates": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isActive": true
}
]
}Exclui um modelo criado pelo usuário da API Key.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| data[].id | body | uuid | obrigatório | Modelo |
{
"data": [
{
"id": "<templateId>"
}
]
}{
"totalElements": 1,
"templates": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
]
}Envelope Signers
Quem assina (ou aprova, testemunha, recebe cópia). Nas rotas de signatários o envelopeId fica fora do data. O identificador de cada signatário no envelope é o signerId: ele é usado nos campos de assinatura, no reenvio e no link de assinatura.
Ordem: order: 0 em todos = todos assinam ao mesmo tempo. order: 1, 2, 3... = cada um recebe o convite depois que o anterior assina. Não misture 0 com valores maiores.
Status do signatário
PENDING aguardando · SIGNED / COMPLETED assinou · REJECTED recusou.
Adiciona signatários ao envelope. Envelope em DRAFT ou BLOCK. email precisa ser único no envelope.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| envelopeId | body | uuid | obrigatório | Envelope |
| data[].fullName | body | string | obrigatório | Nome completo |
| data[].email | body | string | obrigatório | |
| data[].order | body | integer | obrigatório | 0 = paralelo; 1, 2, 3... = sequencial |
| data[].signatureType | body | enum | obrigatório | PARTY (parte), WITNESS (testemunha), APPROVER (aprovador), CLIENT, SELLER, MANAGER, ACKNOWLEDGE (ciência), ACKNOWLEDGE_RECEIPT (ciência de recebimento), CARBON_COPY (só recebe cópia, não assina) |
| data[].requirePersonalDocument | body | boolean | obrigatório | Pede foto de documento + selfie (validação biométrica) |
| data[].requireEmailToken | body | boolean | obrigatório | Pede código enviado por e-mail antes de assinar |
| data[].phone | body | string | opcional | Formato E.164: +5511999999999. Obrigatório com canal WhatsApp |
Erros comuns
- 400
Signers can only be added while the envelope is in DRAFT or BLOCK - 400 e-mail repetido no envelope
- 400
Order must be zero (0)/Order must be greater than zero (0): mistura deorder0 com maior que 0, inclusive com os signatários já existentes
{
"envelopeId": "<envelopeId>",
"data": [
{
"fullName": "Maria Souza",
"email": "maria@exemplo.com.br",
"phone": "+5511999999999",
"order": 0,
"signatureType": "PARTY",
"requirePersonalDocument": false,
"requireEmailToken": false
},
{
"fullName": "João Lima",
"email": "joao@exemplo.com.br",
"order": 0,
"signatureType": "WITNESS",
"requirePersonalDocument": false,
"requireEmailToken": false
}
]
}{
"totalElements": 2,
"envelopeSigners": [
{
"signerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"envelopeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"order": 0,
"signatureType": "PARTY",
"status": "PENDING",
"requirePersonalDocument": false,
"requireEmailToken": false,
"signer": {
"fullName": "Maria Souza",
"email": "maria@exemplo.com.br"
}
}
]
}Lista os signatários de um envelope, na ordem de assinatura, com o status de cada um.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| envelopeId | query | uuid | obrigatório | Envelope |
Erros comuns
- 400
Envelope not found
{
"totalElements": 2,
"envelopeSigners": [
{
"signerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"envelopeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"order": 0,
"signatureType": "PARTY",
"status": "COMPLETED",
"requirePersonalDocument": false,
"requireEmailToken": false,
"createdAt": "2026-10-13T12: 00: 00.000Z",
"updatedAt": "2026-10-13T15: 42: 00.000Z",
"signer": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"fullName": "Maria Souza",
"email": "maria@exemplo.com.br",
"phone": "+5511999999999"
}
}
]
}Corrige nome, e-mail ou telefone de quem ainda não assinou (envelope em DRAFT ou WAITING_SIGNATURE). Se o e-mail mudar com o envelope já enviado, a Assin reenvia o convite para o novo endereço e passa a exigir código por e-mail. Se a pessoa já assinou outros envelopes, nome e e-mail ficam travados (a identidade dela é a mesma em todos): remova o signatário e adicione outro.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| envelopeId | body | uuid | obrigatório | Envelope |
| data[].signerId | body | uuid | obrigatório | Signatário |
| data[].fullName | body | string | opcional | |
| data[].email | body | string | opcional | |
| data[].phone | body | string | opcional | E.164 |
{
"envelopeId": "<envelopeId>",
"data": [
{
"signerId": "<signerId>",
"email": "maria.souza@exemplo.com.br"
}
]
}{
"totalElements": 1,
"envelopeSigners": [
{
"signerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "PENDING"
}
]
}Remove signatários que ainda não assinaram. Envelope em DRAFT, BLOCK, CREATED ou WAITING_SIGNATURE.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| envelopeId | body | uuid | obrigatório | Envelope |
| data[].signerId | body | uuid | obrigatório | Signatário |
Erros comuns
- 400
Envelope signer has already signed and cannot be removed - 400
Signers cannot be removed from an envelope with this status
{
"envelopeId": "<envelopeId>",
"data": [
{
"signerId": "<signer2Id>"
}
]
}{
"totalElements": 1,
"envelopeSigners": [
{
"signerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
]
}Reenvia o convite de assinatura. Canal no fim da URL: EMAIL, WHATSAPP ou SMS.
Só para signatários PENDING, com envelope em WAITING_SIGNATURE. Intervalo mínimo de 1 minuto entre envios para o mesmo signatário, contando também o convite enviado ao lacrar. Para SMS/WhatsApp, o signatário precisa ter telefone (ou informe number).
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| type | path | enum | obrigatório | EMAIL, WHATSAPP ou SMS |
| envelopeId | body | uuid | obrigatório | Envelope |
| data[].signerId | body | uuid | obrigatório | Signatário |
| data[].number | body | string | opcional | Telefone E.164 para SMS/WhatsApp |
{
"envelopeId": "<envelopeId>",
"data": [
{
"signerId": "<signerId>"
}
]
}201 com corpo vazio.
Gera o link para o signatário assinar, para você abrir no seu sistema ou enviar pelo seu canal. Envelope em WAITING_SIGNATURE, signatário PENDING e que não seja CARBON_COPY.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| envelopeId | body | uuid | obrigatório | Envelope |
| data[].signerId | body | uuid | obrigatório | Signatário |
{
"envelopeId": "<envelopeId>",
"data": [
{
"signerId": "<signerId>"
}
]
}{
"totalElements": 1,
"signingLinks": [
{
"signerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"url": "https://sign.assin.com.br/?access=eyJhbGciOi..."
}
]
}Totais de envelopes em que o usuário dono da API Key é signatário.
{
"allEnvelopes": 8,
"processing": 2,
"rejected": 0,
"finished": 6
}Signer Groups
Listas de signatários que se repetem (ex.: diretoria, testemunhas fixas). Em vez de adicionar um a um, importe o grupo inteiro para o envelope. Nestas rotas data é um objeto.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| data.name | body | string | obrigatório | 1 a 100 caracteres |
| data.members[].fullName | body | string | obrigatório | |
| data.members[].email | body | string | obrigatório | |
| data.members[].signatureType | body | enum | obrigatório | Mesmos tipos de signatário |
| data.members[].order | body | integer | obrigatório | 0 = paralelo |
{
"data": {
"name": "Diretoria",
"members": [
{
"fullName": "Carlos Mendes",
"email": "carlos@exemplo.com.br",
"signatureType": "PARTY",
"order": 0
},
{
"fullName": "Ana Prado",
"email": "ana@exemplo.com.br",
"signatureType": "APPROVER",
"order": 0
}
]
}
}{
"totalElements": 1,
"entities": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Diretoria",
"companyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"members": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"fullName": "Carlos Mendes",
"email": "carlos@exemplo.com.br",
"signatureType": "PARTY",
"order": 0
}
]
}
]
}Lista os grupos da empresa com seus membros.
{
"totalElements": 1,
"entities": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Diretoria",
"members": [
{
"fullName": "Carlos Mendes",
"email": "carlos@exemplo.com.br",
"signatureType": "PARTY",
"order": 0
}
]
}
]
}Adiciona os membros do grupo como signatários do envelope (DRAFT). Quem já está no envelope é ignorado.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| data.groupId | body | uuid | obrigatório | Grupo |
| data.envelopeId | body | uuid | obrigatório | Envelope |
Erros comuns
- 400
Envelope must be in DRAFT status - 400
No new signers to import - 404 grupo ou envelope não encontrado
{
"data": {
"groupId": "<groupId>",
"envelopeId": "<envelopeId>"
}
}{
"totalElements": 2,
"entities": [
{
"envelopeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"signerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"signatureType": "PARTY",
"order": 0,
"status": "PENDING"
}
]
}Substitui nome e membros (envie a lista completa). Só quem criou o grupo pode alterar.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| id | path | uuid | obrigatório | Grupo |
| data.name | body | string | obrigatório | |
| data.members | body | array | obrigatório | Lista completa |
{
"data": {
"name": "Diretoria 2026",
"members": [
{
"fullName": "Carlos Mendes",
"email": "carlos@exemplo.com.br",
"signatureType": "PARTY",
"order": 0
}
]
}
}{
"totalElements": 1,
"entities": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Diretoria 2026"
}
]
}Só quem criou o grupo pode excluir.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| id | path | uuid | obrigatório | Grupo |
{
"totalElements": 1,
"entities": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
]
}Folders
Organizam os envelopes do usuário da API Key dentro da empresa. Pastas podem ter subpastas (parentId). Para criar um envelope já dentro de uma pasta, envie folderId na criação do envelope. Nestas rotas data é um objeto.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| data.name | body | string | obrigatório | 1 a 100 caracteres |
| data.parentId | body | uuid | null | opcional | Pasta-mãe |
{
"data": {
"name": "Contratos 2026"
}
}{
"totalElements": 1,
"entities": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Contratos 2026",
"parentId": null,
"companyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
]
}Retorna a árvore de pastas; subpastas vêm em children.
{
"totalElements": 1,
"entities": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Contratos 2026",
"parentId": null,
"children": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Fornecedores",
"parentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"children": []
}
]
}
]
}Envie name e/ou parentId. Sem parentId, a pasta fica onde está; parentId: null move para a raiz.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| id | path | uuid | obrigatório | Pasta |
| data.name | body | string | opcional | |
| data.parentId | body | uuid | null | opcional |
Erros comuns
- 404
Folder not found - 400 mover para ela mesma ou para uma subpasta
{
"data": {
"name": "Contratos 2026 - Assinados"
}
}{
"totalElements": 1,
"entities": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Contratos 2026 - Assinados"
}
]
}As subpastas sobem para a pasta-mãe.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| id | path | uuid | obrigatório | Pasta |
{
"totalElements": 0,
"entities": []
}Contacts
Agenda de contatos da empresa, usada para preencher signatários. Criar e excluir exige que o usuário da API Key seja gestor da empresa.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| data.name | body | string | obrigatório | 1 a 150 |
| data.email | body | string | obrigatório | |
| data.phone | body | string | opcional |
Erros comuns
- 400
This contact exist
{
"data": {
"name": "Maria Souza",
"email": "maria@exemplo.com.br",
"phone": "+5511999999999"
}
}{
"totalElements": 1,
"entities": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"signerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"companyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"createdAt": "2026-10-13T12: 00: 00.000Z"
}
]
}search busca por nome, e-mail ou telefone (com search, a paginação é ignorada e voltam até pageSize resultados).
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| page | query | integer | opcional | Número da página, a partir de 1 (padrão 1) |
| pageSize | query | integer | opcional | 1 a 100 (padrão 20) |
| search | query | string | opcional | Busca |
{
"totalElements": 1,
"entities": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Maria Souza",
"email": "maria@exemplo.com.br",
"phone": "+5511999999999",
"envelopeSigners": 4,
"createdAt": "2026-10-13T12: 00: 00.000Z"
}
]
}Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| id | path | uuid | obrigatório | Contato |
Erros comuns
- 404
Contact not found
204 sem corpo
Webhook Domains
Cadastre uma URL e a Assin avisa seu sistema quando algo acontece, sem você precisar consultar. Nestas rotas data é um objeto.
Eventos
| Evento | Quando |
|---|---|
SIGNER_COMPLETED | Um signatário concluiu (não dispara para CARBON_COPY) |
ENVELOPE_FINISHED | Todos assinaram e o PDF final está pronto. Baixe com GET /v1/envelopes/{id}/documents |
ENVELOPE_CANCELLED | O envelope foi cancelado |
ENVELOPE_EXPIRED | O prazo venceu sem todas as assinaturas (verificação diária, por volta das 09:00 de Brasília) |
Como o aviso chega
POSTna sua URL,Content-Type: application/json, timeout de 10 segundos. Responda 2xx rapidamente e processe depois.- Header
x-assin-event-id: identificador único do evento (o mesmo do campoeventId). Use para ignorar duplicados. - Os headers que você cadastrou (ex.:
Authorization), para validar que o aviso veio da Assin. - Não há nova tentativa automática. Se seu endpoint falhar, use
POST /v1/webhook-domains/reprocess.
Corpo (exemplo SIGNER_COMPLETED, resumido)
{
"event": "SIGNER_COMPLETED",
"eventId": "6f1c2a4e-8b0d-5c3a-9e7f-1a2b3c4d5e6f",
"envelope": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"companyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"title": "Contrato de Prestação de Serviços",
"status": "WAITING_SIGNATURE",
"expiredAt": "2026-10-28T12:00:00.000Z",
"conclusionDate": null,
"validationByIcp": false,
"notificationChannel": "EMAIL",
"envelopeSigners": [
{
"signerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"envelopeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"order": 0,
"signatureType": "PARTY",
"status": "COMPLETED",
"signer": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"fullName": "Maria Souza",
"email": "maria@exemplo.com.br"
}
}
]
},
"signer": {
"signerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"envelopeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "COMPLETED",
"signatureType": "PARTY",
"signer": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"fullName": "Maria Souza",
"email": "maria@exemplo.com.br"
}
}
}
Os outros eventos têm o mesmo formato, sem o campo signer. envelope traz o envelope completo com todos os signatários.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| data.domain | body | URL | obrigatório | Endereço que recebe os avisos (http ou https) |
| data.events | body | enum[] | obrigatório | Um ou mais eventos |
| data.description | body | string | opcional | Até 255 caracteres |
{
"data": {
"domain": "https://seusistema.com.br/webhooks/assin",
"description": "Produção",
"events": [
"SIGNER_COMPLETED",
"ENVELOPE_FINISHED",
"ENVELOPE_CANCELLED",
"ENVELOPE_EXPIRED"
]
}
}{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"domain": "https://seusistema.com.br/webhooks/assin",
"description": "Produção",
"isActive": true,
"headers": {},
"eventSubscriptions": [
{
"eventType": "SIGNER_COMPLETED"
},
{
"eventType": "ENVELOPE_FINISHED"
}
]
}Adiciona ou substitui headers enviados em todos os avisos (ex.: um segredo para você validar). Até 20 headers; nomes são gravados em minúsculas; valores aparecem mascarados nas respostas. Não é permitido Content-Type, Content-Length, Host, Transfer-Encoding e Connection.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| id | path | uuid | obrigatório | Webhook |
| data.headers | body | objeto | obrigatório | { "Nome": "valor" } |
{
"data": {
"headers": {
"Authorization": "Bearer seu-segredo-aqui"
}
}
}{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"headers": {
"authorization": "Bear…"
}
}Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| id | path | uuid | obrigatório | Webhook |
| data.names | body | string[] | obrigatório | Nomes dos headers |
{
"data": {
"names": [
"authorization"
]
}
}{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"headers": {}
}{
"totalElements": 1,
"data": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"domain": "https://seusistema.com.br/webhooks/assin",
"isActive": true,
"headers": {
"authorization": "Bear…"
},
"eventSubscriptions": [
{
"eventType": "ENVELOPE_FINISHED"
}
]
}
]
}Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| id | path | uuid | obrigatório | Webhook |
| data.domain | body | URL | opcional | |
| data.events | body | enum[] | opcional | |
| data.description | body | string | opcional | |
| data.isActive | body | boolean | opcional | false para pausar os avisos |
Erros comuns
- 404 webhook não encontrado
{
"data": {
"isActive": false
}
}{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isActive": false
}Reenvia os avisos (a última tentativa de cada envelope e evento) para os webhooks ativos. Até 500 por chamada.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| data.onlyFailed | body | boolean | opcional | Só os que não receberam 2xx (padrão true) |
| data.envelopeIds | body | uuid[] | opcional | Limitar a envelopes (até 500) |
| data.from | body | ISO 8601 | opcional | Início do período |
| data.to | body | ISO 8601 | opcional | Fim do período |
{
"data": {
"onlyFailed": true
}
}{
"matched": 3,
"resent": 3,
"succeeded": 3,
"failed": 0,
"skipped": 0,
"notReprocessable": 0,
"truncated": false
}Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| id | path | uuid | obrigatório | Webhook |
204 sem corpo
Batches (lote em massa)
Gera um envelope por signatário variável, todos com os mesmos documentos e os mesmos signatários fixos. Exemplo: o mesmo termo para 300 colaboradores, cada um no seu envelope, com o RH assinando todos.
Etapas
- Criar o lote.
- Adicionar os documentos do lote (cada um gera uma URL de upload, como em Documentos).
- Adicionar signatários:
fixed: trueentra em todos os envelopes;fixed: falsegera um envelope para cada. - (Opcional) Definir as posições dos campos em cada documento.
- Processar: os envelopes são criados, lacrados e enviados.
Nas rotas de lote data é um objeto. O companyId que aparece em algumas URLs é o da sua empresa; ele vem na resposta da criação do lote (a collection guarda sozinha).
Atenção às posições no lote: cada campo definido no documento do lote é aplicado a todos os signatários de cada envelope, na mesma posição. Defina ao menos 2 campos por documento.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| data.name | body | string | obrigatório | |
| data.description | body | string | obrigatório |
{
"data": {
"name": "Termo de confidencialidade - Out/2026",
"description": "Envio para todos os colaboradores"
}
}{
"totalElements": 1,
"entities": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Termo de confidencialidade - Out/2026",
"description": "Envio para todos os colaboradores",
"companyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "DRAFT"
}
]
}Cria o documento do lote e devolve a URL de upload (5 minutos). Envie o PDF com PUT nessa URL, igual a Documentos.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| data.batchId | body | uuid | obrigatório | Lote |
| data.alias | body | string | obrigatório | Nome do documento |
{
"data": {
"batchId": "<batchId>",
"alias": "Termo de confidencialidade.pdf"
}
}{
"statusCode": 201,
"message": "Successfully create document",
"data": {
"documents": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"alias": "Termo de confidencialidade.pdf",
"url": "https://<bucket>.s3.amazonaws.com/...?X-Amz-Expires=300&..."
}
]
}
}Corpo binário com o PDF, sem Authorization. Mesmas regras do upload de documentos.
200 com corpo vazio.
Adicione um por chamada. fixed: true = entra em todos os envelopes (ex.: o RH). fixed: false = cada um gera um envelope.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| data.batchId | body | uuid | obrigatório | Lote |
| data.email | body | string | obrigatório | |
| data.fullName | body | string | opcional | |
| data.signatureType | body | enum | obrigatório | Tipos de signatário, exceto CARBON_COPY |
| data.fixed | body | boolean | opcional | Padrão false |
| data.order | body | integer | opcional | |
| data.requirePersonalDocument | body | boolean | opcional | Padrão false |
| data.requireEmailToken | body | boolean | opcional | Padrão false |
{
"data": {
"batchId": "<batchId>",
"fixed": false,
"signatureType": "PARTY",
"email": "colaborador1@exemplo.com.br",
"fullName": "Colaborador Um"
}
}{
"totalElements": 1,
"entities": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"batchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"signerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"fixed": false
}
]
}Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| batchId | path | uuid | obrigatório | Lote |
{
"totalElements": 1,
"entities": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"batchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"signerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"fixed": false,
"envelopeSigner": {
"order": 0,
"signatureType": "PARTY"
}
}
]
}Define os campos do documento. Coordenadas iguais às de Campos de assinatura (frações 0 a 1, a partir do canto superior esquerdo). envelopeDocumentId é o id do documento do lote; envelopeSignerId é o signerId de um signatário do lote.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| data.batchId | body | uuid | obrigatório | Lote |
| data.documentId | body | uuid | obrigatório | Documento do lote |
| data.tags[] | body | array | obrigatório | fixed, envelopeSignerId, envelopeDocumentId, elementType, page, axisX, axisY, angle |
{
"data": {
"batchId": "<batchId>",
"documentId": "<batchDocumentId>",
"tags": [
{
"fixed": false,
"envelopeSignerId": "<batchSignerId>",
"envelopeDocumentId": "<batchDocumentId>",
"elementType": "SIGNATURE",
"page": 1,
"axisX": 0.1,
"axisY": 0.8,
"angle": 0
},
{
"fixed": false,
"envelopeSignerId": "<batchSignerId>",
"envelopeDocumentId": "<batchDocumentId>",
"elementType": "FULL_NAME",
"page": 1,
"axisX": 0.1,
"axisY": 0.88,
"angle": 0
}
]
}
}{
"totalElements": 1,
"entities": [
{
"batchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"documentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
]
}Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| filters | query | string | obrigatório | batchId:<uuid> |
{
"totalElements": 1,
"batchesDocuments": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"batchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"documentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"tags": "[...]"
}
]
}Cria um envelope por signatário variável, adiciona documentos, signatários fixos e campos, lacra e envia. O lote precisa estar em DRAFT. Créditos são debitados por envelope.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| companyId | path | uuid | obrigatório | Sua empresa |
| batchId | path | uuid | obrigatório | Lote |
Erros comuns
- 400
Batch not found - 400
Signers not found
201 com corpo vazio. Acompanhe os envelopes em `GET /v1/envelopes`.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| companyId | path | uuid | obrigatório | Sua empresa |
{
"totalElements": 1,
"batches": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Termo de confidencialidade - Out/2026",
"status": "PROCESS",
"createdAt": "2026-10-13T12: 00: 00.000Z"
}
]
}Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| batchId | path | uuid | obrigatório | Lote |
| signerId | path | uuid | obrigatório | Signatário |
201 com corpo vazio.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| companyId | path | uuid | obrigatório | |
| batchId | path | uuid | obrigatório | |
| signerId | path | uuid | obrigatório | O signerId do signatário |
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| data.batchId | body | uuid | obrigatório | |
| data.documentId | body | uuid | obrigatório |
{
"data": {
"batchId": "<batchId>",
"documentId": "<batchDocumentId>"
}
}Exclui o lote com seus documentos, signatários e modelos. Envelopes já gerados não são afetados.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| companyId | path | uuid | obrigatório | |
| batchId | path | uuid | obrigatório |
Em vez de PDF fixo, o lote usa um modelo .docx preenchido por signatário a partir de uma planilha (próxima rota).
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| batchId | path | uuid | obrigatório | |
| companyId | path | uuid | obrigatório | |
| data.templateId | body | uuid | obrigatório | Modelo |
Erros comuns
- 400
Document already exists for this batch
{
"data": {
"templateId": "<templateId>"
}
}{
"entities": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"batchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"templateId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
]
}Envio multipart/form-data com o campo file. A planilha precisa de uma coluna email e uma coluna para cada campo do modelo. Cada linha preenche o modelo do signatário (variável, já adicionado ao lote) com aquele e-mail; linhas sem signatário correspondente são ignoradas.
Parâmetros
| Campo | Onde | Tipo | Descrição | |
|---|---|---|---|---|
| file | form | arquivo | obrigatório | .xlsx |
Erros comuns
- 400
Key e-mail not found - 400
No data found in the Excel file
file: <Planilha .xlsx>
{
"entities": [
{
"message": "Excel file processed successfully"
}
]
}{
"entities": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"batchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Contrato CLT",
"keys": []
}
]
}No lote com modelo, cada signatário confere os próprios dados antes de assinar. Esta rota reenvia esse pedido.
201 com corpo vazio.