Acesso à API por equipe

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.

Contexto da equipe

A API REST V2 não tem endpoints /team/*. Crie e gerencie equipes, membros e configurações de equipe no aplicativo web da KivoSign. Esta página explica como um token de equipe aplica o contexto daquela equipe aos recursos da API.

A API identifica a equipe pelo token. Você não informa um ID de equipe ao criar, listar ou usar envelopes. O ID da equipe do token define quais recursos a requisição pode acessar.

Tokens de API por equipe

Na KivoSign, todo token de API pertence a uma equipe específica. Ao criar um token, ele fica associado à equipe em que você está trabalhando.

Como funciona o escopo por equipe

Cada token pertence a exatamente uma equipe
Todas as operações com aquele token acessam os recursos daquela equipe
Documentos, modelos e outros recursos criados pela API pertencem à equipe do token
Não é possível acessar recursos de outras equipes com um único token

Criando tokens de equipe

Abra as configurações da sua equipe

Vá em Tokens de API

Clique em Criar token

O token ficará associado à equipe atual

Para trabalhar com várias equipes pela API, crie um token para cada equipe.

Permissões do token

O token herda as permissões do seu papel na equipe:

Papel	Permissões
`ADMIN`	Acesso total a todos os recursos e configurações
`MANAGER`	Criar, editar e excluir documentos e modelos
`MEMBER`	Criar e gerenciar os próprios documentos

Trabalhando com documentos da equipe

Com um token de equipe, todas as operações de documento ficam restritas àquela equipe.

Criar um documento da equipe

Documentos criados com um token de equipe pertencem à equipe:

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 da equipe",
    "recipients": [
      {
        "email": "signatario@exemplo.com",
        "name": "João Silva",
        "role": "SIGNER"
      }
    ]
  }' \
  -F "files=@./contrato.pdf;type=application/pdf"

Listar documentos da equipe

Consulte todos os documentos da equipe:

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

# Filtrar por status
curl -X GET "https://app.kivosign.com.br/api/v2/envelope?type=DOCUMENT&status=PENDING" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx"

Trabalhando com modelos da equipe

Modelos criados com um token de equipe ficam compartilhados com toda a equipe.

Criar um modelo da equipe

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": "TEMPLATE",
    "title": "Modelo de NDA",
    "recipients": [
      {
        "email": "placeholder@exemplo.com",
        "name": "Signatário",
        "role": "SIGNER",
        "fields": [
          {
            "identifier": 0,
            "type": "SIGNATURE",
            "page": 1,
            "positionX": 10,
            "positionY": 80,
            "width": 30,
            "height": 5
          }
        ]
      }
    ]
  }' \
  -F "files=@./modelo-nda.pdf;type=application/pdf"

Listar modelos da equipe

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

Papéis dos membros da equipe

Papel	Descrição
`ADMIN`	Controle total das configurações, membros e recursos da equipe
`MANAGER`	Gerencia documentos e modelos e vê os recursos da equipe
`MEMBER`	Cria e gerencia os próprios documentos dentro da equipe

Visibilidade dos documentos

Documentos da equipe têm uma configuração de visibilidade que controla quem pode acessá-los:

Visibilidade	Descrição
`EVERYONE`	Todos os membros da equipe podem ver
`MANAGER_AND_ABOVE`	Apenas gerentes e administradores podem ver
`ADMIN`	Apenas administradores podem ver

Defina a visibilidade ao criar o documento:

const payload = {
  type: 'DOCUMENT',
  title: 'Acordo confidencial',
  visibility: 'ADMIN', // Apenas administradores da equipe podem ver
  recipients: [...],
};

Fluxo com várias equipes

Para trabalhar com várias equipes, crie e gerencie um token de API para cada uma.

Exemplo: consultar documentos de várias equipes

const SALES_TEAM_TOKEN = process.env.SALES_TEAM_API_TOKEN;
const LEGAL_TEAM_TOKEN = process.env.LEGAL_TEAM_API_TOKEN;

// Documentos pendentes da equipe comercial
const salesResponse = await fetch('https://app.kivosign.com.br/api/v2/envelope?type=DOCUMENT&status=PENDING', {
  headers: { Authorization: SALES_TEAM_TOKEN },
});
const salesDocs = await salesResponse.json();

// Documentos concluídos da equipe jurídica
const legalResponse = await fetch('https://app.kivosign.com.br/api/v2/envelope?type=DOCUMENT&status=COMPLETED', {
  headers: { Authorization: LEGAL_TEAM_TOKEN },
});
const legalDocs = await legalResponse.json();

console.log(`Comercial: ${salesDocs.count} pendentes`);
console.log(`Jurídico: ${legalDocs.count} concluídos`);

Respostas de erro

Status	Descrição
`401`	Token de API inválido ou expirado
`403`	O token não tem permissão para esta operação
`404`	Recurso não encontrado ou inacessível para esta equipe

Exemplo de resposta de erro

{
  "message": "You do not have permission to access this resource"
}

Tokens de API só acessam recursos da equipe associada. Tentar acessar recursos de outra equipe retorna erro 403 ou 404.

Veja também

API de documentos - Crie e gerencie documentos
API de modelos - Trabalhe com modelos de documentos
Autenticação - Crie e gerencie tokens de API

Nesta página