Pular para o conteúdo principal

Signature Requests

Gerenciamento de requisições de assinatura eletrônica.

Endpoints

MétodoEndpointDescriçãoPermissão
POST/api/v1/esignature/requestsCriar requisiçãoESIGNATURE_CREATE
POST/api/v1/esignature/requests/from-templateCriar de templateESIGNATURE_CREATE
GET/api/v1/esignature/requestsListar requisiçõesESIGNATURE_READ
GET/api/v1/esignature/requests/:idObter requisiçãoESIGNATURE_READ
POST/api/v1/esignature/requests/:id/cancelCancelar requisiçãoESIGNATURE_CREATE
POST/api/v1/esignature/requests/:id/resendReenviar requisiçãoESIGNATURE_CREATE
GET/api/v1/esignature/requests/:id/downloadDownload documento assinadoESIGNATURE_READ
DELETE/api/v1/esignature/requests/:idExcluir requisiçãoESIGNATURE_DELETE

Atributos da Requisição

CampoTipoDescrição
titlestringTítulo da requisição
messagestringMensagem para os signatários
statusenumStatus: DRAFT, SENT, VIEWED, PARTIALLY_SIGNED, COMPLETED, DECLINED, EXPIRED, CANCELLED
businessIdstringID de referência do negócio (ex: ID do contrato)
templateIdstringID do template usado (se aplicável)
templateNamestringNome do template usado
viewUrlstringURL para visualização da requisição
expiresAtdatetimeData de expiração
completedAtdatetimeData de conclusão
createdAtdatetimeData de criação
updatedAtdatetimeData da última atualização
createdBystringID do usuário que criou

Atributos do Signatário

CampoTipoDescrição
namestringNome do signatário
emailstringE-mail do signatário
ordernumberOrdem de assinatura (1, 2, 3...)
statusenumStatus: PENDING, SENT, VIEWED, SIGNED, DECLINED
signingUrlstringURL para o signatário assinar
sentAtdatetimeData do envio do e-mail
viewedAtdatetimeData da visualização
signedAtdatetimeData da assinatura
declinedAtdatetimeData da recusa
declineReasonstringMotivo da recusa

Widgets

Widgets são elementos posicionados no documento para coleta de informações.

CampoTipoObrigatórioDescrição
typeenumSimsignature, text, date, checkbox
signerIdstringNãoID/referência do signatário
pagenumberSimNúmero da página (começando em 1)
xnumberSimPosição X em pontos
ynumberSimPosição Y em pontos
widthnumberNãoLargura em pontos
heightnumberNãoAltura em pontos
requiredbooleanNãoSe é obrigatório
labelstringNãoRótulo do campo

Tipos de Widget

TipoDescriçãoUso comum
signatureCampo de assinaturaAssinatura digital do signatário
textCampo de textoNome completo, cargo, etc.
dateCampo de dataData da assinatura
checkboxCaixa de seleçãoAceite de termos

Criar Requisição

POST /api/v1/esignature/requests

Cria uma nova requisição de assinatura.

Atributos

CampoTipoObrigatórioDescrição
titlestringSimTítulo da requisição (max 255)
messagestringNãoMensagem para signatários (max 2000)
configIduuidNãoID da configuração do provedor (usa default se omitido)
businessIdstringNãoID de referência do negócio (max 100)
expiresInDaysnumberNãoDias até expirar (1-365)
fileIduuidCondicionalID do arquivo no File Storage
fileBase64stringCondicionalArquivo em base64
fileNamestringCondicionalNome do arquivo (obrigatório com fileBase64)
signersarraySimLista de signatários (mín. 1)
widgetsarrayNãoPosicionamento de campos
Documento

Você deve fornecer um dos seguintes: fileId (referência ao File Storage) ou fileBase64 + fileName (documento embutido).

Estrutura do Signatário

CampoTipoObrigatórioDescrição
namestringSimNome do signatário (max 255)
emailstringSimE-mail válido (max 255)
ordernumberNãoOrdem de assinatura (default: 1)
curl -X POST 'https://e-signature.stg.catalisa.app/api/v1/esignature/requests' \
-H 'Authorization: Bearer SEU_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"data": {
"type": "signature-request",
"attributes": {
"title": "Contrato de Prestação de Serviços",
"message": "Por favor, assine o contrato anexo.",
"businessId": "contract-2024-001",
"expiresInDays": 7,
"fileBase64": "JVBERi0xLjQK...",
"fileName": "contrato.pdf",
"signers": [
{ "name": "João Silva", "email": "joao@empresa.com", "order": 1 },
{ "name": "Maria Santos", "email": "maria@cliente.com", "order": 2 }
],
"widgets": [
{ "type": "signature", "page": 1, "x": 100, "y": 200, "width": 200, "height": 50 },
{ "type": "signature", "page": 1, "x": 400, "y": 200, "width": 200, "height": 50 },
{ "type": "date", "page": 1, "x": 100, "y": 150, "label": "Data" }
]
}
}
}'

Resposta

{
"data": {
"type": "signature-request",
"id": "550e8400-e29b-41d4-a716-446655440000",
"links": {
"self": "/api/v1/esignature/requests/550e8400-e29b-41d4-a716-446655440000"
},
"attributes": {
"title": "Contrato de Prestação de Serviços",
"message": "Por favor, assine o contrato anexo.",
"status": "SENT",
"businessId": "contract-2024-001",
"viewUrl": "https://opensign.example.com/view/abc123",
"expiresAt": "2024-01-22T10:30:00Z",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"createdBy": "550e8400-e29b-41d4-a716-446655440001"
},
"relationships": {
"signers": {
"data": [
{
"type": "signer",
"id": "550e8400-e29b-41d4-a716-446655440002",
"attributes": {
"name": "João Silva",
"email": "joao@empresa.com",
"order": 1,
"status": "SENT",
"signingUrl": "https://opensign.example.com/sign/xyz789",
"sentAt": "2024-01-15T10:30:05Z"
}
},
{
"type": "signer",
"id": "550e8400-e29b-41d4-a716-446655440003",
"attributes": {
"name": "Maria Santos",
"email": "maria@cliente.com",
"order": 2,
"status": "PENDING"
}
}
]
}
}
},
"links": {
"self": "/api/v1/esignature/requests/550e8400-e29b-41d4-a716-446655440000"
}
}

Criar de Template

POST /api/v1/esignature/requests/from-template

Cria uma requisição de assinatura a partir de um template do provedor.

Atributos

CampoTipoObrigatórioDescrição
templateIdstringSimID do template no provedor
titlestringSimTítulo da requisição (max 255)
messagestringNãoMensagem para signatários (max 2000)
configIduuidNãoID da configuração do provedor
businessIdstringNãoID de referência do negócio
expiresInDaysnumberNãoDias até expirar (1-365)
signersarraySimLista de signatários
fieldValuesobjectNãoValores para campos do template
curl -X POST 'https://e-signature.stg.catalisa.app/api/v1/esignature/requests/from-template' \
-H 'Authorization: Bearer SEU_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"data": {
"type": "signature-request",
"attributes": {
"templateId": "tpl_abc123",
"title": "Contrato de Trabalho - João Silva",
"message": "Segue o contrato para assinatura.",
"businessId": "employee-2024-001",
"expiresInDays": 5,
"signers": [
{ "name": "João Silva", "email": "joao@empresa.com", "order": 1 },
{ "name": "RH Empresa", "email": "rh@empresa.com", "order": 2 }
],
"fieldValues": {
"nome_funcionario": "João Silva",
"cpf": "123.456.789-00",
"cargo": "Desenvolvedor Senior",
"salario": "R$ 15.000,00",
"data_inicio": "01/02/2024"
}
}
}
}'

Listar Requisições

GET /api/v1/esignature/requests

Lista as requisições de assinatura da organização com suporte a paginação e filtros.

Parâmetros de Query

ParâmetroTipoDescrição
page[number]numberNúmero da página (default: 1)
page[size]numberItens por página (default: 20, max: 100)
filter[status]enumFiltrar por status
filter[businessId]stringFiltrar por ID de negócio
# Listar todas
curl -X GET 'https://e-signature.stg.catalisa.app/api/v1/esignature/requests' \
-H 'Authorization: Bearer SEU_TOKEN'

# Com filtros
curl -X GET 'https://e-signature.stg.catalisa.app/api/v1/esignature/requests?filter[status]=SENT&page[size]=10' \
-H 'Authorization: Bearer SEU_TOKEN'

# Filtrar por businessId
curl -X GET 'https://e-signature.stg.catalisa.app/api/v1/esignature/requests?filter[businessId]=contract-2024-001' \
-H 'Authorization: Bearer SEU_TOKEN'

Resposta

{
"data": [
{
"type": "signature-request",
"id": "550e8400-e29b-41d4-a716-446655440000",
"links": {
"self": "/api/v1/esignature/requests/550e8400-e29b-41d4-a716-446655440000"
},
"attributes": {
"title": "Contrato de Prestação de Serviços",
"status": "SENT",
"businessId": "contract-2024-001",
"expiresAt": "2024-01-22T10:30:00Z",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}
}
],
"meta": {
"totalItems": 45,
"totalPages": 5,
"currentPage": 1,
"pageSize": 10
},
"links": {
"self": "/api/v1/esignature/requests?page[number]=1&page[size]=10",
"first": "/api/v1/esignature/requests?page[number]=1&page[size]=10",
"last": "/api/v1/esignature/requests?page[number]=5&page[size]=10",
"next": "/api/v1/esignature/requests?page[number]=2&page[size]=10"
}
}

Obter Requisição

GET /api/v1/esignature/requests/:id

Obtém uma requisição específica com seus signatários.

curl -X GET 'https://e-signature.stg.catalisa.app/api/v1/esignature/requests/550e8400-e29b-41d4-a716-446655440000' \
-H 'Authorization: Bearer SEU_TOKEN'

Cancelar Requisição

POST /api/v1/esignature/requests/:id/cancel

Cancela uma requisição de assinatura pendente.

Atenção

Apenas requisições com status DRAFT, SENT, VIEWED ou PARTIALLY_SIGNED podem ser canceladas.

curl -X POST 'https://e-signature.stg.catalisa.app/api/v1/esignature/requests/550e8400-e29b-41d4-a716-446655440000/cancel' \
-H 'Authorization: Bearer SEU_TOKEN'

Resposta

{
"data": {
"type": "signature-request",
"id": "550e8400-e29b-41d4-a716-446655440000",
"attributes": {
"title": "Contrato de Prestação de Serviços",
"status": "CANCELLED",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T14:00:00Z"
}
}
}

Reenviar Requisição

POST /api/v1/esignature/requests/:id/resend

Reenvia os e-mails de assinatura para signatários pendentes.

Atributos

CampoTipoObrigatórioDescrição
signerEmailstringNãoE-mail específico para reenvio (se omitido, reenvia para todos pendentes)
# Reenviar para todos os signatários pendentes
curl -X POST 'https://e-signature.stg.catalisa.app/api/v1/esignature/requests/550e8400-e29b-41d4-a716-446655440000/resend' \
-H 'Authorization: Bearer SEU_TOKEN' \
-H 'Content-Type: application/json' \
-d '{}'

# Reenviar para um signatário específico
curl -X POST 'https://e-signature.stg.catalisa.app/api/v1/esignature/requests/550e8400-e29b-41d4-a716-446655440000/resend' \
-H 'Authorization: Bearer SEU_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"data": {
"attributes": {
"signerEmail": "maria@cliente.com"
}
}
}'

Resposta

{
"message": "Signature request resent successfully"
}

Download Documento Assinado

GET /api/v1/esignature/requests/:id/download

Obtém a URL para download do documento assinado.

Requisito

O documento só está disponível para download quando a requisição tem status COMPLETED.

curl -X GET 'https://e-signature.stg.catalisa.app/api/v1/esignature/requests/550e8400-e29b-41d4-a716-446655440000/download' \
-H 'Authorization: Bearer SEU_TOKEN'

Resposta

{
"downloadUrl": "https://storage.example.com/signed/abc123.pdf?signature=xyz",
"expiresAt": "2024-01-15T11:30:00Z"
}
Expiração

A URL de download expira em 15 minutos. Solicite uma nova URL se necessário.


Excluir Requisição

DELETE /api/v1/esignature/requests/:id

Exclui uma requisição de assinatura.

Atenção

A exclusão é permanente. Requisições com status COMPLETED ou DECLINED são mantidas para auditoria por padrão.

curl -X DELETE 'https://e-signature.stg.catalisa.app/api/v1/esignature/requests/550e8400-e29b-41d4-a716-446655440000' \
-H 'Authorization: Bearer SEU_TOKEN'

Resposta

Status 204 No Content em caso de sucesso.


Fluxo Completo de Integração

Exemplo de integração completa monitorando status de assinatura:

async function sendContractForSignature(contractData) {
// 1. Criar requisição
const createResponse = await fetch('https://e-signature.stg.catalisa.app/api/v1/esignature/requests', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
data: {
type: 'signature-request',
attributes: {
title: `Contrato - ${contractData.clientName}`,
businessId: contractData.contractId,
expiresInDays: 7,
fileBase64: contractData.pdfBase64,
fileName: `contrato-${contractData.contractId}.pdf`,
signers: contractData.signers,
},
},
}),
});

const { data: request } = await createResponse.json();
console.log(`Requisição criada: ${request.id}`);

return request;
}

async function checkSignatureStatus(requestId) {
const response = await fetch(`https://e-signature.stg.catalisa.app/api/v1/esignature/requests/${requestId}`, {
headers: { 'Authorization': `Bearer ${token}` },
});

const { data } = await response.json();
return data.attributes.status;
}

async function downloadSignedContract(requestId) {
const response = await fetch(`https://e-signature.stg.catalisa.app/api/v1/esignature/requests/${requestId}/download`, {
headers: { 'Authorization': `Bearer ${token}` },
});

const { downloadUrl } = await response.json();

const fileResponse = await fetch(downloadUrl);
return await fileResponse.arrayBuffer();
}

// Uso
const request = await sendContractForSignature({
clientName: 'Empresa ABC',
contractId: 'CTR-2024-001',
pdfBase64: '...',
signers: [
{ name: 'João Silva', email: 'joao@empresa.com', order: 1 },
{ name: 'Cliente ABC', email: 'contato@abc.com', order: 2 },
],
});

// Aguardar conclusão (ou usar webhooks)
const status = await checkSignatureStatus(request.id);

if (status === 'COMPLETED') {
const signedPdf = await downloadSignedContract(request.id);
// Salvar documento assinado
}

Boas Práticas

  1. Use businessId - Vincule requisições a entidades do seu sistema
  2. Configure webhooks - Receba notificações em tempo real
  3. Defina prazos - Use expiresInDays para evitar requisições pendentes indefinidamente
  4. Posicione widgets - Melhora UX dos signatários
  5. Use templates - Para documentos recorrentes com campos fixos
  6. Armazene URLs - As URLs de assinatura podem ser compartilhadas diretamente