API de documentos

Documentos e modelos estão sendo descontinuados e substituídos por envelopes. Leia o guia de migração.

Este guia pode não refletir os endpoints ou parâmetros mais recentes. Para uma referência sempre atualizada, consulte a especificação OpenAPI.

Visão geral

Documentos (chamados de "envelopes" na API) são o recurso central da KivoSign. Você pode:

criar documentos com destinatários e campos
enviá-los para assinatura
acompanhar o status
baixar os PDFs concluídos

Cada documento tem um ou mais arquivos PDF, uma lista de destinatários e os campos que eles precisam preencher.

Objeto documento

O objeto documento tem as seguintes propriedades:

Propriedade	Tipo	Descrição
`id`	string	Identificador único (ex.: `envelope_abc123`)
`secondaryId`	string	Identificador legado com prefixo (`document_123` para documentos, `template_123` para modelos)
`internalVersion`	number	Versão interna do schema do envelope
`type`	string	`DOCUMENT` ou `TEMPLATE`
`status`	string	Status atual: `DRAFT`, `PENDING`, `COMPLETED`, `REJECTED` ou `CANCELLED`
`title`	string	Título do documento
`source`	string	Como o documento foi criado: `DOCUMENT`, `TEMPLATE`, `TEMPLATE_DIRECT_LINK`
`visibility`	string	Quem pode ver: `EVERYONE`, `ADMIN`, `MANAGER_AND_ABOVE`
`templateType`	string	Visibilidade do modelo: `PUBLIC`, `PRIVATE` ou `ORGANISATION` (só faz sentido em modelos)
`externalId`	string \| null	Seu identificador próprio para o documento
`userId`	number	ID do usuário dono do documento
`teamId`	number	ID da equipe a que o documento pertence
`folderId`	string \| null	ID da pasta que contém o documento
`templateId`	number \| null	ID legado do modelo que originou o documento
`authOptions`	object \| null	Exigências de autenticação de acesso e de ação
`formValues`	object \| null	Valores de formulário pré-preenchidos
`publicTitle`	string	Título público exibido no perfil e nas páginas de link direto
`publicDescription`	string	Descrição pública exibida no perfil e nas páginas de link direto
`createdAt`	string	Data/hora ISO 8601
`updatedAt`	string	Data/hora ISO 8601
`completedAt`	string \| null	Data/hora em que todos os destinatários concluíram
`deletedAt`	string \| null	Data/hora da exclusão lógica, se houver
`recipients`	array	Lista de destinatários e seus status de assinatura
`fields`	array	Campos de assinatura e de formulário do documento
`envelopeItems`	array	Arquivos PDF do documento
`directLink`	object \| null	Configuração de assinatura por link direto (`id`, `token`, `enabled`, `directTemplateRecipientId`)
`team`	object	Equipe dona (`id`, `url`)
`user`	object	Dono do documento (`id`, `name`, `email`)
`documentMeta`	object	Configurações de e-mail, URL de redirecionamento e opções de assinatura

Documentos criados pela API têm source: "DOCUMENT"; não existe um valor API separado. Para marcar os documentos criados pela sua integração, informe externalId na criação.

Exemplo de objeto documento

{
  "id": "envelope_abc123xyz",
  "secondaryId": "document_123",
  "internalVersion": 2,
  "type": "DOCUMENT",
  "status": "PENDING",
  "source": "DOCUMENT",
  "visibility": "EVERYONE",
  "templateType": "PRIVATE",
  "title": "Contrato de prestação de serviços",
  "externalId": "contrato-2025-001",
  "userId": 1,
  "teamId": 1,
  "folderId": null,
  "templateId": null,
  "authOptions": null,
  "formValues": null,
  "publicTitle": "",
  "publicDescription": "",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:35:00.000Z",
  "completedAt": null,
  "deletedAt": null,
  "recipients": [
    {
      "id": 1,
      "email": "signatario@exemplo.com",
      "name": "João Silva",
      "role": "SIGNER",
      "signingStatus": "NOT_SIGNED",
      "signingOrder": 1
    }
  ],
  "fields": [
    {
      "id": 123,
      "secondaryId": "field_abc123",
      "type": "SIGNATURE",
      "recipientId": 1,
      "envelopeId": "envelope_abc123xyz",
      "envelopeItemId": "envelope_item_xyz",
      "page": 1,
      "positionX": "10",
      "positionY": "80",
      "width": "30",
      "height": "5",
      "customText": "",
      "inserted": false,
      "fieldMeta": null
    }
  ],
  "envelopeItems": [
    {
      "id": "envelope_item_xyz",
      "envelopeId": "envelope_abc123xyz",
      "documentDataId": "doc_data_abc123",
      "title": "contrato.pdf",
      "order": 1
    }
  ],
  "directLink": null,
  "team": {
    "id": 1,
    "url": "sua-equipe"
  },
  "user": {
    "id": 1,
    "name": "Maria Souza",
    "email": "maria@exemplo.com"
  },
  "documentMeta": {
    "subject": "Por favor, assine este documento",
    "message": "Olá, revise e assine este contrato, por favor.",
    "timezone": "America/Sao_Paulo",
    "redirectUrl": "https://exemplo.com/obrigado"
  }
}

Posição e tamanho dos campos são guardados como decimais e serializados como string nas respostas da API.

Listar documentos

Consulta uma lista paginada de documentos.

GET /envelope

Parâmetros de consulta

Parâmetro	Tipo	Descrição
`page`	integer	Número da página (padrão: 1)
`perPage`	integer	Resultados por página (padrão: 10, máx.: 100)
`type`	string	Filtra por `DOCUMENT` ou `TEMPLATE`
`status`	string	Filtra por status: `DRAFT`, `PENDING`, `COMPLETED`, `REJECTED`, `CANCELLED`
`source`	string	Filtra pela origem da criação
`folderId`	string	Filtra pelo ID da pasta
`orderByColumn`	string	Campo de ordenação (só `createdAt`)
`orderByDirection`	string	Direção: `asc` ou `desc` (padrão: `desc`)

Exemplos

# Listar todos os documentos
curl -X GET "https://app.kivosign.com.br/api/v2/envelope" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx"

# Filtrar por status e paginar
curl -X GET "https://app.kivosign.com.br/api/v2/envelope?status=PENDING&page=1&perPage=20" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx"

# Listar apenas documentos (sem modelos)
curl -X GET "https://app.kivosign.com.br/api/v2/envelope?type=DOCUMENT" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx"

Resposta

{
  "data": [
    {
      "id": "envelope_abc123",
      "type": "DOCUMENT",
      "status": "PENDING",
      "title": "Contrato de prestação de serviços",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:35:00.000Z",
      "recipients": [
        {
          "id": 1,
          "email": "signatario@exemplo.com",
          "name": "João Silva",
          "role": "SIGNER",
          "signingStatus": "NOT_SIGNED"
        }
      ]
    }
  ],
  "count": 42,
  "currentPage": 1,
  "perPage": 10,
  "totalPages": 5
}

Consultar documento

Consulta um documento pelo ID.

GET /envelope/{envelopeId}

Parâmetros de caminho

Parâmetro	Tipo	Descrição
`envelopeId`	string	O ID do documento (ex.: `envelope_abc123`)

Exemplos

curl -X GET "https://app.kivosign.com.br/api/v2/envelope/envelope_abc123" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx"

Resposta

Retorna o objeto documento completo, com destinatários, campos e itens do envelope.

{
  "id": "envelope_abc123",
  "type": "DOCUMENT",
  "status": "PENDING",
  "title": "Contrato de prestação de serviços",
  "recipients": [...],
  "fields": [...],
  "envelopeItems": [...],
  "documentMeta": {...}
}

Criar documento

Cria um documento, com destinatários e campos opcionais, em uma única requisição.

Este endpoint procura automaticamente nos PDFs enviados marcadores como {"{{signature, r1}}"} e cria campos nesses locais.

POST /envelope/create
Content-Type: multipart/form-data

Corpo da requisição

A requisição usa multipart/form-data com duas partes:

Parte	Tipo	Descrição
`payload`	JSON	Configuração do documento
`files`	Arquivo(s)	Um ou mais arquivos PDF

Schema do payload

Campo	Tipo	Obrigatório	Descrição
`type`	string	Sim	Deve ser `DOCUMENT`
`title`	string	Sim	Título do documento
`externalId`	string	Não	Seu identificador próprio
`visibility`	string	Não	`EVERYONE`, `ADMIN` ou `MANAGER_AND_ABOVE`
`folderId`	string	Não	ID da pasta onde criar o documento
`recipients`	array	Não	Destinatários, com campos opcionais
`meta`	object	Não	Assunto e mensagem do e-mail, URL de redirecionamento etc.

Exemplos

curl -X POST "https://app.kivosign.com.br/api/v2/envelope/create" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: multipart/form-data" \
  -F 'payload={
    "type": "DOCUMENT",
    "title": "Contrato de prestação de serviços",
    "externalId": "contrato-2025-001",
    "recipients": [
      {
        "email": "signatario@exemplo.com",
        "name": "João Silva",
        "role": "SIGNER",
        "fields": [
          {
            "identifier": 0,
            "type": "SIGNATURE",
            "page": 1,
            "positionX": 10,
            "positionY": 80,
            "width": 30,
            "height": 5
          },
          {
            "identifier": 0,
            "type": "DATE",
            "page": 1,
            "positionX": 50,
            "positionY": 80,
            "width": 20,
            "height": 3
          }
        ]
      }
    ],
    "meta": {
      "subject": "Por favor, assine este contrato",
      "message": "Olá João, revise e assine o contrato em anexo, por favor.",
      "redirectUrl": "https://exemplo.com/obrigado"
    }
  }' \
  -F "files=@./contrato.pdf;type=application/pdf"

Resposta

{
  "id": "envelope_abc123xyz"
}

Posicionamento dos campos

As posições usam percentuais (0 a 100) relativos à página do PDF:

Parâmetro	Descrição
`positionX`	Posição horizontal a partir da borda esquerda (0 = esquerda, 100 = direita)
`positionY`	Posição vertical a partir do topo (0 = topo, 100 = rodapé)
`width`	Largura do campo em percentual da largura da página
`height`	Altura do campo em percentual da altura da página
`page`	Número da página (começa em 1)
`identifier`	Índice do arquivo (0 para o primeiro) ou nome do arquivo

Tipos de campo

Tipo	Descrição
`SIGNATURE`	Campo de assinatura
`INITIALS`	Campo de iniciais
`NAME`	Nome do destinatário, preenchido automaticamente
`EMAIL`	E-mail do destinatário, preenchido automaticamente
`DATE`	Data da assinatura
`TEXT`	Texto livre
`NUMBER`	Número
`CHECKBOX`	Caixa de seleção
`RADIO`	Grupo de opção única
`DROPDOWN`	Lista suspensa

Papéis dos destinatários

Papel	Descrição
`SIGNER`	Precisa assinar o documento
`APPROVER`	Precisa aprovar antes que os signatários assinem
`CC`	Recebe uma cópia, mas não assina
`VIEWER`	Pode ver o documento, mas não realiza ação

Atualizar documento

Atualiza as propriedades de um documento. Só funciona em documentos com status DRAFT.

POST /envelope/update

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`envelopeId`	string	Sim	ID do documento
`data`	object	Não	Propriedades do documento a atualizar
`meta`	object	Não	Configurações de e-mail e assinatura a atualizar

Exemplos

curl -X POST "https://app.kivosign.com.br/api/v2/envelope/update" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "envelopeId": "envelope_abc123",
    "data": {
      "title": "Contrato de prestação de serviços (revisado)",
      "externalId": "contrato-2025-001-v2"
    },
    "meta": {
      "subject": "Atualizado: por favor, assine este contrato",
      "redirectUrl": "https://exemplo.com/assinado"
    }
  }'

Enviar documento

Envia o documento aos destinatários para assinatura. O status muda de DRAFT para PENDING.

POST /envelope/distribute

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`envelopeId`	string	Sim	ID do documento
`meta`	object	Não	Sobrescreve as configurações de e-mail neste envio

Exemplos

# Envio simples
curl -X POST "https://app.kivosign.com.br/api/v2/envelope/distribute" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "envelopeId": "envelope_abc123"
  }'

# Envio com e-mail personalizado
curl -X POST "https://app.kivosign.com.br/api/v2/envelope/distribute" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "envelopeId": "envelope_abc123",
    "meta": {
      "subject": "Ação necessária: assinar contrato",
      "message": "Por favor, assine este documento até o fim do dia.",
      "timezone": "America/Sao_Paulo"
    }
  }'

Resposta

A resposta traz a URL de assinatura de cada destinatário:

{
  "success": true,
  "id": "envelope_abc123",
  "recipients": [
    {
      "id": 1,
      "name": "João Silva",
      "email": "signatario@exemplo.com",
      "token": "abc123xyz",
      "role": "SIGNER",
      "signingOrder": 1,
      "signingUrl": "https://app.kivosign.com.br/sign/abc123xyz"
    }
  ]
}

Use o signingUrl para levar o destinatário direto à página de assinatura, ou deixe que ele use o link do e-mail.

Cancelar documento

Cancela um documento pendente. O status muda de PENDING para CANCELLED.

POST /envelope/cancel

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`envelopeId`	string	Sim	ID do documento
`reason`	string	Não	Motivo do cancelamento

Exemplos

curl -X POST "https://app.kivosign.com.br/api/v2/envelope/cancel" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "envelopeId": "envelope_abc123",
    "reason": "O contrato não é mais necessário."
  }'

Resposta

{
  "success": true
}

Comportamento

Só documentos com status PENDING podem ser cancelados. Outros status retornam 400.
O cancelamento não é idempotente. Cancelar o mesmo documento de novo retorna 400.
Podem cancelar o dono do documento e membros da equipe com permissão MANAGER ou superior. Requisições para documentos que você não pode ver retornam 404; para documentos visíveis sem permissão suficiente, retornam 401.
Um cancelamento bem-sucedido dispara o webhook DOCUMENT_CANCELLED.
O e-mail de cancelamento só vai para destinatários elegíveis (não CC e que não recusaram) que receberam ou abriram o documento.

Excluir documento

Exclui um documento. Documentos concluídos não podem ser excluídos.

POST /envelope/delete

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`envelopeId`	string	Sim	ID do documento

Exemplos

curl -X POST "https://app.kivosign.com.br/api/v2/envelope/delete" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "envelopeId": "envelope_abc123"
  }'

Resposta

{
  "success": true
}

Consultar vários documentos

Consulta vários documentos pelos IDs em uma única requisição.

POST /envelope/get-many

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`ids`	object	Sim	Seletor de IDs com `type` e `ids`
`ids.type`	string	Sim	`envelopeId`, `documentId` ou `templateId`
`ids.ids`	array	Sim	De 1 a 20 IDs: strings para `envelopeId`; números para `documentId` ou `templateId`

Exemplos

curl -X POST "https://app.kivosign.com.br/api/v2/envelope/get-many" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": {
      "type": "envelopeId",
      "ids": ["envelope_abc123", "envelope_def456", "envelope_ghi789"]
    }
  }'

Resposta

{
  "data": [
    {
      "id": "envelope_abc123",
      "type": "DOCUMENT",
      "status": "PENDING",
      "title": "Contrato de prestação de serviços"
    }
  ]
}

O endpoint omite sem aviso os envelopes que você não pode acessar, em vez de retornar 404. Compare data.length com requestedIds.length para detectar omissões.

Status do documento

Status	Descrição
`DRAFT`	Rascunho em preparação. Os destinatários ainda não foram notificados.
`PENDING`	Documento enviado. Aguardando as assinaturas.
`COMPLETED`	Todos os destinatários assinaram. O documento está selado.
`REJECTED`	Um destinatário recusou o documento.
`CANCELLED`	O documento foi cancelado pelo dono ou por um membro da equipe com permissão `MANAGER` ou superior.

Transições de status

DRAFT para PENDING: chame o endpoint de distribuição
PENDING para COMPLETED: todos os destinatários concluem a assinatura
PENDING para REJECTED: um destinatário recusa o documento
PENDING para CANCELLED: o dono ou um membro da equipe com permissão MANAGER ou superior cancela o documento

Não é possível alterar destinatários ou campos depois que o documento passa para PENDING.

Filtros e paginação

Parâmetros de paginação

Parâmetro	Tipo	Padrão	Descrição
`page`	integer	1	Número da página
`perPage`	integer	10	Resultados por página (máx.: 100)

Parâmetros de filtro

Parâmetro	Valores	Descrição
`type`	`DOCUMENT`, `TEMPLATE`	Filtra pelo tipo de envelope
`status`	`DRAFT`, `PENDING`, `COMPLETED`, `REJECTED`, `CANCELLED`	Filtra pelo status
`source`	`DOCUMENT`, `TEMPLATE`, `TEMPLATE_DIRECT_LINK`	Filtra pela origem da criação
`folderId`	string	Filtra pela pasta

Ordenação

Parâmetro	Valores	Descrição
`orderByColumn`	`createdAt`	Campo de ordenação
`orderByDirection`	`asc`, `desc`	Direção (padrão: `desc`)

Exemplo: buscar todos os documentos pendentes

async function getAllPendingDocuments() {
  const documents = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `https://app.kivosign.com.br/api/v2/envelope?status=PENDING&page=${page}&perPage=100`,
      {
        headers: { Authorization: 'api_xxxxxxxxxxxxxxxx' },
      },
    );

    const { data, currentPage, totalPages } = await response.json();
    documents.push(...data);

    hasMore = currentPage < totalPages;
    page++;
  }

  return documents;
}

Veja também

API de destinatários - Adicione e gerencie destinatários
API de campos - Adicione campos de assinatura e de formulário
API de modelos - Crie modelos de documento reutilizáveis
Webhooks - Seja notificado quando documentos forem assinados

Nesta página