Vivaintra
API docs by Redocly

Vivaintra API para Integração (1.2.0)

Download OpenAPI specification:Download

Introdução

Sabemos que manter a base de usuários em ambientes distribuídos é um dos desafios das implantações de sistemas. E por isso, a API em sua primeira versão, disponibiliza recursos para garantir essa integração.

Esta API é um serviço fornecido pela VivaIntra para seus clientes para integrar sua base de usuários (colaboradores) presente em seus softwares à nossa aplicação.

O que faz esta API?

  • Cria registros para novos usuários
  • Atualiza dados de registros existentes
  • Ativa e inativa usuários
  • Atualiza fotos dos usuários (avatar)

Todos têm acesso a esta API?

  • Todos os clientes do plano enterprise (nuvem ou in-house)

Todos os usuários têm acesso a esta API?

  • Não, somente os papeis que tiverem permissão para "gerenciar integração"
  • Para saber mais, acesse Painel Administrador / Permissões / Integração

Além da API, quais são as outras integrações disponíveis?

  • Integração Active Directory (pelo painel administrador e protoloco LDAP/LDAPS)
  • Integração HTTPS (por requisição automaticamente agendada)
  • Integração de Login com SSO Active Directory (agente local em servidor Windows Server)
  • Integração de Login com SSO (agente própria customizável com sistema de terceiro em ambiente in-house)
  • Integração de Login com Google e Agenda
  • Integração de Login com Outlook e Agenda

Como saber mais e obter documentações sobre as integrações disponíveis através do ambiente administrativo?

Como começar a usar esta API e testar seu funcionamento?

  • Teste a requisição de Autenticação e consiga um retorno de sucesso com um Token
  • Lembre-se que a autenticação é temporária e se for agendar algum processo interno, sempre execute a autenticação antes das suas requisições entre períodos distintos
  • Entenda como está estruturada nosso arquivo de CSV para integração de dados
  • Construa um CSV manualmente com um ou dois usuários e teste a requisição
  • Se desejar que a integração desative usuários, teste também este cenário
  • Por fim, execute a requisição de atualização de fotos (que não é em lote) e tudo estará correto.
  • Qualquer dúvida, você pode acionar nosso suporte em suporte@vivaintra.com

Como conseguir alguns dados que são solicitados na maioria das requisições?

  • Token: valor recebido após autenticação (login) via API
  • ID da Empresa: para todos os clientes enterprise seu código será 1
  • ALIAS da Empresa: esta informação está disponível em seu painel administrador no rodapé junto com a data da última atualização

Autenticação

Autenticação de usuário

Realize a autenticação para receber o token de acesso que precisará informar em todas as demais requisições.

Observações:

  • Este token recebido tem vida útil de até 4 horas.
  • Fique sempre atento às respostas desta requisição bem como à quantidade de requisições pois um número alto de requisições de autenticação com erros poderão ocasionar bloqueio temporário.
  • Recomenda-se que para a integração, um usuário específico seja criado ao invés das credenciais de algum colaborador que faz uso também da intranet.
Request Body schema: form-data
usuario
required
string

email do usuário (recomenda-se a criação de usuário específico para integração)

senha
required
string

senha do usuário no formato md5

coTokenSolicitante
required
string

seu token (do solicitante) no formato md5 que será usado posteriormente nas demais requisições

Observações:

  • gerar aleatoriamente sempre que precisar se autenticar
idEmpresa
required
integer
Default: 1

ID da empresa. No caso de clientes enterprise (nuvem ou in-house) seu ID sempre será 1.

Qualquer dúvida, consulte seu ID e seu ALIAS no painel administrador em Configurações > Sobre

aliasEmpresa
required
string

Alias da empresa é uma string, geralmente um apelido curto para o nome de sua empresa

Qualquer dúvida, consulte seu ID e seu ALIAS no painel administrador em Configurações > Sobre

Responses

Response samples

Content type
application/json
{
  • "type": "success",
  • "message": "Token cadastrado com sucesso",
  • "items": {
    }
}

Usuário

Cadastrar usuário

Cadastra um novo usuário na Vivaintra. O CPF é o identificador único do usuário.

Cargo, departamento e unidade são criados automaticamente na empresa caso ainda não existam.

A senha inicial do usuário é definida automaticamente pela Vivaintra (configuração interna da empresa) — o sistema integrador não envia e não recebe essa senha. O usuário é obrigado a definir uma nova senha no primeiro acesso.

header Parameters
v7a-integracao-id-empresa
required
any
Example: 1
v7a-integracao-alias
required
any
Example: vivaintra
v7a-integracao-token
required
any
Example: xxxxxxxxxxxxxxxxxx
Request Body schema: application/json
nome
required
string

Nome completo.

email
required
string

E-mail do usuário.

matricula
string

Matrícula funcional.

cpf
required
string

CPF do usuário — identificador único na Vivaintra.

cargo
required
string

Nome do cargo. Criado automaticamente na empresa se ainda não existir.

departamento
required
string

Nome do departamento. Criado automaticamente se não existir.

unidade
required
string

Nome da unidade. Criada automaticamente se não existir.

Responses

Request samples

Content type
application/json
{
  • "nome": "João da Silva",
  • "email": "joao.silva@empresa.com.br",
  • "matricula": "00123",
  • "cpf": "12345678901",
  • "cargo": "Analista de RH",
  • "departamento": "Recursos Humanos",
  • "unidade": "Matriz"
}

Response samples

Content type
application/json
{
  • "type": "success",
  • "message": "Usuário cadastrado com sucesso",
  • "items": [ ]
}

Atualizar usuário

Atualiza os dados de um usuário já existente, localizado por cpf ou email.

Observações:

  • O corpo representa o estado completo desejado do usuário após a atualização — não é uma atualização parcial.
  • O campo cpf é obrigatório no corpo mesmo quando a localização é feita por email (ele também pode ser usado para corrigir o CPF cadastrado).
  • Enviar matricula vazia ou omiti-la limpa o valor já cadastrado.
path Parameters
identificador
required
string
Enum: "cpf" "email"

Define por qual dado o usuário será localizado.

valor
required
string
Example: 12345678901

O valor correspondente ao identificador escolhido (e-mail pode ir com urlencode).

header Parameters
v7a-integracao-id-empresa
required
any
Example: 1
v7a-integracao-alias
required
any
Example: vivaintra
v7a-integracao-token
required
any
Example: xxxxxxxxxxxxxxxxxx
Request Body schema: application/json
nome
required
string

Nome completo.

email
required
string

E-mail do usuário.

matricula
string

Matrícula funcional. Enviar vazia ou omitir limpa o valor já cadastrado.

cpf
required
string

CPF do usuário. Obrigatório mesmo quando a localização é feita por email.

cargo
required
string

Nome do cargo. Criado automaticamente na empresa se ainda não existir.

departamento
required
string

Nome do departamento. Criado automaticamente se não existir.

unidade
required
string

Nome da unidade. Criada automaticamente se não existir.

Responses

Request samples

Content type
application/json
{
  • "nome": "João da Silva",
  • "email": "joao.silva@empresa.com.br",
  • "matricula": "00123",
  • "cpf": "12345678901",
  • "cargo": "Analista de RH",
  • "departamento": "Recursos Humanos",
  • "unidade": "Matriz"
}

Response samples

Content type
application/json
{
  • "type": "success",
  • "message": "Usuário cadastrado com sucesso",
  • "items": [ ]
}

Ativar usuário

Ativa um usuário, localizado por cpf ou email. Sem corpo de requisição.

path Parameters
identificador
required
string
Enum: "cpf" "email"

Define por qual dado o usuário será localizado.

valor
required
string
Example: 12345678901

O valor correspondente ao identificador escolhido (e-mail pode ir com urlencode).

header Parameters
v7a-integracao-id-empresa
required
any
Example: 1
v7a-integracao-alias
required
any
Example: vivaintra
v7a-integracao-token
required
any
Example: xxxxxxxxxxxxxxxxxx

Responses

Response samples

Content type
application/json
{
  • "type": "success",
  • "message": "Usuário cadastrado com sucesso",
  • "items": [ ]
}

Inativar usuário

Inativa um usuário, localizado por cpf ou email. Sem corpo de requisição.

path Parameters
identificador
required
string
Enum: "cpf" "email"

Define por qual dado o usuário será localizado.

valor
required
string
Example: 12345678901

O valor correspondente ao identificador escolhido (e-mail pode ir com urlencode).

header Parameters
v7a-integracao-id-empresa
required
any
Example: 1
v7a-integracao-alias
required
any
Example: vivaintra
v7a-integracao-token
required
any
Example: xxxxxxxxxxxxxxxxxx

Responses

Response samples

Content type
application/json
{
  • "type": "success",
  • "message": "Usuário cadastrado com sucesso",
  • "items": [ ]
}

Sincronização de dados

Sincronizar dados de usuários

Envie um arquivo no formato CSV com os dados de todos os colaboradores para importação em lote.

Observações:

  • um registro por linha
  • colunas separadas por ,
header Parameters
v7a-integracao-token
required
any
Example: xxxxxxxxxxxxxxxxxx
v7a-integracao-id-empresa
required
any
Example: 1
v7a-integracao-alias
required
any
Example: vivaintra
Request Body schema: multipart/form-data
csv
required
any

arquivo no formato .CSV

Modelo do arquivo CSV
tpComparacao
required
string
Enum: "email" "cpf" "matricula"

comparação escolhida para realizar cruzamento com base de dados de usuários do VivaIntra

nmSenhaPadrao
required
string

Senha padrão para novos usuários

tpAlterarSenha
required
string
Enum: "nao-solicitar" "alterar-senha"

Solicitar ou não a alteração de senha no primeiro acesso

tpAcaoInativar
required
string
Enum: "todos" "nenhum"

Inativar ou não os usuários que não estejam no arquivo CSV

tpDateFormat
required
string
Enum: "d/m/Y" "Y-m-d"

Formato da data no arquivo CSV

Responses

Response samples

Content type
application/json
{
  • "type": "success",
  • "message": "Usuarios importados com sucesso",
  • "items": [ ]
}

Cadastro de avatar

header Parameters
v7a-integracao-token
required
any
Example: xxxxxxxxxxxxxxxxxx
v7a-integracao-id-empresa
required
any
Example: 1
v7a-integracao-alias
required
any
Example: vivaintra
Request Body schema: multipart/form-data
Any of
foto
required
string <binary> <= 200MB characters

imagem do avatar em formatos image/png ou image/jpeg

email
required
string

email do usuário de destino da atualização

id
integer

id do usuário de destino da atualização

coCpf
integer

CPF do usuário de destino da atualização

coMatricula
integer

código da matrícula do usuário de destino da atualização

coExterno1
string

código coExterno1 do usuário de destino da atualização

Responses

Response samples

Content type
application/json
{
  • "type": "success",
  • "message": "Avatar cadastrado com sucesso",
  • "items": [ ]
}

Sincronização de Holerites

Sincronização de Holerites

Envie um arquivo no formato XML com os dados de todos os colaboradores para importação em lote.

Cada lote deve ser respectivamente para uma competência e um tipo. Se for enviado um lote com a mesma competência e tipo, os dados serão atualizados.

Se for possível, seguir exatamente a mesma estrutura do exemplo. O XML pode ser enviado em formato de string ou como body

Request Body schema: multipart/form-data
xml
required
any

arquivo no formato .xml

Modelo do arquivo XML
idTipoHolerite
required
integer

código do tipo de holerite (configurado via painel de controle)

anoCompetencia
required
integer

Ano da competência

mesCompetencia
required
integer

Mês da competência

Responses

Response samples

Content type
application/json
{
  • "type": "success",
  • "message": "Holerites importados com sucesso",
  • "items": [ ]
}