API de modelos

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

{
  "id": "envelope_document123",
  "recipients": [
    {
      "id": 1,
      "name": "João Silva",
      "email": "joao.silva@exemplo.com",
      "token": "recipient_token",
      "role": "SIGNER",
      "signingOrder": 1,
      "signingUrl": "https://app.kivosign.com.br/sign/recipient_token"
    }
  ]
}

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

const distribution = await distributionResponse.json();
console.log('URL de assinatura:', distribution.recipients[0].signingUrl);

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

{
  "id": 123,
  "envelopeId": "envelope_abc123xyz",
  "type": "PRIVATE",
  "visibility": "EVERYONE",
  "title": "Contrato de trabalho",
  "externalId": "modelo-ct-001",
  "publicTitle": null,
  "publicDescription": null,
  "userId": 1,
  "teamId": 5,
  "folderId": null,
  "createdAt": "2025-01-10T08:00:00.000Z",
  "updatedAt": "2025-01-10T08:30:00.000Z",
  "recipients": [
    {
      "id": 1,
      "email": "colaborador@exemplo.com",
      "name": "Colaborador",
      "role": "SIGNER",
      "signingOrder": 1
    },
    {
      "id": 2,
      "email": "rh@empresa.com.br",
      "name": "Gerente de RH",
      "role": "SIGNER",
      "signingOrder": 2
    }
  ],
  "fields": [
    {
      "id": 101,
      "type": "SIGNATURE",
      "page": 1,
      "positionX": 10,
      "positionY": 80,
      "width": 30,
      "height": 5,
      "recipientId": 1
    }
  ],
  "templateMeta": {
    "subject": "Seu contrato de trabalho",
    "message": "Por favor, revise e assine seu contrato de trabalho.",
    "redirectUrl": "https://exemplo.com/boas-vindas"
  },
  "directLink": null
}

GET /template

{
  "data": [
    {
      "id": 123,
      "envelopeId": "envelope_abc123",
      "type": "PRIVATE",
      "title": "Contrato de trabalho",
      "createdAt": "2025-01-10T08:00:00.000Z",
      "updatedAt": "2025-01-10T08:30:00.000Z",
      "recipients": [
        {
          "id": 1,
          "email": "colaborador@exemplo.com",
          "name": "Colaborador",
          "role": "SIGNER"
        }
      ]
    }
  ],
  "count": 25,
  "currentPage": 1,
  "perPage": 10,
  "totalPages": 3
}

GET /template/{templateId}

POST /template/use

{
  "id": 789,
  "envelopeId": "envelope_xyz789",
  "status": "PENDING",
  "source": "TEMPLATE",
  "title": "Contrato de trabalho",
  "externalId": "contrato-2025-001",
  "recipients": [
    {
      "id": 1,
      "envelopeId": "envelope_xyz789",
      "documentId": 789,
      "templateId": null,
      "email": "joao.silva@exemplo.com",
      "name": "João Silva",
      "role": "SIGNER",
      "signingStatus": "NOT_SIGNED",
      "signingOrder": 1
    }
  ]
}

const document = await response.json();

const distributionResponse = await fetch(`${BASE_URL}/envelope/distribute`, {
  method: 'POST',
  headers: {
    Authorization: API_TOKEN,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    envelopeId: document.envelopeId,
  }),
});

const distribution = await distributionResponse.json();
console.log('URL de assinatura:', distribution.recipients[0].signingUrl);

const response = await fetch(`${BASE_URL}/template/use`, {
  method: 'POST',
  headers: {
    Authorization: API_TOKEN,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    templateId: 123,
    recipients: [{ id: 1, email: 'signatario@exemplo.com', name: 'Signatário' }],
    override: {
      title: 'Título personalizado do documento',
      subject: 'Assunto personalizado do e-mail',
      message: 'Mensagem personalizada do e-mail',
      timezone: 'America/Sao_Paulo',
      dateFormat: 'dd/MM/yyyy',
      redirectUrl: 'https://exemplo.com/redirecionamento',
      language: 'pt-BR',
      typedSignatureEnabled: true,
      uploadSignatureEnabled: false,
      drawSignatureEnabled: true,
    },
    distributeDocument: true,
  }),
});

type PrefillField = {
  id: number; // ID do campo no modelo
  type: string; // Tipo do campo (precisa ser igual ao do modelo)
  label?: string; // Sobrescrita opcional do rótulo
  placeholder?: string; // Placeholder opcional (só text/number)
  value: string | string[]; // Valor a pré-preencher
};

const response = await fetch(`${BASE_URL}/template/use`, {
  method: 'POST',
  headers: {
    Authorization: API_TOKEN,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    templateId: 123,
    recipients: [{ id: 1, email: 'signatario@exemplo.com', name: 'Signatário' }],
    prefillFields: [
      // Campo de texto
      {
        id: 101,
        type: 'text',
        value: 'João Silva',
      },
      // Campo numérico
      {
        id: 102,
        type: 'number',
        value: '50000',
      },
      // Campo de data
      {
        id: 103,
        type: 'date',
        value: '2025-03-15',
      },
      // Opção única
      {
        id: 104,
        type: 'radio',
        value: 'clt',
      },
      // Múltipla escolha
      {
        id: 105,
        type: 'checkbox',
        value: ['saude', 'odonto', 'vale-refeicao'],
      },
      // Lista suspensa
      {
        id: 106,
        type: 'dropdown',
        value: 'engenharia',
      },
    ],
    distributeDocument: true,
  }),
});

POST /template/update

POST /template/duplicate

POST /template/delete

{
  "success": true
}

POST /template/direct/create

{
  "id": 456,
  "token": "abc123xyz",
  "templateId": 123,
  "directTemplateRecipientId": 1,
  "enabled": true,
  "createdAt": "2025-01-15T10:00:00.000Z"
}

POST /template/direct/toggle

POST /template/direct/delete

const API_TOKEN = process.env.KIVOSIGN_API_TOKEN;
const BASE_URL = 'https://app.kivosign.com.br/api/v2';

async function sendEmploymentContract(employeeData: {
  email: string;
  name: string;
  position: string;
  salary: number;
  startDate: string;
}) {
  // 1. Consultar o modelo para obter os IDs de destinatários e campos
  const templateResponse = await fetch(`${BASE_URL}/template/456`, {
    headers: { Authorization: API_TOKEN },
  });
  const template = await templateResponse.json();

  // 2. Encontrar o destinatário do colaborador
  const employeeRecipient = template.recipients.find(
    (r) => r.role === 'SIGNER' && r.signingOrder === 1
  );

  // 3. Encontrar os campos a pré-preencher
  const positionField = template.fields.find(
    (f) => f.fieldMeta?.label === 'Cargo'
  );
  const salaryField = template.fields.find(
    (f) => f.fieldMeta?.label === 'Salário'
  );
  const startDateField = template.fields.find(
    (f) => f.type === 'DATE'
  );

  // 4. Criar o documento a partir do modelo com os dados pré-preenchidos
  const documentResponse = await fetch(`${BASE_URL}/template/use`, {
    method: 'POST',
    headers: {
      Authorization: API_TOKEN,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      templateId: 456,
      recipients: [
        {
          id: employeeRecipient.id,
          email: employeeData.email,
          name: employeeData.name,
        },
      ],
      prefillFields: [
        {
          id: positionField.id,
          type: 'text',
          value: employeeData.position,
        },
        {
          id: salaryField.id,
          type: 'number',
          value: employeeData.salary.toString(),
        },
        {
          id: startDateField.id,
          type: 'date',
          value: employeeData.startDate,
        },
      ],
      override: {
        subject: `Contrato de trabalho de ${employeeData.name}`,
        message: `Olá ${employeeData.name},\n\nPor favor, revise e assine seu contrato de trabalho.`,
      },
      distributeDocument: false,
      externalId: `contrato-ct-${Date.now()}`,
    }),
  });

  const document = await documentResponse.json();

  // 5. Distribuir o envelope e obter os links de assinatura
  const distributionResponse = await fetch(`${BASE_URL}/envelope/distribute`, {
    method: 'POST',
    headers: {
      Authorization: API_TOKEN,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      envelopeId: document.envelopeId,
    }),
  });
  const distribution = await distributionResponse.json();

  return {
    envelopeId: document.envelopeId,
    signingUrl: distribution.recipients[0].signingUrl,
  };
}

const result = await sendEmploymentContract({
  email: 'joao.silva@exemplo.com',
  name: 'João Silva',
  position: 'Engenheiro Sênior',
  salary: 120000,
  startDate: '2025-03-01',
});

console.log('Documento criado:', result.envelopeId);
console.log('URL de assinatura:', result.signingUrl);