Vivaintra API para Integração (1.1.2)
Download OpenAPI specification:Download
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
- Atualiza status (inativação) de 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 papéis 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á estruturado 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 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 feitas 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:
|
| idEmpresa required | integer Default: 1 ID da empresa. No caso de clientes enterprise (nuvem ou in-house) seu ID sempre será 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
- 200
- 412
{- "type": "success",
- "message": "Ok",
- "items": {
- "token": "9176-exemplo-md5-auto-58f7d8d23"
}
}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
,
Request Body schema: multipart/form-data
| csv required | |
| tpComparacao required | string Enum: "email" "cpf" "matricula" comparação escolhida para realizar cruzamento com base de dados de usuários do VivaIntra |
| senhaPadrao 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
- 200
- 401
{- "type": "success",
- "message": "Usuários 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
em sua request de
| foto required | string <binary> <= 2048MB characters imagem do avatar em formatos image/png ou image/jpeg |
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 |
Responses
Response samples
- 200
- 401
{- "type": "success",
- "message": "Avatar atualizado com sucesso",
- "items": [ ]
}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 | |
| idTipoHolerite required | int código do tipo de holerite (configurado via painel de controle) |
| anoCompetencia required | int Ano da competência |
| mesCompetencia required | int Mês da competência |
Responses
Response samples
- 200
- 401
{- "type": "success",
- "message": "Holerites importados com sucesso",
- "items": [ ]
}