API de destinatários

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 destinatário

{
  "id": 123,
  "envelopeId": "envelope_abcdefhiklmnorst",
  "email": "signatario@exemplo.com",
  "name": "João Silva",
  "role": "SIGNER",
  "signingOrder": 1,
  "token": "abc123...",
  "signedAt": "2024-01-15T10:30:00Z",
  "readStatus": "OPENED",
  "signingStatus": "SIGNED",
  "sendStatus": "SENT"
}

Campo	Tipo	Descrição
`id`	number	Identificador único do destinatário
`envelopeId`	string	ID do envelope associado
`email`	string	E-mail do destinatário
`name`	string	Nome de exibição do destinatário
`role`	string	Papel do destinatário (veja abaixo)
`signingOrder`	number \| null	Ordem na assinatura sequencial
`token`	string	Token único da URL de assinatura
`signedAt`	string \| null	Data/hora ISO da assinatura
`readStatus`	string	`NOT_OPENED` ou `OPENED`
`signingStatus`	string	`NOT_SIGNED`, `SIGNED` ou `REJECTED`
`sendStatus`	string	`NOT_SENT` ou `SENT`

Papéis dos destinatários

Papel	Descrição
`SIGNER`	Precisa assinar o documento. Os campos obrigatórios devem ser preenchidos.
`APPROVER`	Precisa aprovar o documento antes que os signatários continuem.
`VIEWER`	Pode ver o documento, mas não realiza nenhuma ação.
`CC`	Recebe uma cópia do documento concluído. Nenhuma ação necessária.
`ASSISTANT`	Pode preencher campos em nome de outro destinatário.

Consultar destinatário

Consulta um destinatário pelo ID.

GET /api/v2/envelope/recipient/{recipientId}

Exemplo

curl "https://app.kivosign.com.br/api/v2/envelope/recipient/789" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx"

Resposta

Retorna o objeto destinatário completo, incluindo os campos.

Criar destinatários

Adiciona um ou mais destinatários a um envelope.

POST /api/v2/envelope/recipient/create-many

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`envelopeId`	string	Sim	ID do envelope que receberá os destinatários
`data`	array	Sim	Lista de objetos destinatário

Cada item da lista data:

Campo	Tipo	Obrigatório	Descrição
`email`	string	Sim	E-mail do destinatário
`name`	string	Sim	Nome de exibição (máx. 255 caracteres)
`role`	string	Sim	Papel do destinatário (veja os papéis acima)
`signingOrder`	number	Não	Posição na assinatura sequencial
`accessAuth`	string[]	Não	Tipos de autenticação de acesso
`actionAuth`	string[]	Não	Tipos de autenticação de ação

Exemplo

curl -X POST "https://app.kivosign.com.br/api/v2/envelope/recipient/create-many" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "envelopeId": "envelope_abcdefhiklmnorst",
    "data": [
      {
        "email": "signatario@exemplo.com",
        "name": "João Silva",
        "role": "SIGNER",
        "signingOrder": 1
      },
      {
        "email": "aprovador@exemplo.com",
        "name": "Maria Souza",
        "role": "APPROVER",
        "signingOrder": 0
      }
    ]
  }'

Resposta

{
  "data": [
    {
      "id": 789,
      "envelopeId": "envelope_abcdefhiklmnorst",
      "email": "signatario@exemplo.com",
      "name": "João Silva",
      "role": "SIGNER",
      "signingOrder": 1,
      "token": "abc123def456",
      "signedAt": null,
      "readStatus": "NOT_OPENED",
      "signingStatus": "NOT_SIGNED",
      "sendStatus": "NOT_SENT"
    },
    {
      "id": 790,
      "envelopeId": "envelope_abcdefhiklmnorst",
      "email": "aprovador@exemplo.com",
      "name": "Maria Souza",
      "role": "APPROVER",
      "signingOrder": 0,
      "token": "def456ghi789",
      "signedAt": null,
      "readStatus": "NOT_OPENED",
      "signingStatus": "NOT_SIGNED",
      "sendStatus": "NOT_SENT"
    }
  ]
}

Atualizar destinatários

Atualiza um ou mais destinatários de um envelope. Disponível apenas para envelopes ainda não concluídos.

POST /api/v2/envelope/recipient/update-many

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`envelopeId`	string	Sim	ID do envelope com os destinatários
`data`	array	Sim	Lista de objetos de atualização

Cada item da lista data:

Campo	Tipo	Obrigatório	Descrição
`id`	number	Sim	ID do destinatário a atualizar
`email`	string	Não	Novo e-mail
`name`	string	Não	Novo nome de exibição (máx. 255 caracteres)
`role`	string	Não	Novo papel
`signingOrder`	number	Não	Nova posição na assinatura sequencial
`accessAuth`	string[]	Não	Tipos de autenticação de acesso
`actionAuth`	string[]	Não	Tipos de autenticação de ação

Exemplo

curl -X POST "https://app.kivosign.com.br/api/v2/envelope/recipient/update-many" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "envelopeId": "envelope_abcdefhiklmnorst",
    "data": [
      {
        "id": 789,
        "name": "João Pedro Silva",
        "signingOrder": 2
      }
    ]
  }'

Resposta

Retorna os destinatários atualizados em uma lista data.

Excluir destinatário

Remove um destinatário de um envelope. Disponível apenas para envelopes ainda não concluídos.

POST /api/v2/envelope/recipient/delete

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`recipientId`	number	Sim	ID do destinatário a remover

Exemplo

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

Resposta

{
  "success": true
}

Ordem de assinatura

Quando o envelope usa assinatura sequencial, os destinatários assinam na ordem definida por signingOrder.

Definindo a ordem

Ao criar os destinatários, informe os valores de signingOrder para controlar a sequência:

const response = await fetch('https://app.kivosign.com.br/api/v2/envelope/recipient/create-many', {
  method: 'POST',
  headers: {
    Authorization: 'api_xxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    envelopeId: 'envelope_abcdefhiklmnorst',
    data: [
      {
        email: 'aprovador@exemplo.com',
        name: 'Aprovador',
        role: 'APPROVER',
        signingOrder: 0, // Aprovadores normalmente vêm primeiro
      },
      {
        email: 'primeiro@exemplo.com',
        name: 'Primeiro signatário',
        role: 'SIGNER',
        signingOrder: 1,
      },
      {
        email: 'segundo@exemplo.com',
        name: 'Segundo signatário',
        role: 'SIGNER',
        signingOrder: 2,
      },
    ],
  }),
});

Para ativar a assinatura sequencial, defina signingOrder como SEQUENTIAL nos metadados do envelope ao criá-lo ou atualizá-lo. Veja a API de documentos para mais detalhes.

Como a ordem funciona

Destinatários com signingOrder menor assinam primeiro
Destinatários com o mesmo signingOrder podem assinar ao mesmo tempo
Destinatários CC recebem o documento depois que todas as assinaturas forem concluídas
Destinatários APPROVER precisam aprovar antes dos signatários com ordem maior

Opções de autenticação

Para mais segurança, você pode exigir autenticação adicional quando o destinatário acessar ou assinar o documento.

Autenticação de acesso

Controla quem pode ver o documento:

Tipo	Descrição
`ACCOUNT`	O destinatário precisa estar logado
`TWO_FACTOR_AUTH`	O destinatário precisa confirmar com 2FA

Autenticação de ação

Controla quem pode assinar o documento:

Tipo	Descrição
`ACCOUNT`	O destinatário precisa estar logado
`PASSKEY`	Exige autenticação por passkey
`TWO_FACTOR_AUTH`	Exige código 2FA
`PASSWORD`	Exige confirmação de senha
`EXPLICIT_NONE`	Desativa explicitamente a autenticação de ação

Exemplo

const response = await fetch('https://app.kivosign.com.br/api/v2/envelope/recipient/create-many', {
  method: 'POST',
  headers: {
    Authorization: 'api_xxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    envelopeId: 'envelope_abcdefhiklmnorst',
    data: [
      {
        email: 'signatario@exemplo.com',
        name: 'João Silva',
        role: 'SIGNER',
        accessAuth: ['ACCOUNT'],
        actionAuth: ['PASSKEY', 'TWO_FACTOR_AUTH'],
      },
    ],
  }),
});

Respostas de erro

Status	Descrição
`400`	Corpo da requisição inválido ou destinatário já existe
`400`	O envelope já foi concluído
`401`	Chave de API inválida ou ausente
`404`	Envelope ou destinatário não encontrado
`500`	Erro no servidor

Exemplo de resposta de erro

{
  "message": "Recipient already exists"
}

Veja também

API de documentos - Crie e gerencie envelopes
API de campos - Adicione campos de assinatura para os destinatários

Nesta página