11 Cálculos
A funcionalidade de visualização de marcações com cálculos é composta por três etapas principais:
1ª Etapa: Criar o processo de visualizar o cálculo das 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 o resultado do cálculo
Quando o processo estiver 100% concluído, utilize o mesmo código para acessar o resultado.
11.1.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/calculo/funcionario
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.1.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/calculo/funcionarios
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
| Campo | Mensagem | Código Http |
| 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 Acompanhar processo
Retorna o processo de calculo das marcações de acordo com o codigo informado no endpoint — este codigo é obtido nas etapas anteriores.
Durante a operação:
- O campo
descricaorefletirá o estado atual do processo, sendo seu último estado"CONCLUIDO". - O campo
progressoindicará o percentual de conclusão, aumentando gradativamente até atingir"progresso": 100.0.
Quando o campo progresso alcançar 100%, o resultado do cálculo estará pronto para ser solicitado conforme como descrito na etapa 11.3 – Consultar marcações calculo.
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/calculo/processo/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/calculo/processo/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.3 Cancelar processo
A partir do código, encerra o processo de cálculo caso ele ainda esteja em andamento.
Endpoint
https://integracao.topponto.com.br/calculo/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/calculo/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 |
11.4 Consultar
Retorna o resultado do cálculo, após concluído a partir do código e retorna seu conteúdo diretamente na resposta da requisição.
Endpoint
https://integracao.topponto.com.br/calculo/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/calculo/d8a46ea0-2c11-444f-8d98-0957e9ab0f28
Resposta
{
"message": "Consulta realizada com sucesso.",
"body": [
{
"funcionario": {
"idFuncionario": 1,
"nome": "Funcionario 1"
},
"calculoDia": [
{
"data": 1754265600000,
"dataFormatada": "04/08/2025",
"dataFormatadaDiaSemana": "04/08/2025 Seg.",
"jornadasDeTrabalho": [
{
"entrada": "08:00",
"saida": "12:00"
},
{
"entrada": "13:00",
"saida": "18:00"
}
],
"marcacoes": [
{
"marcacaoEntrada": {
"idMarcacao": 1,
"horario": "07:50",
"status": "Incluída"
},
"marcacaoSaida": {
"idMarcacao": 2,
"horario": "12:00",
"status": "Incluída"
},
"totalPeriodo": "04:10"
},
{
"marcacaoEntrada": {
"idMarcacao": 3,
"horario": "12:50",
"status": "Incluída"
},
"marcacaoSaida": {
"idMarcacao": 4,
"horario": "18:10",
"status": "Incluída"
},
"totalPeriodo": "05:20"
}
],
"horasTrabalhadas": {
"diurnas": "09:30",
"noturnas": "00:00",
"total": "09:30"
},
"horasPrevistas": {
"diurnas": "09:00",
"noturnas": "00:00",
"total": "09:00"
},
"horasNormais": {
"diurnas": "09:00",
"noturnas": "00:00",
"total": "09:00"
},
"horasExtras": {
"diurnas": "00:30",
"noturnas": "00:00",
"total": "00:30"
},
"horasAusencias": {
"diurnas": "00:00",
"noturnas": "00:00",
"total": "00:00"
},
"bancoDeHoras": {
"credito": "00:00",
"debito": "00:00",
"saldo": "00:00"
},
"saldoDsr": {
"normal": {
"pagar": "00:00"
},
"ausencias": {
"acumulado": "00:00",
"desconto": "00:00"
},
"extras": {
"acumulado": "00:00",
"saldo": "00:00"
}
},
"abono": {
"totalHoras": "--:--",
"motivo": null
},
"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 |