Assin — API Reference

Retorna todos os envelopes da empresa autenticada com suporte a paginação, filtros por status e busca textual.

Query params

{
  "totalElements": 42,
  "data": [
    {
      "id": "uuid",
      "name": "Contrato de Prestação de Serviços",
      "status": "WAITING_SIGNATURE",
      "createdAt": "2026-05-02T00:00:00Z",
      "signers": [...]
    }
  ]
}

Cria um novo envelope em status DRAFT. Após criar, adicione documentos e signatários antes de lacrar.

Body

{
  "name": "Contrato Q2-2026",
  "description": "Contrato anual de parceria",
  "deadline": "2026-06-30T23:59:59Z",
  "folderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Lacra o envelope, verifica e debita créditos, e dispara notificações para o primeiro signatário (ou todos, se a ordem for paralela). O envelope muda para WAITING_SIGNATURE.

Body

{
  "envelopeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Cancela um envelope em status WAITING_SIGNATURE. Notificações de cancelamento são disparadas para os signatários pendentes.

Body

{
  "envelopeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "reason": "Contrato renegociado — nova versão será enviada em breve"
}

Atualiza nome, descrição, prazo ou pasta de um envelope em status DRAFT.

Body

{
  "envelopeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Contrato Q2-2026 — Revisado",
  "deadline": "2026-07-31T23:59:59Z"
}

Gerencia os documentos associados a um envelope em DRAFT. Use :method = set para adicionar e :method = remove para desvincular.

Path params

Body

{
  "envelopeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "documentId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
}

Retorna URLs presigned para leitura/download dos documentos de um envelope. As URLs expiram em 1 hora.

Body

{
  "envelopeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

{
  "data": [
    {
      "documentId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "name": "Contrato Q2-2026.pdf",
      "url": "https://s3.amazonaws.com/bucket/key?X-Amz-Expires=3600&...",
      "expiresAt": "2026-05-02T16:00:00Z"
    }
  ]
}

Bloqueia temporariamente a assinatura de um envelope sem cancelá-lo. Útil para pausar o fluxo enquanto há disputas ou revisões.

Body

{
  "envelopeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "blocked": true
}

Retorna contadores de envelopes por status para o dashboard da empresa.

{
  "total": 150,
  "draft": 12,
  "waitingSignature": 38,
  "completed": 95,
  "cancelled": 5
}

Remove permanentemente um envelope em status DRAFT. Não é possível excluir envelopes lacrados — use PUT /cancel nesses casos.

Path params

Lista todos os documentos da empresa com paginação.

Query params

{
  "totalElements": 5,
  "data": [
    {
      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "name": "Contrato de Prestacao de Servicos.pdf",
      "size": 245760,
      "s3Key": "documents/tenant-uuid/2026/05/contrato.pdf",
      "createdAt": "2026-05-02T12:00:00Z"
    }
  ]
}

Registra um documento via URL presigned gerada previamente. O arquivo deve ser um PDF e já estar armazenado no S3.

Body

{
  "name": "Contrato de Prestacao de Servicos.pdf",
  "s3Key": "documents/tenant-uuid/2026/05/contrato.pdf"
}

{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "name": "Contrato de Prestacao de Servicos.pdf",
  "s3Key": "documents/tenant-uuid/2026/05/contrato.pdf",
  "createdAt": "2026-05-02T12:00:00Z"
}

Gera uma URL presigned temporária para download ou visualização de um documento. Requer header x-dynamic-authorization com o token do signatário ou da sessão.

{
  "url": "https://s3.amazonaws.com/bucket/key?X-Amz-Expires=3600&...",
  "expiresAt": "2026-05-02T16:00:00Z"
}

Verifica se um documento é autêntico a partir de seu fingerprint blockchain ou ID. Use para o portal público de validação.

Query params (pelo menos um obrigatório)

{
  "valid": true,
  "documentId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "envelopeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "envelopeName": "Contrato Q2-2026",
  "finishedAt": "2026-05-02T18:45:00Z",
  "blockchainTx": "0xabc123...def456",
  "signers": [
    { "name": "Maria Souza", "signedAt": "2026-05-02T17:30:00Z" }
  ]
}

Remove um documento da empresa. Documentos vinculados a envelopes lacrados não podem ser excluídos.

Lista todos os templates da empresa. Suporta filtros e paginação.

{
  "totalElements": 3,
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Contrato Padrao CLT",
      "isActive": true,
      "documentId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "fields": [
        { "key": "nomeColaborador", "label": "Nome do Colaborador" },
        { "key": "cpf",             "label": "CPF" },
        { "key": "salario",        "label": "Salario Bruto" },
        { "key": "dataAdmissao",   "label": "Data de Admissao" }
      ],
      "createdAt": "2026-03-10T09:00:00Z"
    }
  ]
}

Cadastra um novo template associado ao documento S3 com seus campos variáveis mapeados.

Body

{
  "name": "Contrato Padrao CLT",
  "documentId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "fields": [
    { "key": "nomeColaborador", "label": "Nome do Colaborador" },
    { "key": "cpf",             "label": "CPF" },
    { "key": "salario",        "label": "Salario Bruto" },
    { "key": "dataAdmissao",   "label": "Data de Admissao" }
  ]
}

Alterna o estado ativo do template. Templates inativos não podem ser usados para gerar documentos.

Path params

Substitui os campos variáveis do template pelos valores fornecidos e gera um PDF pronto para ser adicionado a um envelope.

Body

{
  "templateId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "documentName": "Contrato João Silva 2026",
  "variables": {
    "nomeCliente": "João Silva",
    "cpf": "000.000.000-00",
    "valorContrato": "R$ 5.000,00"
  }
}

Remove um template da empresa. Templates usados em envelopes existentes não são afetados.

Body

{
  "templateId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Lista os signatários de um envelope específico.

Query params

[
  {
    "id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "name": "Maria Souza",
    "email": "maria@empresa.com.br",
    "phone": "+5511999887766",
    "signatureType": "SIGN",
    "order": 1,
    "status": "PENDING",
    "notificationChannel": "EMAIL",
    "signedAt": null
  },
  {
    "id": "2c8e7fce-ccge-5c3e-0c6e-bc9egcce5cfe",
    "name": "João Diretor",
    "email": "joao.diretor@empresa.com.br",
    "phone": null,
    "signatureType": "APPROVE",
    "order": 2,
    "status": "WAITING",
    "notificationChannel": "EMAIL",
    "signedAt": null
  }
]

Adiciona um signatário a um envelope em DRAFT. O campo order define a sequência de assinatura — use 0 para assinatura paralela.

Body

{
  "envelopeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Maria Souza",
  "email": "maria@empresa.com.br",
  "signatureType": "SIGN",
  "order": 1,
  "notificationChannel": "EMAIL"
}

Remove um signatário de um envelope em DRAFT.

Body

{
  "envelopeSignerId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"
}

Reenvia o link de assinatura para um signatário via o canal especificado.

Path params

Body

{
  "envelopeSignerId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"
}

Retorna contadores de signatários por status para a empresa autenticada.

{
  "total": 320,
  "pending": 42,
  "signed": 268,
  "rejected": 10
}

Retorna as tags de um documento dentro de um envelope. Ambos os filtros são obrigatórios.

Query params

[
  {
    "id": "c8e8d2a0-1234-4abc-8def-000000000001",
    "type": "SIGNATURE",
    "page": 3,
    "x": 15.5,
    "y": 82.0,
    "envelopeSignerId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"
  },
  {
    "id": "c8e8d2a0-1234-4abc-8def-000000000002",
    "type": "DATE",
    "page": 3,
    "x": 60.0,
    "y": 82.0,
    "envelopeSignerId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"
  }
]

Adiciona uma tag posicionada no documento. Use para marcar onde cada signatário deve assinar ou preencher.

Body (campos principais)

{
  "envelopeId":         "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "envelopeDocumentId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "envelopeSignerId":   "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
  "type": "SIGNATURE",
  "page": 3,
  "x": 15.5,
  "y": 82.0
}

Atualiza posição, tipo ou signatário de uma tag existente.

Body

{
  "tagId": "c8e8d2a0-1234-4abc-8def-000000000001",
  "x": 20.0,
  "y": 85.5
}

Remove uma tag do documento.

Body

{
  "tagId": "c8e8d2a0-1234-4abc-8def-000000000001"
}

Retorna todos os grupos de signatários da empresa com paginação.

Query params

{
  "totalElements": 2,
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Diretoria Financeira",
      "description": "CFO + CEO para contratos acima de R$ 50k",
      "members": [
        { "name": "Carlos CEO", "email": "ceo@empresa.com.br", "signatureType": "SIGN", "order": 1 },
        { "name": "Ana CFO", "email": "cfo@empresa.com.br", "signatureType": "SIGN", "order": 2 }
      ],
      "createdAt": "2026-04-10T09:00:00Z"
    }
  ]
}

Cria um grupo reutilizável com membros e configurações de assinatura já pré-definidas.

Body

Estrutura de cada membro

{
  "name": "Diretoria Financeira",
  "description": "CFO + CEO para contratos acima de R$ 50k",
  "members": [
    {
      "name": "Carlos CEO",
      "email": "ceo@empresa.com.br",
      "signatureType": "SIGN",
      "order": 1
    },
    {
      "name": "Ana CFO",
      "email": "cfo@empresa.com.br",
      "signatureType": "SIGN",
      "order": 2
    }
  ]
}

Atualiza nome, descrição ou membros de um grupo. Envelopes que já importaram o grupo não são afetados.

Body

{
  "name": "Diretoria Financeira e Jurídica",
  "members": [
    { "name": "Carlos CEO", "email": "ceo@empresa.com.br", "signatureType": "SIGN", "order": 1 },
    { "name": "Ana CFO", "email": "cfo@empresa.com.br", "signatureType": "SIGN", "order": 2 },
    { "name": "Luiza Jurídico", "email": "juridico@empresa.com.br", "signatureType": "WITNESS", "order": 3 }
  ]
}

Remove permanentemente o grupo. Envelopes que já importaram o grupo permanecem inalterados.

Cria automaticamente um EnvelopeSigner para cada membro do grupo no envelope indicado. O envelope deve estar em status DRAFT.

Body

{
  "groupId":    "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "envelopeId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
}

Retorna pastas da empresa. Use parentId para listar subpastas de uma pasta específica.

Query params

{
  "totalElements": 3,
  "data": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "name": "Contratos 2026",
      "parentId": null,
      "envelopeCount": 14,
      "createdAt": "2026-01-05T08:00:00Z"
    }
  ]
}

Cria uma pasta para organizar envelopes. Informe parentId para criar uma subpasta.

Body

{
  "name": "Contratos 2026",
  "parentId": null
}

Renomeia ou move uma pasta para outro nível da hierarquia alterando o parentId.

Body

{
  "name": "Contratos 2026 — Encerrados",
  "parentId": null
}

Remove a pasta. Envelopes dentro da pasta não são excluídos — apenas a associação é removida.

Retorna contatos do livro de endereços. Use isCompanyContact=true para listar os compartilhados com toda a empresa.

Query params

{
  "totalElements": 12,
  "data": [
    {
      "id": "f1a2b3c4-0000-0000-0000-000000000001",
      "fullName": "Pedro Alves",
      "email": "pedro.alves@empresa.com.br",
      "phone": "+5511999887766",
      "isCompanyContact": true,
      "createdAt": "2026-03-15T10:00:00Z"
    }
  ]
}

Adiciona um contato ao livro de endereços.

Body

{
  "fullName": "Pedro Alves",
  "email": "pedro.alves@empresa.com.br",
  "phone": "+5511999887766",
  "isCompanyContact": true
}

Atualiza nome, e-mail ou telefone de um contato existente.

Body

{
  "phone": "+5511988776655",
  "isCompanyContact": false
}

Remove um contato do livro de endereços. Signatários de envelopes existentes não são afetados.

Retorna todos os endpoints registrados com seus eventos subscritos e status ativo/inativo.

{
  "totalElements": 1,
  "data": [
    {
      "id": "uuid",
      "domain": "https://meuapp.com.br/webhooks/assin",
      "description": "Endpoint principal de produção",
      "isActive": true,
      "createdAt": "2026-05-02T00:00:00Z",
      "eventSubscriptions": [
        { "eventType": "ENVELOPE_FINISHED" },
        { "eventType": "SIGNER_COMPLETED" }
      ]
    }
  ]
}

Registra um endpoint para receber eventos. Você pode subscrever a um ou mais eventos por endpoint.

Body

{
  "data": {
    "domain": "https://meuapp.com.br/webhooks/assin",
    "description": "Endpoint de produção",
    "events": [
      "ENVELOPE_FINISHED",
      "SIGNER_COMPLETED"
    ]
  }
}

Payload enviado ao seu endpoint

// POST https://meuapp.com.br/webhooks/assin
{
  "event": "ENVELOPE_FINISHED",
  "envelopeId": "uuid",
  "companyId": "uuid",
  "occurredAt": "2026-05-02T15:30:00Z",
  "data": { /* detalhes do evento */ }
}

Atualiza descrição, status ou lista de eventos. Enviar events substitui completamente a lista anterior.

Body

{
  "data": {
    "isActive": false,
    "events": ["ENVELOPE_FINISHED", "ENVELOPE_CANCELLED", "SIGNER_COMPLETED"]
  }
}

Remove o webhook e cancela todas as subscrições de eventos associadas. Retorna 204 No Content.

Cria um novo lote. Após criar, vincule documentos, signatários e templates antes de processar.

Body

{
  "data": {
    "name": "Folha de Pagamento Maio 2026",
    "description": "Contracheques de todos os colaboradores",
    "companyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

Retorna todos os lotes da empresa.

Path params

{
  "totalElements": 3,
  "data": [{ "id": "uuid", "name": "Folha Maio 2026", "status": "DRAFT" }]
}

Remove um lote em status DRAFT. Lotes já processados não podem ser excluídos.

Associa um documento ao lote pelo alias — nome de referência usado para mapear o documento às variáveis do template.

Body

{
  "data": {
    "batchId":   "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "companyId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "alias":     "contracheque"
  }
}

Lista os documentos vinculados a um lote.

Query params

{
  "totalElements": 1,
  "data": [
    {
      "id": "d1e2f3a4-0000-0000-0000-000000000001",
      "batchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "alias": "contracheque",
      "documentId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "createdAt": "2026-05-01T09:00:00Z"
    }
  ]
}

Atualiza o alias ou documento associado ao lote.

Body

{
  "data": {
    "id":    "d1e2f3a4-0000-0000-0000-000000000001",
    "alias": "holerite"
  }
}

Remove a associação entre um documento e o lote.

Body

{
  "data": { "id": "d1e2f3a4-0000-0000-0000-000000000001" }
}

Adiciona um signatário ao lote. Use fixed=true para signatários fixos (aparecem em todos os envelopes) e fixed=false para variáveis (definidos linha a linha no Excel).

Body

{
  "data": {
    "batchId":       "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "fixed":        true,
    "signatureType": "SIGN",
    "order":        2,
    "email":        "gerente@empresa.com.br",
    "fullName":     "Carlos Gerente"
  }
}

{
  "data": {
    "batchId":       "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "fixed":        false,
    "signatureType": "SIGN",
    "order":        1
  }
}

Retorna todos os signatários (fixos e variáveis) configurados para o lote.

{
  "totalElements": 2,
  "data": [
    {
      "id": "s1a2b3c4-0000-0000-0000-000000000001",
      "fixed": true,
      "signatureType": "SIGN",
      "order": 2,
      "fullName": "Carlos Gerente",
      "email": "gerente@empresa.com.br"
    },
    {
      "id": "s1a2b3c4-0000-0000-0000-000000000002",
      "fixed": false,
      "signatureType": "SIGN",
      "order": 1,
      "fullName": null,
      "email": null
    }
  ]
}

Remove um signatário do lote.

Associa um template ao lote. O template define os campos variáveis que serão preenchidos pelo Excel.

Body

{
  "data": { "templateId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }
}

Faz upload da planilha .xlsx com os dados de cada envelope. Cada linha gera um envelope. Os headers das colunas devem corresponder às chaves do template.

Path params

curl -X POST "{BASE_URL}/v1/batches-template/upload-excel/:batchId/:companyId/:templateId" \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Origin: https://seuapp.com.br" \
  -H "x-origin-with-label: web-app" \
  -F "file=@colaboradores.xlsx"

Define qual coluna do Excel alimenta cada campo dos signatários variáveis. Por exemplo, a coluna "E-mail Corporativo" alimenta o campo email do signatário.

Body

{
  "data": {
    "nomeColaborador": "Nome Completo",
    "cpf":             "CPF",
    "salario":        "Salario Bruto",
    "email":          "E-mail Corporativo"
  }
}

Retorna os templates vinculados ao lote com seus campos mapeados.

{
  "totalElements": 1,
  "data": [
    {
      "id": "t1a2b3c4-0000-0000-0000-000000000001",
      "templateId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "templateName": "Contrato Padrao CLT",
      "batchId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
    }
  ]
}

Retorna o mapeamento de colunas Excel para signatários variáveis de cada template do lote.

[
  {
    "templateId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "signerId": "s1a2b3c4-0000-0000-0000-000000000002",
    "mapping": {
      "nomeColaborador": "Nome Completo",
      "cpf":             "CPF",
      "email":          "E-mail Corporativo"
    }
  }
]

Remove a associação entre um template e o lote.

Dispara o processamento completo. Para cada linha do Excel: gera o documento pelo template, cria o envelope, adiciona documentos e signatários, lacra. Créditos são debitados aqui.

Path params

{
  "batchId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "status": "PROCESSING",
  "totalEnvelopes": 250,
  "creditsDebited": 250,
  "startedAt": "2026-05-02T13:00:00Z"
}

Reenvia a notificação de validação para um signatário específico dentro do lote.

Reenvia o link de assinatura para um signatário que ainda não assinou dentro do lote.