10 Eventos
A funcionalidade de exportação de eventos é realizada em quatro etapas principais. Abaixo, segue o detalhamento passo a passo de como utilizá-la:
1ª Etapa: Consultar o tipo de layout do evento
O primeiro passo consiste em identificar os layouts disponíveis para exportação. Para isso, realize uma requisição ao endpoint de consulta de layouts. Esse endpoint retorna informações como o id
, descrição e formatos de cada layout disponível, permitindo que você selecione o mais adequado ao seu evento.
Recomendação: certifique-se de compreender a estrutura do layout antes de prosseguir para as próximas etapas.
2ª Etapa: Fazer a requisição para criar o processo de exportação
Com o idLayout
em mãos, envie uma requisição ao endpoint de criação de processo. Nesta etapa, é necessário fornecer os parâmetros exigidos para a geração do evento, incluindo o identificador do layout (idLayout
). Além disso, informe quaisquer filtros ou critérios específicos, conforme o evento que deseja exportar.
Observação: a exportação é assíncrona, ou seja, você receberá um identificador único (codigo
) para acompanhar o progresso.
3ª Etapa: Acompanhar o andamento da geração
Com o codigo
de exportação obtido na etapa anterior, utilize o endpoint de acompanhamento para verificar o estado atual do processo. Esse endpoint informa o andamento da geração, incluindo a porcentagem de conclusão.
Dica: realize essa verificação periodicamente (sugerido: a cada 5 segundos) para evitar sobrecarga no servidor.
4ª Etapa: Solicitar o arquivo final
Assim que o acompanhamento indicar que a geração foi concluída (100%), faça uma requisição ao endpoint de download utilizando o mesmo codigo
de exportação.
Importante: confirme o recebimento e valide os dados do arquivo gerado antes de utilizá-lo.
10.1 Consultar layouts (lista)
Retorna uma lista de layouts cadastrados.
Endpoint
https://integracao.topponto.com.br/evento/layouts
Estrutura
Método | Cabeçalho | Body |
GET | Content-Type: application/json X-Auth-Token: “token”X-Api-Version: 1 | JSON |
Parâmetros (Não se enquadra)
Não há parâmetros a serem passados na requisição.
Requisição (Não se enquadra)
Não há dados a serem enviados na requisição.
Resposta
{
"message": "Consulta realizada com sucesso.",
"body": [
{
"idLayout": 1,
"descricao": "BANCO DE HORAS",
"formato": " [E-X:1] [M:5] [{BH-C}VC:5] [{BH-D}VC:5] ",
"formatoDataExportacao": "DD/MM/YYYY",
"delimitador": "|",
"delimitadorData": "/",
"delimitadorHora": ",",
"sabadoDiaUtil": false,
"domingoDiaUtil": false,
"horaSexagesimal": false,
"porLinha": false,
"exportarEventosZerados": true,
"importacao": true,
"exportacao": true,
"formatoDataPeriodo": "DD/MM/YYYY"
},
...
],
"status": 200
}
Erros catalogados
Não há erros catalogados para este método.
10.2 Criar processo
Criar um novo evento de exportação de acordo com o layout.
Endpoint
https://integracao.topponto.com.br/evento
Estrutura
Método | Cabeçalho | Body |
POST | Content-Type: application/json X-Auth-Token: “token”X-Api-Version: 1 | JSON |
Parâmetros
Campo | Tipo | Restrição | Obrigatório | Descrição |
idLayout | Number | 1 a N (Número Positivo) | Sim | Identificador único do layout. |
idFuncionario | Number | 1 a N (Número Positivo) ou NULL | Não | Identificador único do funcionario. |
idCei | Number | 1 a N (Número Positivo) ou NULL | Não | Identificador único do cei. |
idDepartamento | Number | 1 a N (Número Positivo) ou NULL | Não | Identificador único do departamento. |
idEmpresa | Number | 1 a N (Número Positivo) ou NULL | Não | Identificador único da Empresa. |
empresaAtiva | Boolean | true ou false | Sim | true para empresas ativas e false para todas. |
departamentoAtivo | Boolean | true ou false | Sim | true para deparatamentos ativos e false para todos. |
funcionarioAtivo | Boolean | true ou false | Sim | true para funcionarios ativos e false para todos. |
dataExportacao | String | Exatos 10 caracteres | Sim | Data de exportação do evento (formato DD/MM/AAAA), de acordo com a necessidade. |
periodoInicio | String | Exatos 10 caracteres | Sim | Data de inicio do dados (formato DD/MM/AAAA). |
periodoFim | String | Exatos 10 caracteres | Sim | Data final do dados (formato DD/MM/AAAA). |
Requisição (JSON)
{
"idLayout": 5,
"idFuncionario": null,
"idCei": null,
"idDepartamento": null,
"idEmpresa": null,
"empresaAtiva": true,
"departamentoAtivo": true,
"funcionarioAtivo": true,
"dataExportacao": "19/11/2024",
"periodoInicio": "01/11/2024",
"periodoFim": "19/11/2024"
}
Resposta
{
"message": "Criado com sucesso.",
"body": {
"codigo": "2a11a912-9af3-4e0a-8039-ca543b3c1829",
"descricao": "INICIANDO_PROCESSO",
"dataAtualizacao": 1732217938809,
"progresso": 0.0
},
"status": 201
}
Erros catalogados
Campo | Mensagem | Código Http |
idLayout | O id do layout não pode ser nulo. | 400 – Bad Request |
O id do layout deve ser maior que 0. | 400 – Bad Request | |
Layout informando não cadastrado. | 404 – Not Found | |
Layout do arquivo não encontrado. | 404 – Not Found | |
idFuncionario | O id do funcionário deve ser maior que 0. | 400 – Bad Request |
Funcionário não encontrado. Informe um id válido. | 404 – Not Found | |
idCei | O id do cei deve ser maior que 0. | 400 – Bad Request |
Cei não encontrado. Informe um id válido. | 404 – Not Found | |
idEmpresa | O id da empresa deve ser maior que 0. | 400 – Bad Request |
Empresa não encontrada. Informe um id válido. | 404 – Not Found | |
idDepartamento | O id do departamento deve ser maior que 0. | 400 – Bad Request |
Departamento não encontrado. Informe um id válido. | 404 – Not Found | |
empresaAtiva | O campo empresaAtiva não pode ser nulo. | 400 – Bad Request |
departamentoAtivo | O campo departamentoAtivo não pode ser nulo. | 400 – Bad Request |
funcionarioAtivo | O campo funcionarioAtivo não pode ser nulo. | 400 – Bad Request |
dataExportacao | O campo dataExportacao não pode ser vazio. | 400 – Bad Request |
O campo dataExportacao ultrapassou o limite definido. | 400 – Bad Request | |
O campo dataExportacao deve estar no formato dd/MM/yyyy | 400 – Bad Request | |
periodoInicio | O período de inicio não pode ser vazio. | 400 – Bad Request |
O período de inicio ultrapassou o limite definido. | 400 – Bad Request | |
O período de inicio deve estar no formato dd/MM/yyyy | 400 – Bad Request | |
O período de inicio deve ser inferior ao período de fim. | 400 – Bad Request | |
periodoFim | O período fim não pode ser vazio. | 400 – Bad Request |
O período fim ultrapassou o limite definido. | 400 – Bad Request | |
O período fim deve estar no formato dd/MM/yyyy | 400 – Bad Request | |
periodoInicio periodoFim | O intervalo entre as datas não pode ultrapassar 12 meses. | 400 – Bad Request |
10.3 Acompanhar processo
Retorna o processo de exportação de um evento específico com base no codigo
informado no endpoint — este codigo
é obtido na etapa 7.2 – Criar Processo.
Durante a operação:
- O campo
descricao
refletirá o estado atual do processo, alternando entre mensagens como"INICIANDO_PROCESSO"
,"GERANDO_ARQUIVO"
e, ao final,"CONCLUIDO"
. - O campo
progresso
indicará o percentual de conclusão, aumentando gradativamente até atingir"progresso": 100.0
.
Quando o campo progresso
alcançar 100%, o arquivo estará pronto para ser baixado. Para obter o arquivo final, faça uma solicitação na etapa 7.4 – Consultar, utilizando o mesmo codigo
informado anteriormente.
Como se trata de um processo assíncrono, recomenda-se realizar consultas ao endpoint em intervalos de pelo menos 5 segundos, a fim de evitar sobrecarga no servidor por excesso de requisições.
Endpoint
https://integracao.topponto.com.br/evento/codigo
Estrutura
Método | Cabeçalho | Path Variable |
GET | Content-Type: application/json X-Auth-Token: “token”X-Api-Version: 1 | Integer |
Parâmetros
Campo | Tipo | Restrição | Obrigatório | Descrição |
codigo | String | Gerado e retornado no processo de exportação. Não deve ser informado manualmente. | Sim | Identificador único do processo de exportação. |
Requisição (URL)
https://integracao.topponto.com.br/evento/2a11a912-9af3-4e0a-8039-ca543b3c1829
Resposta
{
"message": "Consulta realizada com sucesso.",
"body": {
"codigo": "2a11a912-9af3-4e0a-8039-ca543b3c1829",
"descricao": "CONCLUIDO",
"dataAtualizacao": 1732021779983,
"progresso": 100.0
},
"status": 200
}
Erros catalogados
Campo | Mensagem | Código Http |
codigo | Processo cancelado, realize uma nova solicitação. | 200 – OK |
Código informado não pode ser nulo ou vazio. | 400 – Bad Request | |
Verifique o código informado, não foram encontrados processos. | 404 – Not Found |
10.4 Cancelar processo
A partir do código, encerra o processo de geração do arquivo caso ele ainda esteja em andamento.
Endpoint
https://integracao.topponto.com.br/evento/codigo
Estrutura
Método | Cabeçalho | Path Variable |
DELETE | Content-Type: application/json X-Auth-Token: “token”X-Api-Version: 1 | Integer |
Parâmetros
Campo | Tipo | Restrição | Obrigatório | Descrição |
codigo | String | Gerado e retornado no processo de criação do processo. | Sim | Identificador único do processo de exportação. |
Requisição (URL)
https://integracao.topponto.com.br/evento/2a11a912-9af3-4e0a-8039-ca543b3c1829
Resposta
{
"message": "Cancelado com sucesso.",
"body": {
"codigo": "2a11a912-9af3-4e0a-8039-ca543b3c1829",
"descricao": "CARREGANDO_DADOS_GERA_FREQUENCIA",
"dataAtualizacao": 1734520976153,
"progresso": 6.523579201934719
},
"status": 200
}
Erros catalogados
Campo | Mensagem | Código Http |
codigo | Código informado não pode ser nulo ou vazio. | 404 – Not Found |
10.5 Consultar
Apartir do codigo, busca o arquivo gerado correspondente e retorna seu conteúdo diretamente na resposta da requisição.
Endpoint
https://integracao.topponto.com.br/evento/arquivo/codigo
Estrutura
Método | Cabeçalho | Path Variable |
GET | Content-Type: application/json X-Auth-Token: “token”X-Api-Version: 1 | Integer |
Parâmetros
Campo | Tipo | Restrição | Obrigatório | Descrição |
codigo | String | Gerado e retornado no processo de criação do processo. | Sim | Identificador único do processo de exportação. |
Requisição (URL)
https://integracao.topponto.com.br/evento/arquivo/2a11a912-9af3-4e0a-8039-ca543b3c1829
Resposta
{
"message": "Consulta realizada com sucesso.",
"body": "2|5979 |00000|00000|\r\n2|5983 |00000|00000|\r\n1|15377|00000|00000|",
"status": 200
}
Erros catalogados
Campo | Mensagem | Código Http |
codigo | Código informado não pode ser nulo ou vazio. | 400 – Bad Request |
O arquivo solicitado ainda não foi processado. Tente novamente mais tarde. | 400 – Bad Request | |
Verifique o código informado, não foram encontrados processos. | 404 – Not Found | |
Não foram encontrados arquivos com o codigo informado. | 404 – Not Found | |
O arquivo está vazio. Nenhum dado encontrado para os parâmetros informados. | 404 – Not Found |
11 Marcações
11.2 Marcações Cálculo
A funcionalidade de visualização de marcações com cálculos é composta por três etapas principais:
1ª Etapa: Criar o processo de visualizar as marcações
Inicie o processo enviando uma requisição com os dados dos funcionários e o período desejado. Esse passo gera um processo assíncrono de cálculo das marcações.
2ª Etapa: Acompanhar o progresso
Com o código retornado na criação do processo, acompanhe o progresso da geração. O sistema indicará a porcentagem de conclusão do cálculo.
3ª Etapa: Visualizar as marcações
Quando o processo estiver 100% concluído, utilize o mesmo código para acessar o resultado final com as marcações e cálculos aplicados.
11.2.1 Criar processo funcionário
Criar um novo processo de cálculo de marcações para um funcionário.
Endpoint
https://integracao.topponto.com.br/????
Estrutura
Método | Cabeçalho | Body |
POST | Content-Type: application/json X-Auth-Token: “token” X-Api-Version: 1 | JSON |
Parâmetros
Campo | Tipo | Restrição | Obrigatório | Descrição |
idFuncionario | Number | 1 a N (Número Positivo) ou NULL | Não | Identificador único do funcionario. |
idDepartamento | Number | 1 a N (Número Positivo) ou NULL | Não | Identificador único do departamento. |
idEmpresa | Number | 1 a N (Número Positivo) ou NULL | Não | Identificador único da Empresa. |
idEquipe | Number | 1 a N (Número Positivo) ou NULL | Não | Identificador único da Equipe |
dataInicio | String | Exatos 10 caracteres | Sim | Data de inicio do dados (formato DD/MM/AAAA). |
dataFim | String | Exatos 10 caracteres | Sim | Data final do dados (formato DD/MM/AAAA). |
Requisição (JSON)
{
"idFuncionario": 1,
"idDepartamento": null,
"idEmpresa": null,
"idEquipe": null,
"dataInicio": "01/01/2025",
"dataFim": "31/01/2025"
}
Resposta
{
"message": "Criado com sucesso.",
"body": {
"codigo": "d8a46ea0-2c11-444f-8d98-0957e9ab0f28",
"descricao": "INICIANDO_PROCESSO",
"dataAtualizacao": 1752769096213,
"progresso": 0.0
},
"status": 201
}
Erros catalogados
Campo | Mensagem | Código Http |
idFuncionario | O id do funcionário deve ser maior que 0. | 400 – Bad Request |
idEmpresa | O id da empresa deve ser maior que 0. | 400 – Bad Request |
idDepartamento | O id do departamento deve ser maior que 0. | 400 – Bad Request |
idEquipe | O id da equipe deve ser maior que 0. | 400 – Bad Request |
dataInicio | A data de início deve estar no formato dd/MM/yyyy e ser uma data válida. | 400 – Bad Request |
O data de início ultrapassou o limite definido. | 400 – Bad Request | |
A data de início não pode ser vazia. | 400 – Bad Request | |
dataFim | A data de fim deve estar no formato dd/MM/yyyy e ser uma data válida. | 400 – Bad Request |
A data de fim não pode ser vazia. | 400 – Bad Request | |
A data de fim ultrapassou o limite definido. | 400 – Bad Request | |
A data de fim não pode ser menor à data inicial. | 400 – Bad Request | |
dataInicio dataFim | O intervalo entre as datas excede o limite permitido de meses para consulta de marcações. | 400 – Bad Request |
11.2.2 – Criar processo funcionários.
Criar um novo processo de cálculo de marcações para uma lista de funcionário.
Endpoint
https://integracao.topponto.com.br/????
Estrutura
Método | Cabeçalho | Body |
POST | Content-Type: application/json X-Auth-Token: “token” X-Api-Version: 1 | JSON |
Parâmetros
Campo | Tipo | Restrição | Obrigatório | Descrição |
funcionarios | Array<Integer> | IDs de funcionários | Não | Lista de identificadores únicos dos funcionários. |
departamentos | Array<Integer> | IDs de departamentos | Não | Lista de identificadores únicos dos departamentos. |
empresas | Array<Integer> | IDs de empresas | Não | Lista de identificadores únicos das empresas. |
equipes | Array<Integer> | IDs de equipes | Não | Lista de identificadores únicos das equipes. |
dataInicio | String | Exatos 10 caracteres | Sim | Data de inicio do dados (formato DD/MM/AAAA). |
dataFim | String | Exatos 10 caracteres | Sim | Data final do dados (formato DD/MM/AAAA). |
Requisição (JSON)
{
"funcionarios": [1],
"departamentos": null,
"empresas": null,
"equipes": null,
"dataInicio": "01/01/2025",
"dataFim": "31/01/2025"
}
Resposta
{
"message": "Criado com sucesso.",
"body": {
"codigo": "d8a46ea0-2c11-444f-8d98-0957e9ab0f28",
"descricao": "INICIANDO_PROCESSO",
"dataAtualizacao": 1752769096213,
"progresso": 0.0
},
"status": 201
}
Erros catalogados
implementar
11.2.3 Consultar processo
Retorna o processo de calculo das marcações de acordo com o codigo
informado no endpoint — este codigo
é obtido na etapa 11.2.1 – Criar processo funcionário. ou na etapa 11.2.2 – Criar processo funcionários.
Durante a operação:
- O campo
descricao
refletirá o estado atual do processo, alternando entre mensagens como ??? e, ao final,"CONCLUIDO"
. - O campo
progresso
indicará o percentual de conclusão, aumentando gradativamente até atingir"progresso": 100.0
.
Quando o campo progresso
alcançar 100%, as marcações estaram prontas para serem solicitadas como descrito na etapa 11.2.3 – Consultar marcações calculo, utilizando o mesmo codigo
informado anteriormente.
Como se trata de um processo assíncrono, recomenda-se realizar consultas ao endpoint em intervalos de pelo menos 5 segundos, a fim de evitar sobrecarga no servidor por excesso de requisições.
Endpoint
https://integracao.topponto.com.br/???/codigo
Estrutura
Método | Cabeçalho | Path Variable |
GET | Content-Type: application/json X-Auth-Token: “token”X-Api-Version: 1 | Integer |
Parâmetros
Campo | Tipo | Restrição | Obrigatório | Descrição |
codigo | String | Gerado e retornado no processo de marcações. Não deve ser informado manualmente. | Sim | Identificador único do processo de marcações. |
Requisição (URL)
https://integracao.topponto.com.br/??/d8a46ea0-2c11-444f-8d98-0957e9ab0f28
Resposta
{
"message": "Consulta realizada com sucesso.",
"body": {
"codigo": "d8a46ea0-2c11-444f-8d98-0957e9ab0f28",
"descricao": "CALCULO_CONCLUIDO",
"dataAtualizacao": 1752769096213,
"progresso": 100.0
},
"status": 200
}
Erros catalogados
Campo | Mensagem | Código Http |
codigo | Processo cancelado, realize uma nova solicitação. | 200 – OK |
Código informado não pode ser nulo ou vazio. | 400 – Bad Request | |
Verifique o código informado, não foram encontrados processos. | 404 – Not Found |
11.2.3 Consultar Marcações
A partir do código, busca as marcações com os cálculos gerados correspondentes e retorna seu conteúdo diretamente na resposta da requisição.
Endpoint
https://integracao.topponto.com.br/???
Estrutura
Método | Cabeçalho | Path Variable |
GET | Content-Type: application/json X-Auth-Token: “token” X-Api-Version: 1 | Integer |
Parâmetros
Campo | Tipo | Restrição | Obrigatório | Descrição |
codigo | String | Gerado e retornado no processo de marcações. Não deve ser informado manualmente. | Sim | Identificador único do processo de marcações. |
Requisição (URL)
https://integracao.topponto.com.br/???/d8a46ea0-2c11-444f-8d98-0957e9ab0f28
Resposta
{
"message": "Consulta realizada com sucesso.",
"body": [
{
"funcionario": {
"idFuncionario": 1,
"nome": "NATALIA OLIVEIRA DA SILVA"
},
"marcacoes": [
{
"data": 1735700400000,
"dataFormatada": "01/01/2025",
"dataFormatadaDiaSemana": "01/01/2025 qua..",
"jornadasDeTrabalho": [],
"marcacoes": [],
"horasTrabalhadas": {
"diurnas": "00:00",
"noturnas": "00:00",
"total": "00:00"
},
"horasPrevistas": {
"diurnas": "00:00",
"noturnas": "00:00",
"total": "00:00"
},
"horasNormais": {
"diurnas": "00:00",
"noturnas": "00:00",
"total": "00:00"
},
"horasExtras": {
"diurnas": "00:00",
"noturnas": "00:00",
"total": "00:00"
},
"horasAusencias": {
"diurnas": "00:00",
"noturnas": "00:00",
"total": "00:00"
},
"bancoDeHoras": {
"credito": "00:00",
"debito": "00:00",
"saldo": "-22:-48"
},
"saldoDsr": {
"normal": {
"pagar": "00:00"
},
"ausencias": {
"acumulado": "00:00",
"desconto": "00:00"
},
"extras": {
"acumulado": "00:00",
"saldo": "00:00"
}
},
"abono": {
"totalHoras": "0"
},
"desconsideradas": [],
"observacoes": []
} ...
]
}
],
"status": 200
}
Erros catalogados
Campo | Mensagem | Código Http |
codigo | Código informado não pode ser nulo ou vazio. | 400 – Bad Request |
O arquivo solicitado ainda não foi processado. Tente novamente mais tarde. | 400 – Bad Request | |
Verifique o código informado, não foram encontrados processos. | 404 – Not Found | |
Não foram encontrados arquivos com o codigo informado. | 404 – Not Found | |
O arquivo está vazio. Nenhum dado encontrado para os parâmetros informados. | 404 – Not Found |
Mais páginas