API de campos

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.

Objeto campo

Propriedade	Tipo	Descrição
`id`	number	Identificador único do campo
`secondaryId`	string	Identificador secundário para logs de auditoria
`type`	string	Tipo do campo (veja Tipos de campo)
`recipientId`	number	ID do destinatário associado ao campo
`envelopeId`	string	ID do envelope
`envelopeItemId`	string	ID do item (PDF) em que o campo está
`page`	number	Número da página (começa em 1)
`positionX`	string	Coordenada X em percentual (0-100), decimal serializado como string
`positionY`	string	Coordenada Y em percentual (0-100), decimal serializado como string
`width`	string	Largura em percentual da página (0-100), decimal serializado como string
`height`	string	Altura em percentual da página (0-100), decimal serializado como string
`customText`	string	Valor preenchido pelo destinatário
`inserted`	boolean	Se o campo já foi preenchido
`fieldMeta`	object \| null	Opções de configuração específicas do tipo

Exemplo de objeto campo

{
  "id": 456,
  "secondaryId": "field_abc123",
  "type": "SIGNATURE",
  "recipientId": 123,
  "envelopeId": "envelope_abcdefhiklmnorst",
  "envelopeItemId": "envelope_item_abcdefhiklmnorst",
  "page": 1,
  "positionX": "10",
  "positionY": "80",
  "width": "30",
  "height": "5",
  "customText": "",
  "inserted": false,
  "fieldMeta": {
    "type": "signature",
    "required": true,
    "overflow": "auto"
  }
}

Tipos de campo

Tipo	Descrição	Preenchimento automático
`SIGNATURE`	Assinatura desenhada, digitada ou enviada como imagem	Não
`FREE_SIGNATURE`	Assinatura livre antiga. Aceita pelo schema de criação da v2, mas rejeitada pela API v1 e sem suporte na tela de assinatura. Evite em novas integrações	Não
`INITIALS`	Iniciais do destinatário	Não
`NAME`	Nome completo do destinatário	Sim
`EMAIL`	E-mail do destinatário	Sim
`DATE`	Data em que o campo foi preenchido	Sim
`TEXT`	Texto livre	Não
`NUMBER`	Número, com validação opcional	Não
`RADIO`	Escolha única entre opções	Não
`CHECKBOX`	Múltipla escolha entre opções	Não
`DROPDOWN`	Escolha única em uma lista suspensa	Não

Parâmetro	Tipo	Descrição
`fieldId`	number	O ID do campo

Criar campos

Adiciona um ou mais campos a um documento.

POST /envelope/field/create-many

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`envelopeId`	string	Sim	O ID do envelope
`data`	array	Sim	Lista de configurações de campo

Cada item de data exige type, recipientId e uma posição: coordenadas explícitas (page, positionX, positionY, width, height) ou um marcador de texto (placeholder, com width, height e matchAll opcionais). Propriedades opcionais por item: envelopeItemId (em qual PDF do envelope colocar o campo; o padrão é o primeiro) e fieldMeta.

Exemplos

curl -X POST "https://app.kivosign.com.br/api/v2/envelope/field/create-many" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "envelopeId": "envelope_abcdefhiklmnorst",
    "data": [
      {
        "type": "SIGNATURE",
        "recipientId": 456,
        "page": 1,
        "positionX": 10,
        "positionY": 80,
        "width": 30,
        "height": 5
      },
      {
        "type": "DATE",
        "recipientId": 456,
        "page": 1,
        "positionX": 50,
        "positionY": 80,
        "width": 20,
        "height": 3
      },
      {
        "type": "TEXT",
        "recipientId": 456,
        "page": 1,
        "positionX": 10,
        "positionY": 70,
        "width": 40,
        "height": 4,
        "fieldMeta": {
          "type": "text",
          "label": "Cargo",
          "placeholder": "Informe seu cargo",
          "required": true
        }
      }
    ]
  }'

Resposta

{
  "data": [
    {
      "id": 101,
      "secondaryId": "field_abc123",
      "envelopeId": "envelope_abcdefhiklmnorst",
      "envelopeItemId": "envelope_item_abcdefhiklmnorst",
      "type": "SIGNATURE",
      "recipientId": 456,
      "page": 1,
      "positionX": "10",
      "positionY": "80",
      "width": "30",
      "height": "5",
      "customText": "",
      "inserted": false,
      "fieldMeta": {
        "type": "signature",
        "fontSize": 18,
        "overflow": "auto"
      }
    },
    {
      "id": 102,
      "secondaryId": "field_def456",
      "envelopeId": "envelope_abcdefhiklmnorst",
      "envelopeItemId": "envelope_item_abcdefhiklmnorst",
      "type": "DATE",
      "recipientId": 456,
      "page": 1,
      "positionX": "50",
      "positionY": "80",
      "width": "20",
      "height": "3",
      "customText": "",
      "inserted": false,
      "fieldMeta": {
        "type": "date",
        "fontSize": 12,
        "textAlign": "left",
        "overflow": "auto"
      }
    },
    {
      "id": 103,
      "secondaryId": "field_ghi789",
      "envelopeId": "envelope_abcdefhiklmnorst",
      "envelopeItemId": "envelope_item_abcdefhiklmnorst",
      "type": "TEXT",
      "recipientId": 456,
      "page": 1,
      "positionX": "10",
      "positionY": "70",
      "width": "40",
      "height": "4",
      "customText": "",
      "inserted": false,
      "fieldMeta": {
        "type": "text",
        "label": "Cargo",
        "placeholder": "Informe seu cargo",
        "required": true
      }
    }
  ]
}

Atualizar campos

Atualiza um ou mais campos em uma única requisição.

POST /envelope/field/update-many

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`envelopeId`	string	Sim	O ID do envelope
`data`	array	Sim	Lista de objetos de atualização

Cada item de data exige o id e o type do campo. As propriedades de posição (page, positionX, positionY, width, height), envelopeItemId e fieldMeta são opcionais: só os valores enviados são atualizados. Quando fieldMeta é enviado, ele substitui o fieldMeta salvo por inteiro, então inclua todas as propriedades que quer manter. Mudar o type sem enviar fieldMeta aplica o fieldMeta padrão do novo tipo. A atualização não aceita posicionamento por marcador; use coordenadas.

Exemplos

curl -X POST "https://app.kivosign.com.br/api/v2/envelope/field/update-many" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "envelopeId": "envelope_abcdefhiklmnorst",
    "data": [
      {
        "id": 101,
        "type": "SIGNATURE",
        "positionY": 85
      },
      {
        "id": 102,
        "type": "DATE",
        "positionY": 85
      }
    ]
  }'

Resposta

{
  "data": [
    {
      "id": 101,
      "secondaryId": "field_abc123",
      "envelopeId": "envelope_abcdefhiklmnorst",
      "envelopeItemId": "envelope_item_abcdefhiklmnorst",
      "type": "SIGNATURE",
      "recipientId": 456,
      "page": 1,
      "positionX": "10",
      "positionY": "85",
      "width": "30",
      "height": "5",
      "customText": "",
      "inserted": false,
      "fieldMeta": {
        "type": "signature",
        "fontSize": 18,
        "overflow": "auto"
      }
    },
    {
      "id": 102,
      "secondaryId": "field_def456",
      "envelopeId": "envelope_abcdefhiklmnorst",
      "envelopeItemId": "envelope_item_abcdefhiklmnorst",
      "type": "DATE",
      "recipientId": 456,
      "page": 1,
      "positionX": "50",
      "positionY": "85",
      "width": "20",
      "height": "3",
      "customText": "",
      "inserted": false,
      "fieldMeta": {
        "type": "date",
        "fontSize": 12,
        "textAlign": "left",
        "overflow": "auto"
      }
    }
  ]
}

Excluir campo

Remove um campo de um documento.

POST /envelope/field/delete

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`fieldId`	number	Sim	O ID do campo

Exemplos

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

Resposta

{
  "success": true
}

Posicionamento dos campos

Os campos usam coordenadas em percentual, relativas ao tamanho da página do PDF.

Propriedade	Faixa	Descrição
`positionX`	0-100	Posição horizontal a partir da borda esquerda (0 = borda esquerda)
`positionY`	0-100	Posição vertical a partir do topo (0 = topo)
`width`	0-100	Largura do campo em percentual da largura da página
`height`	0-100	Altura do campo em percentual da altura da página
`page`	1+	Número da página (começa em 1)

Sistema de coordenadas

(0,0) ─────────────────────────── (100,0)
  │                                   │
  │    ┌─────────┐                    │
  │    │  Campo  │ (positionX: 10,    │
  │    │         │  positionY: 20,    │
  │    └─────────┘  width: 30,        │
  │                 height: 5)        │
  │                                   │
(0,100) ─────────────────────────(100,100)

Exemplo: assinatura no canto inferior direito

const field = {
  type: 'SIGNATURE',
  recipientId: 123,
  page: 1,
  positionX: 60, // 60% a partir da esquerda
  positionY: 85, // 85% a partir do topo (perto do rodapé)
  width: 30, // 30% da largura da página
  height: 8, // 8% da altura da página
};

Posicionamento por marcador

Em vez de informar coordenadas exatas, você pode posicionar campos com marcadores de texto dentro do PDF. Inclua marcadores como {{signature, r1}} no documento e a KivoSign cria os campos nesses locais quando o documento é enviado.

Isso é útil quando você gera PDFs por código ou usa modelos com layout fixo.

Os marcadores só funcionam nos endpoints envelope.*. POST /template/use não processa marcadores.

Veja o guia Marcadores em PDF para a referência completa do formato, incluindo tipos de campo, identificadores de destinatário e opções de campo.

Marcadores pela API

POST /envelope/field/create-many aceita uma posição por marcador no lugar das coordenadas. Em vez de page, positionX, positionY, width e height, envie:

Campo	Tipo	Obrigatório	Descrição
`placeholder`	string	Sim	Texto a procurar no PDF (ex.: `{{name}}`). O campo é colocado na área da primeira ocorrência.
`width`	number	Não	Sobrescreve a largura do campo. O padrão é a largura do texto encontrado.
`height`	number	Não	Sobrescreve a altura do campo. O padrão é a altura do texto encontrado.
`matchAll`	boolean	Não	Cria um campo em cada ocorrência do marcador, e não só na primeira.

{
  "envelopeId": "envelope_abcdefhiklmnorst",
  "data": [
    {
      "type": "SIGNATURE",
      "recipientId": 456,
      "placeholder": "{{signature}}",
      "matchAll": true
    }
  ]
}

POST /envelope/field/update-many não aceita marcadores: a atualização de campos é só por coordenadas.

Opções de fieldMeta

Cada tipo de campo aceita configurações próprias em fieldMeta.

Opções comuns

Todos os tipos de campo aceitam estas opções básicas:

Opção	Tipo	Descrição
`label`	string	Texto exibido junto ao campo
`placeholder`	string	Texto de dica quando o campo está vazio
`required`	boolean	Se o campo é obrigatório
`readOnly`	boolean	Trava o campo com um valor pré-preenchido
`fontSize`	number	Tamanho do texto em pixels (8-96, padrão: 12)

Campo de assinatura

{
  "type": "SIGNATURE",
  "fieldMeta": {
    "type": "signature",
    "required": true
  }
}

Campo de texto

{
  "type": "TEXT",
  "fieldMeta": {
    "type": "text",
    "label": "Razão social",
    "placeholder": "Informe a razão social",
    "text": "Valor padrão",
    "characterLimit": 100,
    "textAlign": "left",
    "required": true
  }
}

Opção	Tipo	Descrição
`text`	string	Valor padrão
`characterLimit`	number	Máximo de caracteres
`textAlign`	string	`left`, `center` ou `right`
`lineHeight`	number	Espaçamento entre linhas (1-10)
`letterSpacing`	number	Espaçamento entre caracteres (0-100)

Campo numérico

{
  "type": "NUMBER",
  "fieldMeta": {
    "type": "number",
    "label": "Quantidade",
    "minValue": 1,
    "maxValue": 100,
    "value": "10",
    "required": true
  }
}

Opção	Tipo	Descrição
`value`	string	Valor padrão
`minValue`	number	Valor mínimo
`maxValue`	number	Valor máximo
`numberFormat`	string	Formato de exibição

Campo de data

{
  "type": "DATE",
  "fieldMeta": {
    "type": "date",
    "textAlign": "left",
    "required": true
  }
}

Campo de caixa de seleção

{
  "type": "CHECKBOX",
  "fieldMeta": {
    "type": "checkbox",
    "label": "Aceites",
    "values": [
      { "id": 1, "value": "Termos de uso", "checked": false },
      { "id": 2, "value": "Política de privacidade", "checked": false }
    ],
    "validationRule": "min",
    "validationLength": 1,
    "direction": "vertical",
    "required": true
  }
}

Opção	Tipo	Descrição
`values`	array	Lista de opções
`validationRule`	string	Tipo de validação das seleções
`validationLength`	number	Número usado na regra de validação
`direction`	string	Layout `vertical` ou `horizontal`

Campo de opção única (radio)

{
  "type": "RADIO",
  "fieldMeta": {
    "type": "radio",
    "label": "Forma de pagamento",
    "values": [
      { "id": 1, "value": "Cartão de crédito", "checked": false },
      { "id": 2, "value": "Pix", "checked": true },
      { "id": 3, "value": "Boleto", "checked": false }
    ],
    "direction": "vertical",
    "required": true
  }
}

Campo de lista suspensa

{
  "type": "DROPDOWN",
  "fieldMeta": {
    "type": "dropdown",
    "label": "Estado",
    "values": [{ "value": "São Paulo" }, { "value": "Rio de Janeiro" }, { "value": "Minas Gerais" }],
    "defaultValue": "São Paulo",
    "required": true
  }
}

Opção	Tipo	Descrição
`values`	array	Lista de opções
`defaultValue`	string	Opção pré-selecionada

Exemplo completo

Cria um bloco de assinatura com vários tipos de campo:

async function addSignatureBlock(envelopeId: string, recipientId: number) {
  const data = [
    {
      type: 'SIGNATURE',
      recipientId,
      page: 1,
      positionX: 10,
      positionY: 80,
      width: 30,
      height: 8,
      fieldMeta: {
        type: 'signature',
        required: true,
      },
    },
    {
      type: 'NAME',
      recipientId,
      page: 1,
      positionX: 10,
      positionY: 90,
      width: 30,
      height: 4,
      fieldMeta: {
        type: 'name',
        label: 'Nome por extenso',
      },
    },
    {
      type: 'DATE',
      recipientId,
      page: 1,
      positionX: 50,
      positionY: 80,
      width: 20,
      height: 4,
      fieldMeta: {
        type: 'date',
        label: 'Data',
      },
    },
    {
      type: 'TEXT',
      recipientId,
      page: 1,
      positionX: 50,
      positionY: 90,
      width: 30,
      height: 4,
      fieldMeta: {
        type: 'text',
        label: 'Cargo',
        placeholder: 'Informe seu cargo',
      },
    },
  ];

  const response = await fetch('https://app.kivosign.com.br/api/v2/envelope/field/create-many', {
    method: 'POST',
    headers: {
      Authorization: 'api_xxxxxxxxxxxxxxxx',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ envelopeId, data }),
  });

  return response.json();
}

Respostas de erro

Status	Descrição
`400`	Configuração de campo inválida ou documento já enviado
`401`	Chave de API inválida ou ausente
`404`	Documento, destinatário ou campo não encontrado
`500`	Erro no servidor

Os campos não podem ser alterados depois que o documento é enviado para assinatura. Faça todas as alterações enquanto o documento está em DRAFT.

Veja também

API de documentos - Crie e gerencie documentos
API de destinatários - Adicione signatários aos documentos
Tipos de campo - Referência detalhada dos tipos de campo

Objeto campo

Exemplo de objeto campo

Tipos de campo

Consultar campo

Parâmetros de caminho

Exemplos

Resposta

Criar campos

Corpo da requisição

Exemplos

Resposta

Atualizar campos

Corpo da requisição

Exemplos

Resposta

Excluir campo

Corpo da requisição

Exemplos

Resposta

Posicionamento dos campos

Sistema de coordenadas

Exemplo: assinatura no canto inferior direito

Posicionamento por marcador

Marcadores pela API

Opções de fieldMeta

Opções comuns

Campo de assinatura

Campo de texto

Campo numérico

Campo de data

Campo de caixa de seleção

Campo de opção única (radio)

Campo de lista suspensa

Exemplo completo

Respostas de erro

Veja também

Nesta página