1. Home
  2. Integração com o TopPonto
  3. Protocolo Integração TopPonto

Protocolo Integração TopPonto

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étodoCabeçalhoBody
GETContent-Type: application/json X-Auth-Token: “token”X-Api-Version: 1JSON

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étodoCabeçalhoBody
POSTContent-Type: application/json X-Auth-Token: “token”X-Api-Version: 1JSON

Parâmetros

CampoTipoRestriçãoObrigatórioDescrição
idLayoutNumber1 a N (Número Positivo)SimIdentificador único do layout.
idFuncionarioNumber1 a N (Número Positivo) ou NULLNãoIdentificador único do funcionario.
idCeiNumber1 a N (Número Positivo) ou NULLNãoIdentificador único do cei.
idDepartamentoNumber1 a N (Número Positivo) ou NULLNãoIdentificador único do departamento.
idEmpresaNumber1 a N (Número Positivo) ou NULLNãoIdentificador único da Empresa.
empresaAtivaBooleantrue ou falseSimtrue para empresas ativas e false para todas.
departamentoAtivoBooleantrue ou falseSimtrue para deparatamentos ativos e false para todos.
funcionarioAtivoBooleantrue ou falseSimtrue para funcionarios ativos e false para todos.
dataExportacaoStringExatos 10 caracteresSimData de exportação do evento (formato DD/MM/AAAA), de acordo com a necessidade.
periodoInicioStringExatos 10 caracteresSimData de inicio do dados (formato DD/MM/AAAA).
periodoFimStringExatos 10 caracteresSimData 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

CampoMensagemCódigo Http
idLayoutO 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
idFuncionarioO 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
idCeiO id do cei deve ser maior que 0.400 – Bad Request
Cei não encontrado. Informe um id válido.404 – Not Found
idEmpresaO id da empresa deve ser maior que 0.400 – Bad Request
Empresa não encontrada. Informe um id válido.404 – Not Found
idDepartamentoO id do departamento deve ser maior que 0.400 – Bad Request
Departamento não encontrado. Informe um id válido.404 – Not Found
empresaAtivaO campo empresaAtiva não pode ser nulo.400 – Bad Request
departamentoAtivoO campo departamentoAtivo não pode ser nulo.400 – Bad Request
funcionarioAtivoO campo funcionarioAtivo não pode ser nulo.400 – Bad Request
dataExportacaoO 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/yyyy400 – Bad Request
periodoInicioO 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/yyyy400 – Bad Request
O período de inicio deve ser inferior ao período de fim.400 – Bad Request
periodoFimO 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/yyyy400 – Bad Request
periodoInicio periodoFimO 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étodoCabeçalhoPath Variable
GETContent-Type: application/json X-Auth-Token: “token”X-Api-Version: 1Integer

Parâmetros

CampoTipoRestriçãoObrigatórioDescrição
codigoStringGerado e retornado no processo de exportação. Não deve ser informado manualmente.SimIdentificador ú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

CampoMensagemCódigo Http
codigoProcesso 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étodoCabeçalhoPath Variable
DELETEContent-Type: application/json X-Auth-Token: “token”X-Api-Version: 1Integer

Parâmetros

CampoTipoRestriçãoObrigatórioDescrição
codigoStringGerado e retornado no processo de criação do processo.SimIdentificador ú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

CampoMensagemCódigo Http
codigoCó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étodoCabeçalhoPath Variable
GETContent-Type: application/json X-Auth-Token: “token”X-Api-Version: 1Integer

Parâmetros

CampoTipoRestriçãoObrigatórioDescrição
codigoStringGerado e retornado no processo de criação do processo.SimIdentificador ú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

CampoMensagemCódigo Http
codigoCó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étodoCabeçalhoBody
POSTContent-Type: application/json 
X-Auth-Token: “token”
X-Api-Version: 1
JSON

Parâmetros

CampoTipoRestriçãoObrigatórioDescrição
idFuncionarioNumber1 a N (Número Positivo) ou NULLNãoIdentificador único do funcionario.
idDepartamentoNumber1 a N (Número Positivo) ou NULLNãoIdentificador único do departamento.
idEmpresaNumber1 a N (Número Positivo) ou NULLNãoIdentificador único da Empresa.
idEquipeNumber1 a N (Número Positivo) ou NULLNãoIdentificador único da Equipe
dataInicioStringExatos 10 caracteresSimData de inicio do dados (formato DD/MM/AAAA).
dataFimStringExatos 10 caracteresSimData 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

CampoMensagemCódigo Http
idFuncionarioO id do funcionário deve ser maior que 0.400 – Bad Request
idEmpresaO id da empresa deve ser maior que 0.400 – Bad Request
idDepartamentoO id do departamento deve ser maior que 0.400 – Bad Request
idEquipeO id da equipe deve ser maior que 0.400 – Bad Request
dataInicioA 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
dataFimA 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étodoCabeçalhoBody
POSTContent-Type: application/json 
X-Auth-Token: “token”
X-Api-Version: 1
JSON

Parâmetros

CampoTipoRestriçãoObrigatórioDescrição
funcionariosArray<Integer>IDs de funcionáriosNãoLista de identificadores únicos dos funcionários.
departamentosArray<Integer>IDs de departamentosNãoLista de identificadores únicos dos departamentos.
empresasArray<Integer>IDs de empresasNãoLista de identificadores únicos das empresas.
equipesArray<Integer>IDs de equipesNãoLista de identificadores únicos das equipes.
dataInicioStringExatos 10 caracteresSimData de inicio do dados (formato DD/MM/AAAA).
dataFimStringExatos 10 caracteresSimData 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étodoCabeçalhoPath Variable
GETContent-Type: application/json X-Auth-Token: “token”X-Api-Version: 1Integer

Parâmetros

CampoTipoRestriçãoObrigatórioDescrição
codigoStringGerado e retornado no processo de marcações. Não deve ser informado manualmente.SimIdentificador ú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

CampoMensagemCódigo Http
codigoProcesso 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étodoCabeçalhoPath Variable
GETContent-Type: application/json 
X-Auth-Token: “token”
X-Api-Version: 1
Integer

Parâmetros

CampoTipoRestriçãoObrigatórioDescrição
codigoStringGerado e retornado no processo de marcações. Não deve ser informado manualmente.SimIdentificador ú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

CampoMensagemCódigo Http
codigoCó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

Mais Páginas

Introdução
Cadastros
Painel
Erros Catalogados


Páginas: 1 2 3 4 5
Esse artigo foi útil?