1 Introdução
Esta documentação tem como objetivo apoiar a integração do TopPonto com sistemas externos, oferecendo uma interface de comunicação robusta e eficiente por meio de sua API REST baseada em HTTPS.
A API do TopPonto permite o gerenciamento completo de dados como empresas, funcionários, horários e outros recursos essenciais. Com ela, é possível executar operações de consulta, criação, atualização e exclusão de dados de forma segura e flexível, independentemente do sistema operacional ou linguagem de programação utilizada.
Com arquitetura moderna e foco em escalabilidade, a API foi desenvolvida para simplificar o processo de integração, atendendo desde operações básicas até cenários mais complexos. Este documento apresenta os métodos de autenticação necessários e fornece exemplos práticos de requisições e respostas para facilitar a implementação.
Caso tenha dúvidas, sugestões ou precise de suporte durante a integração, entre em contato conosco pelo e-mail: [email protected]
2 Habilitar usuário
Para habilitar um usuário de integração no sistema, é necessário que o cadastro seja realizado por um administrador ou por um usuário do TopPonto Web com permissões de criação. Durante esse processo, as seguintes informações obrigatórias devem ser fornecidas:
- Nome: Nome completo do usuário, utilizado para identificação.
- CPF: Cadastro de Pessoa Física, utilizado como identificador único no sistema.
- Senha: Credenciais de acesso que serão utilizadas pelo usuário.
- Grupo: Grupo de permissões que define o nível de acesso, especialmente para fins de integração.
Entre os grupos disponíveis, existe um grupo padrão chamado API de Integração, que pode ser utilizado para conceder as permissões iniciais necessárias para o uso da API. Este grupo é recomendado para facilitar a configuração e garantir o acesso adequado aos recursos disponíveis.
Além das permissões gerais de incluir, editar, atualizar e deletar, o sistema também permite configurar restrições por empresa e departamento. Ou seja, é possível limitar o acesso do usuário a departamentos específicos dentro de empresas específicas. Com isso, todos os dados acessados por esse usuário serão automaticamente filtrados conforme essas permissões, garantindo maior controle e segurança no uso da API.
3 SDK TopPonto Web
Para facilitar a integração com a nossa API, disponibilizamos uma SDK desenvolvida em C# que encapsula as chamadas mais comuns e auxilia no desenvolvimento da sua aplicação.
Link para Download
4 Retorno de requisições
Todas as respostas da API seguem um formato padronizado, projetado para facilitar tanto a leitura quanto o processamento automatizado das informações. Esse formato inclui os seguintes campos:
{
"message": String,
"body": Object,
"status": Number
}5 Endpoint Base
O endpoint base para a integração com o sistema TopPonto é o ponto de entrada para todas as requisições à API.
https://integracao.topponto.com.br
Utilize este endpoint como referência para executar todas as operações disponíveis na integração.
6 Versão
Envio da Versão da API
Para garantir a compatibilidade com diferentes versões da API, a versão da API deve ser incluída no cabeçalho (Header) de todas as requisições. Esse cabeçalho informa ao servidor qual versão da API o cliente deseja utilizar.
Versão atual
A versão atual da API é: 1
| Headers | |
| X-Api-Version | “versao” |
Exemplo:
X-Api-Version: 1Erros Catalogados
| Campo | Mensagem | Código Http |
| X-Api-Version | O cabeçalho ‘X-Api-Version’ é obrigatório. | 400 – Bad Request |
| Versão da Api não suportada. | 404 – Not Found |
7 Autenticação
Endpoint
https://integracao.topponto.com.br/auth
Estrutura
| Método | Cabeçalho | Body |
| POST | Content-Type: application/jsonX-Api-Version: 1 | JSON |
Parâmetros
| Campo | Tipo | Descrição |
| user | String | Nome de usuário para autenticação. |
| password | String | Senha do usuário. |
| domain | String | Domínio associado a empresa. |
Requisição (JSON)
Link de acesso ao software: https://cliente.topponto.com.br
{
"user": "usuario_integracao",
"password": "123456",
"domain": "cliente"
}Resposta
{
"message": "Autenticação realizada com sucesso.",
"body": {
"token": "token"
},
"status": 200
}8 Envio do Token
Para acessar os demais endpoints da API, o token retornado após a autenticação bem-sucedida deve ser incluído no cabeçalho (Header) de todas as requisições subsequentes. Esse token é necessário para validar a autorização do usuário.
| Headers | |
| X-Auth-Token | “token” |
Erros Catalogados
| Campo | Mensagem | Código Http |
| Usuário | O campo ‘user’ é obrigatório. | 400 – Bad Request |
| Usuário não encontrado. Informe um id válido. | 404 – Not Found | |
| Usuário Api inativo, entre em contato com seu administrador. | 404 – Not Found | |
| O usuário não tem acesso a Integração Api. | 404 – Not Found | |
| O usuário não tem acesso a este método. Realize a autenticação novamente e, caso persista, verifique com seu administrador. | 404 – Not Found | |
| Senha | O campo ‘password’ é obrigatório. | 400 – Bad Request |
| A senha informada está incorreta. | 401 – Unauthorized | |
| Domínio | O campo ‘domain’ é obrigatório. | 400 – Bad Request |
| Domínio não encontrado. | 404 – Not Found | |
| Erro Geral | Ocorreu um erro no processo de Autenticação da Api. | 500 – Internal Server Error |